Merge branch 'develop' of gitee.com:hezhaohui123/gen2d into feat/async-generate-pipeline

Signed-off-by: 何朝晖 <hezhaohui0807@163.com>

docs/backend.md

@@ -14,32 +14,32 @@ backend/internal/
 │   ├── health.go         # [已有] 健康检查
 │   ├── register.go       # [已有] 用户注册（handler 骨架 + 参数校验）
 │   ├── login.go          # [已有] 用户登录（handler 骨架 + 参数校验）
-│   ├── project.go        # 工程 CRUD + 任务列表
-│   ├── generate.go       # 生成任务提交 / 查询 / WebSocket
-│   └── project_style.go  # 工程风格 CRUD
+│   ├── generate.go       # [已有] 素材生成（异步管线 + 任务查询）
+│   ├── edit.go           # [已有] 图片编辑
+│   ├── prompt.go         # [已有] 提示词优化
+│   └── storage.go        # [已有] 素材下载（重定向到七牛云 CDN）
 ├── service/              # 业务逻辑层
 │   ├── pipeline.go       # [已有] Eino compose.Graph 编排：PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter
 │   ├── nodes.go          # [已有] 管线四个节点的实现（每个节点单一职责）
 │   ├── types.go          # [已有] 管线输入/状态/输出的显式结构体定义
-│   ├── inference.go      # [已有] AI 推理 API 调用封装（当前为 mock 实现）
+│   ├── inference.go      # [已有] AI 推理 API 调用封装（文生图 + 图片编辑）
+│   ├── prompt_agent.go   # [已有] LLM 提示词优化 Agent
 │   ├── pipeline_test.go  # [已有] 管线测试（happy path / 重试 / 降级 / 风格合并）
-│   ├── auth.go           # 用户认证：注册、登录、JWT 签发与校验
-│   └── project_style.go  # 工程风格管理 & 风格合并逻辑
+│   ├── auth.go           # [已有] 用户认证：注册、登录、JWT 签发与校验
+│   └── storage.go        # [已有] 七牛云对象存储：上传、下载 URL 生成、删除
 ├── model/                # 数据模型 / DTO
 │   ├── response.go       # [已有] 统一响应
-│   ├── user.go           # [已有] 用户模型
-│   ├── task.go           # 生成任务 & 素材
-│   └── style.go          # 工程风格 & 任务风格覆盖
-├── middleware/            # 中间件
-│   ├── logger.go
-│   ├── auth.go           # JWT 认证中间件（从 Cookie 读取 Token）
-│   └── ratelimit.go
+│   └── user.go           # [已有] 用户模型
+├── mildware/             # 中间件
+│   ├── logger.go         # [已有] 请求日志 + Panic 恢复中间件（基于 slog）
+│   └── auth.go           # [已有] JWT 认证中间件
+├── logger/               # [已有] 日志包（基于 log/slog）
+│   └── logger.go         # 日志初始化、全局 logger、context 注入
 ├── config/               # [已有] 配置
-│   └── config.go
-├── queue/                # 异步任务队列
-│   └── jobqueue.go
-└── cache/                # 缓存层（请求去重）
-    └── cache.go
+│   ├── config.go
+│   └── config.yml
+└── db/                   # [已有] 数据库初始化
+    └── db.go
 ```
 
 ## 分层原则
@@ -48,6 +48,46 @@ backend/internal/
 - **service**：承载所有业务逻辑。`pipeline.go` 通过 Eino `compose.Graph` 编排四个节点；`nodes.go` 实现各节点逻辑；`types.go` 定义显式状态结构体。
 - **model**：纯数据结构，不含业务逻辑。
 
+## 日志系统
+
+基于 Go 标准库 `log/slog`，无需第三方依赖。
+
+### 核心组件
+
+- **`internal/logger/logger.go`**：日志初始化与 context 注入
+  - `Init(level, format)` — 初始化全局 logger（level: debug/info/warn/error，format: text/json）
+  - `FromCtx(ctx)` — 从 context 提取带 request_id 的 logger
+  - `WithRequestID(ctx, id)` — 创建带 request_id 的 logger 并存入 context
+
+- **`internal/mildware/logger.go`**：HTTP 请求日志 + Panic 恢复中间件
+  - `Logger()` — 为每个请求生成 request_id（注入 header `X-Request-ID`），记录 method/path/status/latency/client_ip
+  - `Recovery()` — 自定义 panic 恢复，记录 request 上下文和堆栈
+
+### 日志级别使用规范
+
+| 级别 | 场景 |
+|------|------|
+| Debug | 开发调试信息 |
+| Info | 正常业务流程（API 调用、任务完成等） |
+| Warn | 可恢复的异常（认证失败、LLM 回退模板等） |
+| Error | 不可恢复的错误（API 调用失败、数据库错误等） |
+
+### 配置
+
+```yaml
+log:
+  level: info    # debug / info / warn / error
+  format: text   # text（开发）/ json（生产）
+```
+
+环境变量：`GEN2D_LOG_LEVEL`、`GEN2D_LOG_FORMAT`
+
+### 错误处理原则
+
+- 服务端错误（5xx）：先用 `slog.Error` 记录完整错误（含 request_id），返回客户端通用描述
+- 客户端错误（4xx）：用 `slog.Warn` 记录，返回具体提示
+- 内部错误细节不泄露给客户端
+
 ## 多阶段生成管线
 
 gen2d 的核心生成流程采用 Eino `compose.Graph` 编排的三阶段管线，含质检不通过时的重优化分支。
@@ -106,7 +146,7 @@ finalStyle = merge(projectStyle.KVPairs, taskStyle.KVPairs)
 
 - **输入**：通过质检的图片 + 素材类型
 - **输出**：游戏引擎可用的素材文件 + 元数据
-- **职责**：格式转换、spritesheet 打包、元数据生成。
+- **职责**：格式转换、spritesheet 打包、元数据生成、上传素材到七牛云对象存储。
 - **示例**：输入 4 张 64×64 的角色行走帧 PNG → 输出一张 256×64 的 spritesheet + JSON 元数据（帧尺寸、帧数、锚点偏移），可直接拖入 Unity 2D Animation 使用。
 
 ---