86 lines
3.3 KiB
Markdown
86 lines
3.3 KiB
Markdown
# 后端工程
|
||
|
||
## 分层结构
|
||
|
||
```
|
||
backend/internal/
|
||
├── handler/ # HTTP handlers（薄层，只做参数绑定 + 调用 service）
|
||
│ ├── generate.go # 生成任务提交 / 查询 / WebSocket
|
||
│ ├── project_style.go # 工程风格 CRUD
|
||
│ └── health.go # [已有] 健康检查
|
||
├── service/ # 业务逻辑层
|
||
│ ├── pipeline.go # 核心管线：接收请求 → PromptBuilder → AssetGenerator → QualitySupervisor → FormatAdapter
|
||
│ ├── inference.go # AI 推理 API 调用封装（可替换模型提供商）
|
||
│ └── project_style.go # 工程风格管理 & 风格合并逻辑
|
||
├── model/ # 数据模型 / DTO
|
||
│ ├── response.go # [已有] 统一响应
|
||
│ ├── task.go # 生成任务 & 素材
|
||
│ └── style.go # 工程风格 & 任务风格覆盖
|
||
├── middleware/ # 中间件
|
||
│ ├── cors.go
|
||
│ ├── logger.go
|
||
│ └── ratelimit.go
|
||
├── config/ # [已有] 配置
|
||
│ └── config.go
|
||
├── queue/ # 异步任务队列
|
||
│ └── jobqueue.go
|
||
└── cache/ # 缓存层（请求去重 + 结果缓存）
|
||
└── cache.go
|
||
```
|
||
|
||
## 分层原则
|
||
|
||
- **handler**：只做参数绑定、校验、调用 service、返回响应。一个 handler 对应一组 API 路由。
|
||
- **service**：承载所有业务逻辑。`pipeline.go` 是唯一编排入口，不再拆分成 orchestrator/preprocess/generator/postprocess 四个文件——这些是同一根管线的顺序步骤，拆开反而增加耦合面。
|
||
- **model**：纯数据结构，不含业务逻辑。
|
||
|
||
## 关键实体
|
||
|
||
| 实体 | 说明 | 关系 |
|
||
|------|------|------|
|
||
| Project | 顶层容器，用户创建的项目 | 1──1 ProjectStyle, 1──N Task |
|
||
| ProjectStyle | 工程级键值对风格配置，保证同一工程下所有素材风格一致 | 属于 Project |
|
||
| Task | 工程下的单次生成请求，包含用户文本、素材类型、任务风格覆盖、技术参数、状态、结果 | 属于 Project, 1──N Asset |
|
||
| Prompt | PromptBuilder 输出的三段式提示词（主题+约束+内容），管线中间产物，不持久化 | 由 Task 生成 |
|
||
| Asset | 生成结果素材，关联到任务，包含 URL、元数据（分辨率、帧数、格式） | 属于 Task |
|
||
|
||
```
|
||
Project 1──1 ProjectStyle
|
||
Project 1──N Task
|
||
Task 1──N Asset
|
||
```
|
||
|
||
## 风格模型
|
||
|
||
### 工程风格（Project Style）
|
||
|
||
工程级别，保证同一工程下所有素材风格一致：
|
||
|
||
```go
|
||
type ProjectStyle struct {
|
||
ID string `json:"id"`
|
||
ProjectID string `json:"projectId"`
|
||
KVPairs map[string]string `json:"kvPairs"` // 如 {"artStyle":"pixel","palette":"warm"}
|
||
CreatedAt time.Time `json:"createdAt"`
|
||
UpdatedAt time.Time `json:"updatedAt"`
|
||
}
|
||
```
|
||
|
||
### 任务风格覆盖（Task Style Override）
|
||
|
||
任务级别，仅覆盖需要差异化的键：
|
||
|
||
```go
|
||
type TaskStyle struct {
|
||
KVPairs map[string]string `json:"kvPairs"` // 仅记录与工程风格不同的部分
|
||
}
|
||
```
|
||
|
||
### 合并逻辑
|
||
|
||
```
|
||
finalStyle = merge(projectStyle.KVPairs, taskStyle.KVPairs)
|
||
```
|
||
|
||
任务同名键覆盖工程风格，由 PromptBuilder 在生成提示词时执行合并。
|