gen2d/docs/backend.md

后端工程

分层结构

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）

工程级别，保证同一工程下所有素材风格一致：

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）

任务级别，仅覆盖需要差异化的键：

type TaskStyle struct {
    KVPairs map[string]string `json:"kvPairs"` // 仅记录与工程风格不同的部分
}

合并逻辑

finalStyle = merge(projectStyle.KVPairs, taskStyle.KVPairs)

任务同名键覆盖工程风格，由 PromptBuilder 在生成提示词时执行合并。