diff --git a/app/controllers/file_admin_controller.py b/app/controllers/file_admin_controller.py
index 4caba02..10f4dc2 100644
--- 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,
diff --git a/app/main.py b/app/main.py
index 4ebed17..c29d3b5 100644
--- 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
diff --git a/app/schemas/file.py b/app/schemas/file.py
index 59ff262..6c61e20 100644
--- 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]
diff --git a/app/schemas/pdf.py b/app/schemas/pdf.py
index b3c9004..f17c666 100644
--- 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="失败原因")
diff --git a/app/views/system_status_html.py b/app/views/system_status_html.py
index 127326f..d19f7c3 100644
--- a/app/views/system_status_html.py
+++ b/app/views/system_status_html.py
@@ -128,7 +128,7 @@ def render(status: SystemStatus) -> str:
-
+