# 后端工程

## 分层结构

```
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 在生成提示词时执行合并。