refactor: 清理死代码/提前失败/日志/高内聚低耦合

死代码移除:
- whiteboard_hub.py: 移除未引用的 reset_hub 单例重置函数
- tunnel_service.py: 移除未引用的 is_port_allowed (逻辑已在 sftp_server 内联)
- tunnel_session_dao.py: 移除未引用的 get_active_by_port
- pdf_job_dao.py: 移除未用 datetime 导入
- pdf_converter.py: 移除未用 shutil 导入
- pdf_service.py: 移除未用 PdfSubmitResponse 导入 + _do_convert 内未用 hashlib 导入
- upload_html.py: 移除未用 escape 导入 (JS 侧自有 escapeHtml)
- pdf_controller.py: 移除 _resolve_cookie 内未用 cfg 局部变量

提前失败/分层修复:
- database.py init_db_schema: 建表后用 inspector 校验既有表列与模型一致,
  缺列即抛 RuntimeError (fail-fast on schema drift), 避免运行期才暴露
- whiteboard_dao.get_or_create: 仅 IntegrityError 才回滚重读, 其他异常向上抛
  (原 except Exception 会掩盖 schema/连接等真实故障)
- pdf_service.admin_delete/_safe_delete_file: 改用 PdfJobDAO.delete /
  UploadedFileDAO.delete, 不再直接操作 job_dao.db / file_dao.db (修复分层契约:
  DAO 头注释声明 service 不直接操作 session)
- PdfJobDAO 新增 delete(job) 方法

日志补全 (8 处 silent catch):
- whiteboard_hub.py disconnect/close_board 关闭 ws: logger.debug
- whiteboard_controller _safe_send/_safe_close: logger.debug
- sftp_server _close_tunnel_dao/读用户名: logger.debug
- sftp_server validate_public_key: logger.warning (auth 路径, 避免静默失败)

文档:
- 新增 docs/routes.md, docs/configuration.md, docs/error-handling.md
- README.md 精简为简介/结构/外部依赖/apache2 配置/Ubuntu 安装/docs 链接

app/dao/pdf_job_dao.py

@@ -6,8 +6,6 @@
 
 from __future__ import annotations
 
-from datetime import datetime
-
 from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 
@@ -33,6 +31,11 @@ class PdfJobDAO:
         self.db.refresh(job)
         return job
 
+    def delete(self, job: PdfJob) -> None:
+        """硬删 PdfJob 行（管理视角真正删除，不可恢复）。"""
+        self.db.delete(job)
+        self.db.commit()
+
     def list_for_user(self, owner_cookie: str, limit: int = 100, offset: int = 0) -> list[PdfJob]:
         """用户视角：仅未软删的任务，按创建时间倒序。"""
         stmt = (

app/dao/tunnel_session_dao.py

@@ -31,15 +31,6 @@ class TunnelSessionDAO:
         )
         return self.db.scalars(stmt).first()
 
-    def get_active_by_port(self, tunnel_port: int) -> TunnelSession | None:
-        stmt = (
-            select(TunnelSession)
-            .where(TunnelSession.tunnel_port == tunnel_port)
-            .where(TunnelSession.status == "active")
-            .limit(1)
-        )
-        return self.db.scalars(stmt).first()
-
     def list_active(self) -> list[TunnelSession]:
         stmt = select(TunnelSession).where(TunnelSession.status == "active")
         return list(self.db.scalars(stmt).all())

app/dao/whiteboard_dao.py

@@ -6,11 +6,16 @@ get_or_create 用于「访问即新建」语义（路由 GET /api/wb/{id} 不存
 
 from __future__ import annotations
 
+import logging
+
 from sqlalchemy import func, select
+from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 
 from ..models.whiteboard import Whiteboard
 
+logger = logging.getLogger("zikai.whiteboard")
+
 
 class WhiteboardDAO:
     def __init__(self, db: Session) -> None:
@@ -27,14 +32,18 @@ class WhiteboardDAO:
         return self.db.scalars(stmt).first()
 
     def get_or_create(self, board_id: str) -> Whiteboard:
-        """存在则返回，否则新建空板。利用 unique 约束兜底并发首访。"""
+        """存在则返回，否则新建空板。利用 unique 约束兜底并发首访。
+
+        仅 IntegrityError（并发下另一事务已插入违反唯一约束）才回滚重读；
+        其他异常向上抛，避免掩盖 schema/连接等真实故障。
+        """
         board = self.get(board_id)
         if board is not None:
             return board
         board = Whiteboard(board_id=board_id, content="", version=0, edit_count=0)
         try:
             return self.create(board)
-        except Exception:
+        except IntegrityError:
             # 并发下另一事务已插入：回滚后重新读
             self.db.rollback()
             return self.get(board_id)  # type: ignore[return-value]