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; 手动校验各页面路由与合并接口响应
52 lines
3.8 KiB
Markdown
52 lines
3.8 KiB
Markdown
# 路由与访问入口
|
||
|
||
## 路由约定
|
||
|
||
**所有 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` |
|