前端整理: 合并文件管理页 + 新增导航页

1. 合并 files-page 与 pdf-admin 为统一文件管理页 /api/files-page: - 新增 GET /api/admin/files/with-pdf 接口，以 uploaded_files 为基础，用 pdf_jobs.source_file_id / output_file_id 内存匹配，为关联文件标注转换状态、用户软删标记与角色(源epub/产物PDF) - PdfJobOut 补 source_file_id / output_file_id 字段 - file_browser 新增 PDF 任务列(状态徽标/软删标记/硬删任务按钮) - 删除 /api/pdf-admin 路由及 static/pdf_admin.* 三个文件 2. 新增导航页 /api/index，卡片式收集所有页面入口；各子页(upload/whiteboard/system_status/files-page)脚注加返回导航链接 3. 更新 docs/routes.md、docs/configuration.md 同步说明测试: pytest tests/test_pdf_service.py 7 passed; 手动校验各页面路由与合并接口响应
2026-07-28 14:04:12 +08:00
parent 9af28f41b4
commit 7c193ca46e
17 changed files with 275 additions and 289 deletions
--- a/app/controllers/file_admin_controller.py
+++ b/app/controllers/file_admin_controller.py
@@ -14,8 +14,15 @@ from pydantic import BaseModel, Field
 from sqlalchemy.orm import Session

 from ..database import get_db
+from ..dao.pdf_job_dao import PdfJobDAO
 from ..dao.uploaded_file_dao import UploadedFileDAO
-from ..schemas.file import FileListResponse, UploadedFileOut
+from ..schemas.file import (
+    FileListResponse,
+    FileWithPdfListResponse,
+    PdfJobBrief,
+    UploadedFileOut,
+    UploadedFileWithPdfOut,
+)
 from ..security import require_docs_auth
 from ..services.upload_service import UploadService

@@ -57,6 +64,53 @@ def list_files(
    return FileListResponse(total=total, items=items)


+@router.get(
+    "/with-pdf",
+    response_model=FileWithPdfListResponse,
+    summary="列出已上传文件并附带 PDF 转换任务关联（需鉴权）",
+    description=(
+        "合并管理页使用：以 uploaded_files 为基础分页拉取，再内存匹配 pdf_jobs，"
+        "为每个文件附带它作为 PDF 任务「源文件(epub)」或「产物(PDF)」时的状态、"
+        "进度与用户软删标记。匹配键为 pdf_job.source_file_id / output_file_id -> uploaded_file.id。"
+        "返回前会触发磁盘扫描（频率限制 3s），把 SFTP 上传但未入库的文件补录进来。"
+    ),
+)
+def list_files_with_pdf(
+    limit: int = Query(100, ge=1, le=10000, description="每页条数，1-10000"),
+    offset: int = Query(0, ge=0, description="偏移量"),
+    service: UploadService = Depends(_service),
+    db: Session = Depends(get_db),
+    _: str = Depends(require_docs_auth),
+) -> FileWithPdfListResponse:
+    service.scan_sftp_files()  # 频率限制内置：3s 内重复只返回 DB 缓存
+    total, items = service.list_files(limit=limit, offset=offset)
+
+    # 拉全部 pdf_jobs（数据量小，不分页），建反查 map
+    jobs = PdfJobDAO(db).list_all(limit=10000, offset=0)
+    by_source: dict[int, list] = {}
+    by_output: dict[int, list] = {}
+    for j in jobs:
+        by_source.setdefault(j.source_file_id, []).append(j)
+        if j.output_file_id is not None:
+            by_output.setdefault(j.output_file_id, []).append(j)
+
+    out_items: list[UploadedFileWithPdfOut] = []
+    for f in items:
+        briefs: list[PdfJobBrief] = []
+        for j in by_source.get(f.id, []):
+            briefs.append(PdfJobBrief(
+                job_id=j.id, role="source", status=j.status,
+                progress=j.progress, user_deleted=j.user_deleted, deleted_at=j.deleted_at,
+            ))
+        for j in by_output.get(f.id, []):
+            briefs.append(PdfJobBrief(
+                job_id=j.id, role="output", status=j.status,
+                progress=j.progress, user_deleted=j.user_deleted, deleted_at=j.deleted_at,
+            ))
+        out_items.append(UploadedFileWithPdfOut(**f.model_dump(), pdf_jobs=briefs))
+    return FileWithPdfListResponse(total=total, items=out_items)
+
+
@router.post(
    "/batch-delete",
    response_model=BatchDeleteResult,
--- a/app/main.py
+++ b/app/main.py
@@ -6,10 +6,11 @@
    GET  /redoc                  -> ReDoc       （Basic Auth）
    GET  /openapi.json           -> OpenAPI 文档（Basic Auth）
    GET  /health                 -> 存活探针（公开）
-    GET  /upload                 -> 上传页面（公开 HTML）
-    GET  /files                  -> 文件浏览页（Basic Auth，同 docs）
-    GET  /wb/{id}                -> 白板页面（公开，不存在则新建）
-    GET  /wb-admin               -> 白板管理页（Basic Auth，同 docs）
+    GET  /api/index              -> 导航页（公开，收集所有页面入口）
+    GET  /api/upload             -> 上传页面（公开 HTML）
+    GET  /api/files-page         -> 文件管理页（Basic Auth，同 docs；含 PDF 转换管理）
+    GET  /api/wb/{id}            -> 白板页面（公开，不存在则新建）
+    GET  /api/wb-admin           -> 白板管理页（Basic Auth，同 docs）
    GET  /api/...                -> 业务接口
    WS   /ws/wb/{id}             -> 白板实时同步（公开）
    /static/...                  -> 前端静态资源（JS/CSS）
@@ -183,6 +184,16 @@ def create_app() -> FastAPI:
    def health() -> dict:
        return {"status": "ok"}

+    @app.get(
+        "/api/index",
+        response_class=HTMLResponse,
+        tags=["pages"],
+        summary="导航页（公开）",
+        description="收集所有页面入口的卡片式导航页，各子页脚注可返回此处。",
+    )
+    def index_page() -> HTMLResponse:
+        return _serve_static_html("index.html")
+
    @app.get(
        "/api/upload",
        response_class=HTMLResponse,
@@ -197,8 +208,12 @@ def create_app() -> FastAPI:
        "/api/files-page",
        response_class=HTMLResponse,
        tags=["pages"],
-        summary="文件浏览页（需鉴权）",
-        description="列出 / 下载 / 删除已上传文件；支持多选、批量下载删除与分页。Basic Auth 同 docs。",
+        summary="文件管理页（需鉴权）",
+        description=(
+            "列出 / 下载 / 删除已上传文件，并合并 PDF 转换管理：以 uploaded_files 为基础，"
+            "用 pdf_jobs 匹配标注关联文件的转换状态、用户软删标记，可硬删任务。"
+            "支持多选、批量下载删除与分页。Basic Auth 同 docs。"
+        ),
    )
    def files_page(_: str = Depends(require_docs_auth)) -> HTMLResponse:
        return _serve_static_html("file_browser.html")
@@ -223,16 +238,6 @@ def create_app() -> FastAPI:
    def whiteboard_page(board_id: str) -> HTMLResponse:
        return _serve_static_html("whiteboard.html")

-    @app.get(
-        "/api/pdf-admin",
-        response_class=HTMLResponse,
-        tags=["pages"],
-        summary="PDF 转换管理页（需鉴权）",
-        description="查看全部转换任务（含用户已软删的，标注是否已删除），并可硬删。Basic Auth 同 docs。",
-    )
-    def pdf_admin_page(_: str = Depends(require_docs_auth)) -> HTMLResponse:
-        return _serve_static_html("pdf_admin.html")
-
    return app


--- a/app/schemas/file.py
+++ b/app/schemas/file.py
@@ -36,3 +36,31 @@ class FileUploadResponse(BaseModel):
 class FileListResponse(BaseModel):
    total: int
    items: list[UploadedFileOut]
+
+
+class PdfJobBrief(BaseModel):
+    """文件关联到的 PDF 转换任务摘要（供合并管理页展示）。
+
+    一个 uploaded_file 可能同时被多个 job 引用（罕见），故为列表；
+    通常每行 0 或 1 条。
+    """
+
+    job_id: int
+    role: str = Field(..., description='"source"=该文件是 epub 源文件；"output"=该文件是产物 PDF')
+    status: str = Field(..., description="pending / converting / done / failed")
+    progress: int = Field(0, description="转换进度 0-100")
+    user_deleted: bool = Field(False, description="用户是否已软删该任务")
+    deleted_at: datetime | None = Field(None, description="用户软删时间")
+
+
+class UploadedFileWithPdfOut(UploadedFileOut):
+    """带 PDF 任务关联信息的文件视图（合并管理页用）。"""
+
+    pdf_jobs: list[PdfJobBrief] = Field(default_factory=list, description="关联到的 PDF 转换任务")
+
+
+class FileWithPdfListResponse(BaseModel):
+    """合并管理页列表响应：以 uploaded_files 为基础，附带 pdf_jobs 关联。"""
+
+    total: int
+    items: list[UploadedFileWithPdfOut]
--- a/app/schemas/pdf.py
+++ b/app/schemas/pdf.py
@@ -11,8 +11,10 @@ class PdfJobOut(BaseModel):
    """任务对外视图（用户与管理页共用，user_deleted 仅管理页关注）。"""

    id: int
+    source_file_id: int = Field(..., description="原始 epub 文件的 uploaded_file.id")
    source_filename: str = Field(..., description="原始上传文件名")
    source_size: int = Field(..., description="原始文件字节数")
+    output_file_id: int | None = Field(None, description="产物 PDF 的 uploaded_file.id，转换完成前为 null")
    status: str = Field(..., description="pending / converting / done / failed")
    progress: int = Field(0, description="转换进度 0-100")
    error_message: str = Field("", description="失败原因")
--- a/app/views/system_status_html.py
+++ b/app/views/system_status_html.py
@@ -128,7 +128,7 @@ def render(status: SystemStatus) -> str:
  </table>
 </div>

-<p class="foot">zikai file service · 数据来源 psutil</p>
+<p class="foot"><a class="json" href="/api/index">导航</a> · zikai file service · 数据来源 psutil</p>
 </body>
 </html>
 """
--- a/app/views/upload_html.py
+++ b/app/views/upload_html.py
@@ -36,7 +36,7 @@ def render() -> str:

 <div id="summary" class="foot"></div>

-<p class="foot"><a class="json" href="/api/system/status">系统状态</a> · zikai file service</p>
+<p class="foot"><a class="json" href="/api/index">导航</a> · <a class="json" href="/api/system/status">系统状态</a> · zikai file service</p>

 <script>
 const CHUNK_SIZE = {DEFAULT_CHUNK_SIZE};