vault backup: 2026-06-04 09:33:09

hzh/Gen2D/00-索引.md

@@ -32,10 +32,11 @@ create time: 2026-06-03 09:00
 | 13 | [[13-标签驱动提示词工程]] | 标签驱动提示词 | 40+ 标签映射 + 风格一致性 |
 | 14 | [[14-部署架构]] | 部署架构 | Docker Compose + Prometheus + Grafana |
 | 15 | [[15-配置级联机制]] | 配置级联 | Viper 三层配置：YAML → ENV → Default |
+| 16 | [[QA]] | 答辩问答 | 30 个架构相关 Q&A，按模块分布 |
 
 > [!tip] 阅读顺序建议
 >
-> 建议按编号顺序阅读：先理解 [[01-系统总览]] 的全局架构，再深入各个具体组件（协程池、任务队列、RabbitMQ），最后学习运行时相关话题（SSE 推送、可观测性、降级策略）。
+> 建议按编号顺序阅读：先理解 [[01-系统总览]] 的全局架构，再深入各个具体组件（协程池、任务队列、RabbitMQ），最后学习运行时相关话题（SSE 推送、可观测性、降级策略）。[[QA]] 可作为答辩准备参考。
 
 ### 架构总览图
 

hzh/Gen2D/QA.md

@@ -0,0 +1,159 @@
+# Gen2D — Q&A
+
+> 按模块分布编排，贴近实际答辩场景。每个 Answer 已精简适配 PPT 展示。
+
+---
+
+## 一、系统架构（Q1–Q4）
+
+**Q1：Gen2D 的整体架构是什么？**
+
+A：采用经典分层架构，从浏览器请求到外部依赖共六层：Gin HTTP Server → Handler → Service 层（Eino Pipeline）→ 基础设施层（协程池/队列/事件总线）→ 领域模型 → 外部依赖（MySQL/Redis/CDN/AI API）。各层职责清晰、可独立替换。
+
+**Q2：为什么选择异步任务 + SSE 推送的组合？**
+
+A：AI 生成耗时 10~120 秒，如果同步调用会耗尽服务器连接。异步提交让 API 快速返回 taskId，后续通过 SSE 长连接推送进度，客户端可以自由离开并在后台接收更新。
+
+**Q3：系统的依赖注入方式是什么？为什么没有使用 Wire/Fx 等框架？**
+
+A：采用轻量级的 Set*/Init* 函数注入，在 main.go 中约 220 行完成全部注入。项目规模可控，框架级 DI 的复杂度收益比不高。
+
+**Q4：配置管理是如何设计的？**
+
+A：使用 Viper 实现三层级联：环境变量 > YAML 配置文件 > 代码默认值。容器化部署时可通过环境变量覆盖，开发时使用 YAML 集中管理，零配置也可启动运行。
+
+---
+
+## 二、并发控制与协程池（Q5–Q8）
+
+**Q5：协程池的核心参数和默认值是什么？**
+
+A：Worker 数量 = NumCPU × 4，任务队列容量 = 100，单用户最大并发数 = 2。IO 密集型场景推荐 4 倍 CPU 核数。
+
+**Q6：什么是背压保护？Gen2D 为什么选择非阻塞拒绝而不是阻塞等待？**
+
+A：当协程池队列满时立即返回 ErrPoolFull 错误并返回 HTTP 503，而不是等待有空位。因为用户期望快速反馈，且 AI 生成场景中用户可以重新点击提交——这种短暂的操作成本远低于服务器因连接堆积导致的雪崩风险。
+
+**Q7：Per-user 限流的作用和实现机制是什么？**
+
+A：防止单个用户占满整个协程池。实现上在 Submit 时就增加 userActive 计数预留槽位，任务完成后释放。这样即使 channel 还未取出任务，也能保证槽位一致性。
+
+**Q8：协程池如何优雅关闭？**
+
+A：收到 SIGINT/SIGTERM 信号后，先停止接受新任务（consumeCancel），再通过 wg.Wait 等待所有正在执行的 Worker 完成，超时时间为 30 秒。超时则部分任务可能丢失。
+
+---
+
+## 三、任务队列（Q9–Q11）
+
+**Q9：任务队列的可插拔设计是什么意思？**
+
+A：定义了统一的 TaskQueue 接口（Submit/Consume/Close），支持 MemoryQueue 和 RabbitMQQueue 两种实现。通过配置中的 `driver` 字段一行切换，单机开发用内存队列，生产环境用 RabbitMQ。
+
+**Q10：MemoryQueue 和 RabbitMQQueue 的主要区别是什么？**
+
+A：MemoryQueue 零依赖但无持久化和重试，进程重启任务丢失；RabbitMQQueue 消息持久化到磁盘、支持失败重试和手动 ACK，适合多机部署的生产环境。
+
+**Q11：任务消息的结构中包含哪些关键字段？**
+
+A：包含 TaskID、UserID、ProjectID、Input（PipelineInput）、CreatedAt 和 RetryCount。其中 Input 直接嵌入管线输入结构，反序列化后可直接传入；RetryCount 用于判断是否超过最大重试次数。
+
+---
+
+## 四、生成管线（Q12–Q16）
+
+**Q12：生成管线的四个阶段分别是什么？**
+
+A：第一阶段 PromptOptimizer（提示词优化，纯 CPU <1ms），第二阶段 AssetGenerator（AI 出图，IO 密集 10-120s），第三阶段 QualitySupervisor（质量检查 1-5s），第四阶段 FormatAdapter（格式适配/Cut/GIF 1-3s）。
+
+**Q13：质量检测最多重试 3 次的策略依据是什么？**
+
+A：第 1 次失败通常是 LLM 波动或偶发噪声，重试大概率通过；第 2 次失败说明提示词不够精确，重新优化后改善；第 3 次仍失败表示当前参数确实无法生成合格图片。超过 3 次降级到 FormatAdapter——宁可降级不可阻塞。
+
+**Q14：AssetGenerator 的三级回退逻辑是什么？**
+
+A：优先使用任务级参考图进行图生图，其次使用工程级参考图 URL 下载后图生图，最后回退到纯文生图。任意一级失败都尝试下一级，确保任务不阻塞。
+
+**Q15：管线的安全机制有哪些？**
+
+A：包括三个层面——Eino Graph 设置 WithMaxRunSteps(20) 防止无限循环，WorkerPool 设置 context.WithTimeout(10min) 控制任务超时，以及 context.Canceled 支持优雅关闭时取消执行中的管线。
+
+**Q16：管线的全局状态是怎么管理的？**
+
+A：通过 Eino 的 WithGenLocalState 注入 PipelineState 全局状态对象，各节点通过 StatePreHandler / StatePostHandler 读写状态。状态包含原始输入、最终提示词、质检结果、重试次数和路由目标。
+
+---
+
+## 五、精灵图处理（Q17–Q19）
+
+**Q17：精灵图处理管线包含哪几个步骤？**
+
+A：背景移除（白底/绿幕）→ 投影检测分割 → MinFillRatio 过滤空白帧 → trimAlpha 裁剪透明边框 → padToLargest 底部居中对齐 → GIF 预览生成。
+
+**Q18：两阶段投影算法相比传统方法有什么优势？**
+
+A：传统全局投影会因为武器、尾巴、翅膀等突出物被其他行"稀释"导致切割不准。两阶段算法先用全局行投影检测水平间隙，再在每个行段内独立计算列密度——相当于把二维问题拆解为多个一维子问题，避免跨行干扰。
+
+**Q19：GIF Maker 的防鬼影机制如何实现？**
+
+A：设置 DisposalBackground，每帧渲染前清除前一帧的内容。同时设置调色板索引 0 为透明色，LoopCount=0 实现无限循环播放。
+
+---
+
+## 六、SSE 实时推送（Q20–Q22）
+
+**Q20：EventBus 的订阅模式有哪几种？**
+
+A：两种——Subscribe(taskID) 按任务订阅，Buffer 容量 16，用于单任务实时进度；SubscribeAll() 全局订阅，Buffer 容量 64，用于工程级查看所有任务的混合视图，在 Handler 层按 projectID 过滤。
+
+**Q21：为什么 EventBus 的 Publish 使用 non-blocking send？**
+
+A：使用 select default 模式，当消费者 channel 缓冲满时静默丢弃事件。这是为了防止慢消费者拖慢管线执行速度，保证 Pipeline 的处理效率不受 SSE 推送影响。
+
+**Q22：SSE 连接在什么条件下会自动关闭？**
+
+A：两种情况——收到终态事件（completed/failed）时自动关闭；客户端断开连接时通过 c.Request.Context().Done() 触发 Unsubscribe 并退出。
+
+---
+
+## 七、可观测性（Q23–Q25）
+
+**Q23：Gen2D 的可观测性体系覆盖哪些层面？**
+
+A：共 35 个 Prometheus 指标分为六大组——HTTP 层、限流层、任务队列层、协程池层、Pipeline 业务层、基础设施层。配套 3 个 Grafana 仪表盘（Overview/Pipeline/Infrastructure）和 10 条告警规则。
+
+**Q24：使用 FullPath() 而不是实际路径采集 HTTP 指标有什么用意？**
+
+A：使用路由模板 `/api/v1/tasks/:taskId` 而非实际路径 `/api/v1/tasks/abc123`，避免高基数标签导致 Prometheus 内存爆炸。
+
+**Q25：哪些告警是 Critical 级别需要立即处理的？**
+
+A：PipelineSuccessRateLow（成功率低于 90%）、RedisDown（连接池为零）、RabbitMQDisconnected（断连）和 HighErrorRate（5xx 错误率超 5%）。这些表示核心功能或服务健康度出现严重问题。
+
+---
+
+## 八、限流与降级（Q26–Q28）
+
+**Q26：双层限流的设计思路是什么？**
+
+A：全局限流在前先检查系统总体配额（如 24 小时 500 次），通过后检查用户限流（如 24 小时 15 次）。这样可以先防止单一用户耗尽全局资源，再在用户层面做精细控制。
+
+**Q27：为什么限流器选择 Fail-Open 而不是 Fail-Close？**
+
+A：在"偶尔超限"和"完全不可用"之间，优先保可用性。Redis 故障时放行请求，超出配额的用户后续可以通过账单追缴；如果选择 Fail-Close，Redis 故障会导致所有用户都无法使用服务。
+
+**Q28：三级降级链的第一、二、三级分别是什么？**
+
+A：第一级 TaskQueue（持久化排队 + 分布式能力），第二级 WorkerPool（有界并发 + 用户隔离），第三级 Legacy FIFO（零配置串行兜底）。每一级都是前一级功能的超集，降级过程渐进、服务始终可用。
+
+---
+
+## 九、提示词工程（Q29–Q30）
+
+**Q29：标签驱动提示词工程的工作原理是什么？**
+
+A：内置 40+ 预定义标签分为 7 大类别（内容类型、美术风格、色调配色、线条粗细、场景氛围、光照效果、情绪基调），每条标签映射到精确的图像生成指令。系统将这些指令与用户描述、风格约束和技术参数组装为三段式提示词。
+
+**Q30：为什么精灵图的网格布局需要特殊处理？**
+
+A：如果不指定间隙要求，AI 生成的图片往往人物之间几乎没有空隙——人类艺术家为了最大化利用画布这样做，但机器无法从中推断分割边界。强制纯白间隙等于人为制造"裂缝"，让投影检测算法可以可靠地分离每帧内容。

hzh/Gen2D/任务分工.md

@@ -0,0 +1,350 @@
+# Gen2D 项目分工
+
+> 仓库地址：https://gitee.com/hezhaohui123/gen2d/tree/v2/
+> 分析时间：2026-06-03
+
+---
+
+## 一、项目概况
+
+**Gen2D** 是一个 AI 驱动的 2D 游戏素材生成工具，通过文本提示词或可视化参数快速生成 Sprite、背景、UI 与动画帧。支持 Unity/Godot 一键集成。技术栈：
+
+| 层级 | 技术 |
+|------|------|
+| 后端 | Go + Gin + Eino (CloudWeGo AI 框架) |
+| 前端 | React + TypeScript + Vite + Zustand |
+| 数据库 | SQLite (后切换到 MySQL) |
+| 存储 | 七牛云对象存储 |
+| 消息队列 | RabbitMQ (可插拔，支持 Memory 模式) |
+| 可观测性 | Prometheus + Grafana + slog |
+| 部署 | Docker Compose + Nginx + CI/CD (Gitee Workflow) |
+
+---
+
+## 二、两位开发者身份
+
+| 身份 | Gitee 账号 | Git 提交别名 | 角色定位 |
+|------|-----------|-------------|---------|
+| **何朝晖** | hezhaohui123 | 何朝晖, wonder | 项目负责人，后端架构 + DevOps + 文档 |
+| **郭永昊** | guo-yong-hao | 郭永昊, Gmaker689, GYhde | 核心开发者，AI 管线 + 前端功能 + 精灵处理 |
+
+
+---
+
+## 三、何朝晖（hezhaohui123 / wonder）的详细分工
+
+### 3.1 后端基础设施（Go/Gin）
+
+| 提交内容 | 说明 |
+|---------|------|
+| 初始化后端项目，集成 Gin 框架，开放健康检查端口 | 项目骨架搭建 |
+| 全面集成 slog 日志到 handler/service/middleware | 结构化日志改造 |
+| 新建请求日志与 Panic 恢复中间件 | 中间件基础设施 |
+| 新建 logger 包，基于 log/slog 提供结构化日志 | 日志子系统 |
+| 代码注释补充 | 代码质量 |
+
+### 3.2 认证与用户系统
+
+| 提交内容 | 说明 |
+|---------|------|
+| 用户注册/登录 Handler 及用户模型 | 认证核心逻辑 |
+| 自动建表，用户信息落库 | 数据持久化 |
+| JWT 认证中间件 | 接口鉴权 |
+| 修复 JWT Claims 类型转换问题 | Bug 修复 |
+| 用户 ID 改为 UUID，注册后自动登录 | 安全增强 |
+
+### 3.3 配置与部署（DevOps）
+
+| 提交内容 | 说明 |
+|---------|------|
+| Docker Compose 配置（后端 + Nginx + MySQL + Redis + RabbitMQ） | 容器化部署 |
+| Nginx 反向代理配置 | 生产环境部署 |
+| .env 文件注入后端环境变量 | 配置管理 |
+| 一键部署脚本 | 快速部署 |
+| CI/CD 流水线自动化 | 持续部署 |
+| Docker 容器和网络添加 v2 标识，外部端口调整 | 多版本隔离 |
+| Docker 后端端口 8080→9001 避免冲突 | 运维优化 |
+| 禁用 v2 分支自动 workflow，改为手动触发 | CI 策略调整 |
+| nginx client_max_body_size 设为 8m 解决大图片上传 413 | 生产修复 |
+| Docker 构建优化（BuildKit 缓存挂载，.dockerignore） | 构建性能 |
+
+### 3.4 数据库与存储
+
+| 提交内容 | 说明 |
+|---------|------|
+| 数据库从 SQLite 切换到 MySQL | 数据库升级 |
+| 精简 Docker Compose | 部署简化 |
+| 七牛云 SDK 依赖与配置 | 云存储接入 |
+| 七牛云存储服务与素材下载接口 | 存储层实现 |
+| 接入七牛云存储，替换本地文件存储 | 存储迁移 |
+| 七牛云私有 bucket 下载 URL 签名支持 | 安全增强 |
+| 移除内存存储，全部改为数据库持久化 | 架构重构 |
+| .env example 示例 | 开发者体验 |
+
+### 3.5 配置架构
+
+| 提交内容 | 说明 |
+|---------|------|
+| 配置层重构为 Viper + YAML + .env 三级加载 | 配置体系 |
+| 精简 image_gen 配置为 OpenAI 兼容同步 API | 配置优化 |
+
+### 3.6 限流系统
+
+| 提交内容 | 说明 |
+|---------|------|
+| 接入 Redis — 配置结构体、客户端初始化 | Redis 集成 |
+| 令牌桶限流器 — Redis Lua 脚本保证原子性 | 核心限流 |
+| Gin 限流中间件 — 429 + Retry-After + X-RateLimit-Remaining | 中间件 |
+| 限流器单元测试 — 7 个用例覆盖令牌桶核心逻辑 | 测试 |
+| 集成 Redis 与限流中间件到 main — Redis 不可用时 fail-open | 容错 |
+| 限流按接口独立挂载 | 粒度优化 |
+| 限流配置按接口拆分（prompt/generate × user/global），Lua 脚本兼容固定窗口 | 策略细化 |
+| 测试固定窗口模式（rate=0 不补充、key 过期重置、配置校验） | 测试 |
+| prompt/optimize 移至认证路由组，用户限流统一使用 userID | 权限调整 |
+
+### 3.7 可插拔任务队列系统
+
+| 提交内容 | 说明 |
+|---------|------|
+| 可插拔任务队列接口 + MemoryQueue 实现 + 配置体系 | 队列抽象 |
+| RabbitMQ 队列适配器 + Docker Compose 配置 | 队列实现 |
+| EventBus 内存事件总线，支持任务状态发布/订阅 | 事件系统 |
+| SSE Handler 任务状态实时推送 | 实时推送 |
+| Consumer 消费者，桥接任务队列和协程池 | 消费者 |
+| 集成可插拔任务队列到主流程 | 系统集成 |
+| Consumer 集成测试（队列→协程池→handler 完整链路） | 测试 |
+| 更新可插拔任务队列相关文档 | 文档 |
+
+### 3.8 可观测性（Prometheus + Grafana）
+
+| 提交内容 | 说明 |
+|---------|------|
+| 完善可观测性指标规划（6 维度 35 指标 + Dashboard + 告警规则） | 规划设计 |
+| Prometheus 指标注册中心（6 维度 35 指标定义） | 指标基础设施 |
+| HTTP 指标中间件（请求量/延迟/大小/并发数） | HTTP 层指标 |
+| 注册 /metrics 端点 + Metrics 中间件到路由 | 端点注册 |
+| 限流中间件 Prometheus 指标埋点（scope/endpoint/result） | 限流指标 |
+| 协程池 atomic Metrics 桥接 Prometheus 指标 | 协程池指标 |
+| 任务队列层 Prometheus 指标埋点（memory + rabbitmq） | 队列指标 |
+| Pipeline 业务层指标埋点（总量/耗时/阶段/重试/活跃数） | 业务指标 |
+| Docker Compose 新增 Prometheus + Grafana 服务及配置 | 服务部署 |
+| Grafana Dashboard 三件套（Overview / Pipeline / Infrastructure） | 可视化 |
+| Prometheus 告警规则（10 条：限流/队列/协程池/Pipeline/基础设施/HTTP） | 告警 |
+| 更新 PLAN.md，标记可观测性阶段六所有任务为已完成 | 进度跟踪 |
+| 完善可观测性文档（backend.md 新增可观测性章节） | 文档 |
+| 更新 Grafana 部署文档，记录 1Panel 实际配置流程 | 文档 |
+
+### 3.9 工程管理模块（Project CRUD）
+
+| 提交内容 | 说明 |
+|---------|------|
+| 工程管理模块实现 | 核心逻辑 |
+| 在路由中注册工程管理接口 | API 注册 |
+| 新增前端 API 客户端 | 前端对接 |
+| 更新项目 API 客户端对接真实后端 | API 联调 |
+
+### 3.10 前端架构与基础设施
+
+| 提交内容 | 说明 |
+|---------|------|
+| 初始化构建前端 | 前端项目搭建 |
+| 构建前端 MVP，实现完整 UI 框架与 mock 数据层 | 前端骨架 |
+| 前端重构为项目+任务双核心模型 | 架构重构 |
+| Toast 通知系统，替换内联错误/成功提示 | UX 组件 |
+| 空状态组件，替换各页面空白提示 | UX 组件 |
+| 骨架屏加载组件与页面入场动画 | UX 组件 |
+| 素材类型选择器改为图标卡片布局 | UX 改进 |
+| 交互元素悬浮/聚焦/按压状态增强 | UX 改进 |
+| CSS 变量重构为暗色/浅色双主题 | 主题系统 |
+| Zustand 主题 store，localStorage 持久化，默认浅色 | 状态管理 |
+| App 初始化时设置 data-theme 属性 | 主题初始化 |
+| 认证页面统一导航栏，含主题切换与退出按钮 | UI 统一 |
+| AI 提示词优化双栏交互 | 前端交互 |
+| 前端任务进度轮询改为 SSE 推送，消除 DB 轮询压力 | 性能优化 |
+
+### 3.11 文档体系
+
+| 提交内容 | 说明 |
+|---------|------|
+| 定义 CLAUDE.md 文件 | AI 辅助开发规范 |
+| 新增架构设计文档 | 架构文档 |
+| 拆分架构设计文档为多篇专项文档 | 文档体系 |
+| 完善 README，精简 CLAUDE.md | README |
+| 后端采用 Eino 框架编排管线，完善前后端文档对齐 | 文档对齐 |
+| 新增用户认证、OSS 存储、异步任务设计 | 设计文档 |
+| 交叉检查修复文档疏漏与不一致 | 文档质量 |
+| 适配单机场景，简化存储与认证方案 | 架构决策 |
+| 更新 API 与后端文档，对齐已实现功能 | 文档同步 |
+| 添加任务完成后自动更新文档并提交的规范 | 开发流程 |
+| 更新 API 文档反映实现状态 | API 文档 |
+| 修正工程管理文档中的认证方式说明 | 文档修正 |
+| 优化 README 与文档索引结构 | 文档整理 |
+| 添加全局/后端/前端架构图生成提示词 | 文档工具 |
+| README 架构图从 ASCII 替换为 Mermaid | 文档可视化 |
+| 提示词优化链路图改为上下排布 | 文档排版 |
+| 新增接口文档 /health | API 文档 |
+| 更新架构文档，文件存储切换为七牛云对象存储 | 架构更新 |
+| 更新后端文档，补充日志系统说明 | 文档更新 |
+| 更新后端文档限流策略，按接口拆分+24小时窗口 | 文档更新 |
+| API 文档新增速率限制章节，标注各接口限流策略 | API 文档 |
+| 更新可插拔任务队列相关文档 | 文档 |
+| 补充工程级 SSE 流端点文档 | API 文档 |
+| 补充哔哩哔哩视频链接 | 推广材料 |
+
+---
+
+## 四、郭永昊（guo-yong-hao / Gmaker689 / GYhde）的详细分工
+
+### 4.1 AI 图片生成管线
+
+| 提交内容                                     | 说明        |
+| ---------------------------------------- | --------- |
+| 文生图与图片编辑 API 调用，新增管线与编辑 HTTP 端点          | 核心生成能力    |
+| 修正文生图 API 调用参数，支持动态分辨率                   | 生成参数优化    |
+| 集成 GPT Image 2 异步文生图 API                 | 异步 API 对接 |
+| 统合 image_gen 为 GPT Image 2 异步 API，删除冗余配置 | API 统一    |
+| 生成管线改为异步，前端接入轮询进度                        | 异步生成+轮询   |
+| 图片持久化到本地 generation/ 目录，前端对接真实 API       | 存储对接      |
+| 回退为 OpenAI 兼容同步 Images API，恢复图片编辑功能      | API 兼容性修复 |
+| 精简 image_gen 配置为 OpenAI 兼容同步 API         | 配置清理      |
+| 管线下阶段进度上报 + 图片预览 + Vite 代理               | 进度可视化     |
+| 异步生成管线 + 前端轮询 + 图片编辑 + JWT 中间件           | 管线综合实现    |
+| 管线 context 取消修复 + FIFO 任务队列 + 移除重复提示词优化  | 管线修复      |
+
+### 4.2 PromptOptimizer 提示词优化
+
+| 提交内容 | 说明 |
+|---------|------|
+| PromptAgent Eino Chain 调用 LLM 优化提示词 | AI 提示词引擎 |
+| PromptOptimizer 集成到生成管线，新增优化 API | 管线集成 |
+| 更新 README 与 API 文档，描述提示词优化链路 | 文档 |
+| 提示词优化支持多布局模式识别与纯白背景统一 | 优化增强 |
+| 提示词优化参考 format 和 resolution 参数 | 参数感知 |
+| 统一提示词白底约束规则 | 质量约束 |
+
+### 4.3 精灵表处理（Sprite Sheet Processing）
+
+| 提交内容 | 说明 |
+|---------|------|
+| 精灵表清洗拆分组件 | 核心功能 |
+| 投影法波谷检测 + 白底硬切断 + 帧底部对齐 + gifmaker 透明 GIF | 算法实现 |
+| spritesprite 增加白底移除、固定网格拆分与帧居中功能 | 拆分工法 |
+| 优化投影法切分 — 收紧峰值边界 + 子图填充至最大尺寸底部对齐 | 算法优化 |
+| 按行独立计算列投影，解决武器等细小突起被截断问题 | 边界情况修复 |
+
+### 4.4 图生图 / 图片编辑功能（Image-to-Image）
+
+| 提交内容 | 说明 |
+|---------|------|
+| Project/Task 模型新增 ReferenceImage 和 GlobalStylePrompt 字段 | 数据模型扩展 |
+| 新增图片上传接口 POST /api/v1/upload/image | 上传接口 |
+| 工程创建/更新支持风格参考图 (base64 上传) 和全局风格提示词 | 工程层支持 |
+| 生成管线支持图生图 — AssetGenerator 有参考图时走 /images/edits | 管线集成 |
+| 图片编辑接口支持 AssetKey 参数，可直接对已生成素材做二次加工 | 二次编辑 |
+| 图生图/编辑接口添加 mask 遮罩参数支持 | 遮罩支持 |
+| 二次编辑 ReEditModal 添加遮罩图上传支持 | 前端遮罩 |
+| 更新前端 API 类型定义和客户端，新增 upload.ts | 前端对接 |
+| 新增 ImageDropZone/ReEditModal 组件，更新表单和配置面板 | 前端组件 |
+| 更新所有文档以反映图生图功能变更 | 文档 |
+| 合并 feat/image-to-image 到 v2（解决 3 个冲突） | 分支合并 |
+| 修复图生图参考图丢失与前端持久化问题 | Bug 修复 |
+
+### 4.5 素材管理系统（Asset Management）
+
+| 提交内容 | 说明 |
+|---------|------|
+| 素材分页加载 + 公开/私有切换 — AssetGallery 加载更多，结果页可见性控制 | 前端分页 |
+| 素材用户隔离 — Asset 新增 IsPublic，GetRecentAssets 分页+按用户过滤，新增 ToggleAssetVisibility | 后端隔离 |
+| 素材展示拆分社区/我的双栏 Tab，社区素材显示作者名 | 前端双栏 |
+| GetRecentAssets 支持 scope 参数 — community 返回公开素材+作者名，mine 返回我的全部 | 后端过滤 |
+| 更新素材接口文档 — 新增 scope 参数说明 | 文档 |
+| 前端素材可见性切换按钮修复 — 前后端 HTTP 方法对齐 | Bug 修复 |
+| 结果详情弹窗 — 瓦片集不自动生成 GIF | 前端优化 |
+| 精灵表+序列帧恢复 GIF 预览 + 详情页图片缩放 | 预览修复 |
+
+### 4.6 素材分类与标签系统
+
+| 提交内容 | 说明 |
+|---------|------|
+| 标签驱动提示词注入系统 | 标签引擎 |
+| 素材类型+内容分类合并，格式 context-aware | 分类体系 |
+| 工程类型与素材风格标签分离，支持双栏自定义标签 | 标签分离 |
+| 修复工程类型双重标签和自定义标签无法点击的问题 | Bug 修复 |
+| 自定义标签融入原生标签栏，点击切换而非消失 | 交互修复 |
+| 将帧动画与单独帧分开为独立分类 | 分类调整 |
+| 首页素材画廊增加分类筛选标签 | 前端筛选 |
+| 输出格式根据素材类型自动设置默认值 | 默认值逻辑 |
+
+### 4.7 前端核心功能
+
+| 提交内容 | 说明 |
+|---------|------|
+| 首页展示最近生成的素材画廊 | 首页画廊 |
+| 左上角品牌图标更换为自定义 logo | 品牌定制 |
+| 更换网页图标为自定义 favicon | 品牌定制 |
+| 首页素材点击查看详情，支持下载 | 详情交互 |
+| 结果页添加帧预览、GIF 动画和导出选项 | 结果展示 |
+| 详情弹窗使用 Portal 渲染到 body，确保始终居中 | 前端修复 |
+| 新建工程弹窗使用 Portal 渲染到 body，解决 transform 父级导致居中和遮罩失效 | 前端修复 |
+| 任务侧边栏点击详情后"任务不存在"问题修复 | Bug 修复 |
+| 任务详情页 JWT 鉴权失败导致回退登录页修复 | Bug 修复 |
+| .gitignore 忽略前后端构建产物 | 工程配置 |
+| FormatAdapter 接入 splitsprite+gifmaker 管线 | 格式适配 |
+| 工程参考图/全局风格提示词贯通到生成管线 | 数据贯通 |
+| 生成请求传递工程参考图和全局风格提示词 | 前端传递 |
+| 移除工程页面生成进度展示，提交后自动跳转结果页 | 交互优化 |
+| TaskListPanel 接入工程级 SSE 实时刷新 | 实时刷新 |
+| 修复项目级参考图预览使用 CDN URL 时的显示问题 | Bug 修复 |
+| 修复 ToggleAssetVisibility 和 GetRecentAssets 因 GetUint 解析 UUID 失败返回 404 | Bug 修复 |
+
+---
+
+## 五、分工总结对照表
+
+| 工作领域                           | 何朝晖  | 郭永昊  |
+| ------------------------------ | :--: | :--: |
+| 后端骨架搭建（Gin + 日志 + 中间件）         | ✅ 主导 |  —   |
+| 认证系统（注册/登录/JWT/UUID）           | ✅ 参与 | ✅ 主导 |
+| 配置体系（Viper + YAML + .env）      |  —   | ✅ 主导 |
+| Docker/CI/CD/部署                | ✅ 主导 |  —   |
+| 七牛云存储集成                        | ✅ 主导 |  —   |
+| 限流系统（Redis + 令牌桶）              | ✅ 主导 |  —   |
+| 可插拔任务队列（Memory/RabbitMQ）       | ✅ 主导 | ✅ 参与 |
+| EventBus + SSE 实时推送            | ✅ 主导 | ✅ 参与 |
+| 协程池（IO 密集型，多用户并发）              | ✅ 主导 | ✅ 参与 |
+| 可观测性（Prometheus + Grafana）     | ✅ 主导 |  —   |
+| 工程管理模块（Project CRUD）           | ✅ 主导 |  —   |
+| 文档体系（架构/API/部署/运维）             | ✅ 主导 | ✅ 参与 |
+| AI 图片生成管线（文生图/图生图）             |  —   | ✅ 主导 |
+| PromptOptimizer 提示词优化          |  —   | ✅ 主导 |
+| Eino 框架集成                      | ✅ 参与 | ✅ 主导 |
+| 精灵表拆分/清洗/动画生成                  |  —   | ✅ 主导 |
+| 图生图/二次编辑/Mask 遮罩               |  —   | ✅ 主导 |
+| 素材管理系统（分页/隔离/可见性）              |  —   | ✅ 主导 |
+| 标签系统（分类/筛选/提示词注入）              |  —   | ✅ 主导 |
+| 前端 UI 框架与 MVP                  | ✅ 主导 |  —   |
+| 前端 UX 组件（Toast/Empty/Skeleton） | ✅ 主导 |  —   |
+| 前端品牌定制（Logo/Favicon）           |  —   | ✅ 主导 |
+| 前端首页/结果页/详情页                   |  —   | ✅ 主导 |
+| 前端 ImageDropZone/ReEditModal   |  —   | ✅ 主导 |
+
+
+---
+
+## 六、协作模式总结
+
+1. **PR 驱动的工作流**：所有代码变更通过 Pull Request 提交，由何朝晖统一 review 和合并。v2 分支共产生 104 个 PR（#1 ~ #104）。
+
+2. **分工边界清晰**：
+   - **何朝晖**负责**基础设施层**：后端骨架、部署运维、可观测性、限流、任务队列、存储、文档体系、前端架构
+   - **郭永昊**负责**业务功能层**：AI 生成管线、精灵表处理、提示词优化、素材管理、标签系统、前端业务页面
+
+3. **技术深度各有侧重**：
+   - 何朝晖深入 Go 后端基础设施（协程池、Redis 限流、RabbitMQ、Prometheus）
+   - 郭永昊深入 AI 管线算法（Eino Chain、投影法分割、GPT Image API 对接、GIF 合成）
+
+4. **提交时间线**：项目从 2026-05-23 初始化到 2026-06-03，仅用 **12 天**完成了 192+ 次提交，实现了从零到完整可部署产品的全流程开发。
+
+---
+
+*本文档基于 Gitee API 拉取的 v2 分支提交历史自动分析生成。*