docs: 适配单机场景,简化存储与认证方案

- 数据库:MySQL → SQLite,去掉连接池配置和 golang-migrate
- 文件存储:OSS 对象存储 → 本地文件系统,统一 Gin 静态文件服务
- ID 生成:Sonyflake → 前缀+随机字符串
- 认证:Bearer Token → httpOnly Cookie,WebSocket 同步改为 Cookie 认证
- 质检重试:PromptBuilder 重试时注入 RejectReason 改进提示词
- 合并 multi-agent-pipeline.md 到 backend.md,消除文档重复
- 移除缓存管理 API(暴露内部实现细节)
This commit is contained in:
2026-05-24 10:56:40 +08:00
parent f4c1a10403
commit cbcda82515
7 changed files with 206 additions and 255 deletions
+7 -7
View File
@@ -20,7 +20,7 @@ stateDiagram-v2
|------|------|--------|
| `pending` | 已入队,等待 Worker 领取 | `task.status = 'pending'` |
| `running` | 管线执行中,`task.stage` 记录当前阶段 | `task.status = 'running'` |
| `completed` | 管线完成,素材已上传至 OSS | `task.status = 'completed'`, 写入 `asset` 表 |
| `completed` | 管线完成,素材已保存到本地 | `task.status = 'completed'`, 写入 `asset` 表 |
| `failed` | 执行失败或超过重试上限 | `task.status = 'failed'`, `task.error` 记录原因 |
## 任务队列
@@ -79,7 +79,7 @@ JobQueue.Pop() 取出 taskId
│ ├── AssetGenerator → stage 更新
│ ├── QualitySupervisor → stage 更新(可能触发重试分支)
│ └── FormatAdapter → stage 更新
├── 5. 上传素材至 OSS,写入 asset 表
├── 5. 保存素材到本地,写入 asset 表
├── 6. 更新 task.status = completed
└── 7. 异常时更新 task.status = failed, task.error = 错误信息
```
@@ -128,7 +128,7 @@ func (s *TaskService) StartWorkers(n int) {
| 提示词构建 | `prompt_builder` | 0-20% | 合并风格,生成三段式提示词 |
| 素材生成 | `asset_generator` | 20-60% | 调用 AI 推理 API 出图 |
| 质量检查 | `quality_supervisor` | 60-80% | 视觉模型质检 |
| 格式适配 | `format_adapter` | 80-100% | 格式转换、spritesheet 打包、上传 OSS |
| 格式适配 | `format_adapter` | 80-100% | 格式转换、spritesheet 打包、保存素材 |
进度更新通过 WebSocket 实时推送给前端(参见 [API 设计 - WebSocket 消息格式](api.md))。
@@ -152,7 +152,7 @@ QualitySupervisor -- pass --> FormatAdapter
### 任务级重试(管线外重试)
管线执行过程中发生不可恢复的错误(如 AI API 超时、OSS 上传失败):
管线执行过程中发生不可恢复的错误(如 AI API 超时、文件写入失败):
| 参数 | 默认值 | 说明 |
|------|--------|------|
@@ -176,10 +176,10 @@ GET /api/v1/tasks/:taskId
### WebSocket
```
ws://host/api/v1/tasks/:taskId/ws?token=<jwt>
ws://host/api/v1/tasks/:taskId/ws
```
长连接实时推送,每个阶段的状态变更立即通知前端。消息格式参见 [API 设计](api.md)。
长连接实时推送,通过 httpOnly Cookie 自动认证,每个阶段的状态变更立即通知前端。消息格式参见 [API 设计](api.md)。
## 去重
@@ -187,4 +187,4 @@ ws://host/api/v1/tasks/:taskId/ws?token=<jwt>
## 文件存储
任务完成后,FormatAdapter 将素材上传至 OSS。素材文件的存储结构与访问方式详见 [数据存储 — 文件存储](database.md#文件存储)。
任务完成后,FormatAdapter 将素材保存到本地文件系统。素材文件的存储结构与访问方式详见 [数据存储 — 文件存储](database.md#文件存储)。