351 lines
18 KiB
Markdown
351 lines
18 KiB
Markdown
# 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 分支提交历史自动分析生成。*
|