zikai/zTools2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
refactor/cleanup-failfast
zTools2/docs/routes.md
zikai 7c193ca46e 前端整理: 合并文件管理页 + 新增导航页 
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

3.8 KiB
Raw Permalink Blame History

路由与访问入口

路由约定

所有 zTools2 托管的入口（页面 / 静态资源 / 健康探针 / WebSocket / REST API）统一挂在 /api/ 前缀下，只有元信息/文档例外（/、/docs、/redoc、/openapi.json）。这样反向代理与 vite dev proxy 都只需一条 /api/ 规则即可把请求转给当前环境的 zTools2，前端用同源相对路径（如 /api/pdf/jobs、/api/health）即可，与运行环境（本地 / 测试 / 生产）无关，无需区分 dev/prod 指向。

PDF 转换的用户侧 UI 由 zMainPage 的 zPDF_package 组件提供（构建期 import，非 iframe）；zTools2 仅提供 /api/pdf/jobs 等 REST API。PDF 转换管理（查看全部任务含软删标记、硬删）已并入文件管理页 /api/files-page。

页面类入口为避免与同名 REST API 冲突，统一加 -page 后缀：

类型 页面入口 REST API（同名不加后缀）
文件管理 GET /api/files-page GET /api/files、/api/files/{id} 等
记事本 GET /api/wb-page/{id} GET /api/wb/{id}

其余入口：/api/index（导航页）、/api/health（探针）、/api/static/*（JS/CSS）、/api/ws/wb/{id}（WebSocket）、/api/upload、/api/wb-admin。

功能一览

模块 页面 / 接口 鉴权
导航页 GET /api/index（卡片式入口索引，各子页可返回） 公开
文件上传 POST /api/files/upload（流式）/ POST /api/files/chunk-uploads/*（分片+断点续传） 公开
上传页 GET /api/upload（拖拽/多文件/分片/去重） 公开
文件管理 GET /api/files-page（多选/批量下载删除/分页，合并 PDF 转换管理：状态、软删标记、硬删任务） Basic Auth
文件管理 API GET /api/admin/files、GET /api/admin/files/with-pdf（合并视图，附带 pdf_jobs 关联）、GET/DELETE /api/admin/files/{id}、GET /api/admin/files/{id}/download Basic Auth
共享记事本 GET /api/wb-page/{id}（公开，不存在则新建） 公开
记事本实时同步 WS /api/ws/wb/{id}（心跳 3s，5 次失活移除） 公开
记事本管理 GET /api/wb-admin（查看/删除） Basic Auth
记事本管理 API GET /api/admin/wb、DELETE /api/admin/wb/{id} Basic Auth
PDF 转换 API POST /api/pdf/jobs、GET /api/pdf/jobs[/{id}]、GET /api/pdf/jobs/{id}/download、DELETE /api/pdf/jobs/{id} 公开（cookie）
PDF 转换管理 API GET /api/admin/pdf/jobs、DELETE /api/admin/pdf/jobs/{id}（管理入口已并入 /api/files-page） Basic Auth
主机监控 GET /api/system/status（CPU/内存/磁盘，HTML+JSON 内容协商） 公开
反向隧道反代 ALL /api/userPort/{userName}（经 SSH 隧道转发到 user 本地服务） 公开
SFTP/SSH 端口 2022（密码+公钥，chroot 到上传目录，承载隧道转发） SSH
API 文档 GET /docs（Swagger）/ GET /redoc Basic Auth

访问入口

入口 URL
导航页 https://f.zikai.wang/api/index
API 文档 https://f.zikai.wang/docs（Basic Auth）
上传页 https://f.zikai.wang/api/upload
文件管理 https://f.zikai.wang/api/files-page（Basic Auth，含 PDF 转换管理）
共享记事本 https://f.zikai.wang/api/wb-page/{id}（公开，{id} 为 [a-zA-Z0-9_-]{1,64}）
记事本管理 https://f.zikai.wang/api/wb-admin（Basic Auth）
PDF 转换 经 zMainPage 的 PDF 页签（zPDF_package 组件）调用 /api/pdf/jobs 等 REST API（公开，凭 cookie）
系统状态 https://f.zikai.wang/api/system/status（HTML，?format=json 切 JSON）
curl 上传 curl -F file=@big.iso https://f.zikai.wang/api/files/upload
SFTP sftp -P 2022 uploader@f.zikai.wang