feat(export): 交付 Markdown → HTML 导出服务

实现 Export Service 完整生命周期:mistune AST → Document AST → HtmlExporter 渲染完整 HTML5,异步任务注册表 + 取消 + 24h 产物过期。新增 5 个 /api/exports 端点与 15 项测试;pdf/docx 与函数图像静态渲染留待后续 PR。
This commit is contained in:
yxx
2026-09-04 09:02:33 +08:00
parent 2e496462a9
commit 5c2441464d
18 changed files with 1358 additions and 17 deletions
@@ -66,11 +66,11 @@
| Benchmark | POST | `/api/benchmarks/agent/runs` | 暂缓 | 创建 Agent Benchmark(依赖 Agent Runtime 完成后交付) |
| Benchmark | GET | `/api/benchmarks/runs` | 已实现 | 分页获取 Benchmark Run |
| Benchmark | GET/POST | `/api/benchmarks/runs/{run_id}/*` | 计划新增 | 查询、订阅、取消和读取报告 |
| Export | POST | `/api/exports` | 计划新增 | 创建 HTML/PDF/DOCX 导出任务 |
| Export | GET | `/api/exports` | 计划新增 | 分页获取导出任务 |
| Export | GET | `/api/exports/{job_id}` | 计划新增 | 查询导出任务 |
| Export | GET | `/api/exports/{job_id}/file` | 计划新增 | 下载已完成产物 |
| Export | POST | `/api/exports/{job_id}/cancel` | 计划新增 | 取消导出任务 |
| Export | POST | `/api/exports` | 已实现(HTML | 创建导出任务;`pdf`/`docx` 暂缓,返回 `EXPORT_FORMAT_UNSUPPORTED` |
| Export | GET | `/api/exports` | 已实现(HTML | 分页获取导出任务 |
| Export | GET | `/api/exports/{job_id}` | 已实现(HTML | 查询导出任务 |
| Export | GET | `/api/exports/{job_id}/file` | 已实现(HTML | 下载已完成产物 |
| Export | POST | `/api/exports/{job_id}/cancel` | 已实现(HTML | 取消导出任务 |
| Theme | Host Contract | `ThemePackageService` | 计划新增 | 导入、预览、启停和卸载主题包 |
| Renderer | 内部 Contract | `StaticRenderer` | 计划新增 | Mermaid/Function Plot 预览和导出复用 |
@@ -1078,6 +1078,8 @@ VECTOR_INDEX_REBUILD_REQUIRED
## 10. Export Service
> 实现状态:HTML 导出已实现(`backend/app/export/`),`pdf`/`docx` 暂缓——请求这两个格式返回 `EXPORT_FORMAT_UNSUPPORTED`。函数图像与 Mermaid 在 HTML 中以占位代码块保留并记 warning,静态渲染由 §10.4 的 Render Contract 在后续 PR 补齐。
### 10.1 创建导出任务
`POST /api/exports`,返回 `202 ExportJob`
@@ -1088,7 +1090,7 @@ VECTOR_INDEX_REBUILD_REQUIRED
"type": "note",
"note_id": "note_123"
},
"format": "pdf",
"format": "html",
"options": {
"theme_id": "light",
"include_title": true,
@@ -1099,7 +1101,7 @@ VECTOR_INDEX_REBUILD_REQUIRED
}
```
`source.type` 首批支持 `note``markdown``markdown` 来源用于尚未保存的预览,字段大小受限且不持久化到 Trace。`format` 固定为 `html``pdf``docx`
`source.type` 首批支持 `note``markdown``note` 来源通过 `source.note_id` 引用已建索引笔记;`markdown` 来源用于尚未保存的预览,内容放在 `source.markdown` 字段大小限制为 200 000 字符、不持久化到 Trace。`format` 可取 `html``pdf``docx`,但当前仅 `html` 已实现,`pdf`/`docx` 返回 `EXPORT_FORMAT_UNSUPPORTED`
响应:
@@ -1107,11 +1109,12 @@ VECTOR_INDEX_REBUILD_REQUIRED
{
"job_id": "export_123",
"status": "queued",
"format": "pdf",
"format": "html",
"progress": null,
"file": null,
"warnings": [],
"error": null,
"error_code": null,
"created_at": "2026-08-31T10:30:00Z",
"started_at": null,
"completed_at": null
@@ -1127,14 +1130,14 @@ VECTOR_INDEX_REBUILD_REQUIRED
| POST | `/api/exports/{job_id}/cancel` | `OperationResponse` |
| GET | `/api/exports/{job_id}/file` | 文件流 |
下载响应设置正确 `Content-Type`、经过清理的 `Content-Disposition` 文件名和 `Content-Length`。未完成、失败或过期 Job 不返回空文件。
下载响应设置正确 `Content-Type`、经过清理的 `Content-Disposition` 文件名和 `Content-Length`。未完成、失败或过期 Job 不返回空文件:未完成/失败返回 `EXPORT_JOB_NOT_FOUND`404),产物过期(超过 `expires_at`)返回 `EXPORT_FILE_EXPIRED`410
完成 Job 的 file
```json
{
"file_name": "操作系统复习.pdf",
"mime_type": "application/pdf",
"file_name": "操作系统复习.html",
"mime_type": "text/html",
"size": 1048576,
"sha256": "...",
"expires_at": "2026-09-01T10:30:00Z"