docs: 交叉检查修复文档疏漏与不一致

- 修复 api.md 修改密码接口混入注册场景的 409 错误
- 补充 api.md WebSocket 示例缺失的 quality_supervisor running 消息
- 补充 api.md 注册接口格式校验错误响应、缓存接口详细说明
- 补充 frontend.md Task 接口缺失的 error 字段
- 补充 frontend.md 错误处理章节(API 错误、WebSocket 断连、加载状态)
- frontend.md 风格键表改为引用 style-keys.md,消除重复
- async-tasks.md 去重/文件存储改为引用 database.md,消除重复
- backend.md ER 图改为引用 database.md,消除重复
- 补充 backend.md 目录结构中缺失的 auth/project handler 和 user model
- 补充 backend.md 缓存层设计说明
- 补充 database.md GEN2D_SERVER_PORT 环境变量和迁移文件归属说明
- 补充 multi-agent-pipeline.md 到 backend.md 和 async-tasks.md 的交叉引用
- 补充 async-tasks.md 超时控制说明
This commit is contained in:
2026-05-24 10:47:00 +08:00
parent 5a6bcaffaf
commit f4c1a10403
6 changed files with 102 additions and 37 deletions
+15 -6
View File
@@ -11,10 +11,13 @@
```
backend/internal/
├── handler/ # HTTP handlers(薄层,只做参数绑定 + 调用 service)
│ ├── auth.go # 用户注册 / 登录 / 当前用户 / 修改密码
│ ├── project.go # 工程 CRUD + 任务列表
│ ├── generate.go # 生成任务提交 / 查询 / WebSocket
│ ├── project_style.go # 工程风格 CRUD
│ └── health.go # [已有] 健康检查
├── service/ # 业务逻辑层
│ ├── auth.go # 用户认证:注册、登录、JWT 签发与校验
│ ├── pipeline.go # Eino compose.Graph 编排:PromptBuilder → AssetGenerator → QualitySupervisor → FormatAdapter
│ ├── nodes.go # 管线四个节点的实现(每个节点单一职责)
│ ├── types.go # 管线输入/状态/输出的显式结构体定义
@@ -22,10 +25,12 @@ backend/internal/
│ └── project_style.go # 工程风格管理 & 风格合并逻辑
├── model/ # 数据模型 / DTO
│ ├── response.go # [已有] 统一响应
│ ├── user.go # 用户模型
│ ├── task.go # 生成任务 & 素材
│ └── style.go # 工程风格 & 任务风格覆盖
├── middleware/ # 中间件
│ ├── logger.go
│ ├── auth.go # JWT 认证中间件
│ └── ratelimit.go
├── config/ # [已有] 配置
│ └── config.go
@@ -194,12 +199,7 @@ func RunPipeline(ctx context.Context, in PipelineInput) (*PipelineOutput, error)
| Prompt | PromptBuilder 输出的三段式提示词(主题+约束+内容),管线中间产物,不持久化 | 由 Task 生成 |
| Asset | 生成结果素材,关联到任务,包含 URL、元数据(分辨率、帧数、格式) | 属于 Task |
```mermaid
erDiagram
Project ||--|| ProjectStyle : has
Project ||--|{ Task : has
Task ||--|{ Asset : has
```
ER 关系图与外键约束详见 [数据存储 — ER 关系](database.md#er-关系)。
## 风格模型
@@ -234,3 +234,12 @@ finalStyle = merge(projectStyle.KVPairs, taskStyle.KVPairs)
```
任务同名键覆盖工程风格,由 PromptBuilder 节点在生成提示词时执行合并。
## 缓存层
`cache/cache.go` 提供应用内存级缓存,主要用于请求去重(详见 [数据存储 — 去重策略](database.md#去重策略)):
- **数据结构**:`sync.Map`,key 为 `hash(prompt + assetType + params)`,value 为 taskId
- **生命周期**:任务提交时写入,任务完成或失败后清除;可设置 TTL 过期兜底
- **作用域**:单实例内存,不跨实例共享
- **接口**:提供 `Get`/`Set`/`Delete`/`Clear` 方法,同时供 handler 层(缓存管理 API)和 service 层(去重检查)调用