diff --git a/docs/_index.md b/docs/_index.md index 92b7960..bde8805 100755 --- a/docs/_index.md +++ b/docs/_index.md @@ -16,6 +16,7 @@ Go + Gin + Eino / Vite + React + TypeScript + zustand / SQLite / 七牛云对象 | [数据存储](database.md) | SQLite 选型、表结构、ER 关系、对象存储、去重策略 | | [异步任务](async-tasks.md) | 任务生命周期、并发控制、重试策略、进度推送 | | [预设风格键](style-keys.md) | 美术风格、色调、线条等风格键分类与可选值 | +| [架构图提示词](prompts/) | 全局/后端/前端架构图生成提示词,供多模态 AI 生成架构图 | ## 系统架构 diff --git a/docs/prompts/backend-architecture-prompt.md b/docs/prompts/backend-architecture-prompt.md new file mode 100644 index 0000000..2cb8c47 --- /dev/null +++ b/docs/prompts/backend-architecture-prompt.md @@ -0,0 +1,180 @@ +# 后端架构图 — 文生图提示词 + +你是一位技术架构可视化专家。请根据以下描述,生成一张 **gen2d 后端架构详图**,风格:**技术文档风格,白色或浅灰背景,清晰的层次关系和连线**。 + +## 标题 + +gen2d Backend Architecture (Go + Gin + Eino) + +## 整体布局 + +自上而下的分层架构图,共 5 层。 + +--- + +### 第 1 层:入口 (Entry Point) + +``` +cmd/main.go → 初始化 Config → 初始化 Logger → 初始化 DB → 注册路由 → 启动 HTTP Server (:8080) +``` + +用横向箭头串联的流程表示。 + +--- + +### 第 2 层:HTTP 层 (Handler + Middleware) + +分为两个子块并排放置: + +#### 左块:Middlewares (中间件链) + +三个中间件纵向排列,用向下箭头串联: +1. **Logger Middleware** — 生成 X-Request-ID,记录 method/path/status/latency +2. **Auth Middleware** — JWT Bearer Token 校验,注入 UserID 到 context +3. **Recovery Middleware** — Panic 恢复 + 堆栈日志 + +#### 右块:Handlers (路由处理) + +按路由分组展示: + +| 路由前缀 | Handler | 说明 | +|---------|---------|------| +| `/health` | health.go | 健康检查 | +| `/auth/*` | register.go, login.go | 认证(独立路径) | +| `/api/v1/projects/*` | project handlers | 工程 CRUD + 风格管理 | +| `/api/v1/generate` | generate.go | 提交生成任务 | +| `/api/v1/tasks/*` | task handlers | 任务查询 + 素材获取 | +| `/api/v1/prompt/*` | prompt.go | 提示词优化 | +| `/api/v1/assets/*` | storage.go | 素材下载 (302 重定向) | + +在 Handler 块内用小字标注:**"薄层: 仅参数绑定 + 校验 + 调用 Service + 返回统一响应"** + +--- + +### 第 3 层:Service 层 (核心业务逻辑) + +这是整个图的核心区域,占比最大。分为四个子块: + +#### 3a. Pipeline 编排 (pipeline.go) + +用流程图展示 Eino `compose.Graph` 的节点编排: + +``` + ┌─────────────────┐ + │ PipelineInput │ (user prompt + assetType + styles + params) + └────────┬────────┘ + ▼ + ┌──────────────────────┐ + │ ① PromptOptimizer │ 合并工程风格 + 任务风格覆盖 + │ 输出: 三段式提示词 │ 调用 LLM 生成规范化提示词 + └──────────┬───────────┘ + ▼ + ┌──────────────────────┐ + │ ② AssetGenerator │ OpenAI 兼容接口 /v1/images/generations + │ 输出: 原始图片列表 │ 支持多图生成 (n 参数) + └──────────┬───────────┘ + ▼ + ┌──────────────────────┐ + │ ③ QualitySupervisor │ 视觉模型检查风格一致性 + │ 输出: pass / fail │ + └──────┬──────┬────────┘ + │ │ + pass fail (retry < 3) ──→ 回到 ① (RejectReason 回填) + │ │ + │ fail (retry ≥ 3) ──→ 降级输出 ↓ + ▼ │ + ┌──────────────────────┐ │ + │ ④ FormatAdapter │ ◄──────┘ + │ spritesheet 打包 │ + │ 上传七牛云 + 写 DB │ + └──────────┬───────────┘ + ▼ + ┌──────────────────┐ + │ PipelineOutput │ (assets[] + metadata) + └──────────────────┘ +``` + +#### 3b. 节点实现 (nodes.go) + +四个节点用一个表格或四个小卡片展示,每个卡片包含: +- **节点名称** +- Lambda 输入 → 输出 类型签名 +- StatePreHandler / StatePostHandler 交互说明 + +| 节点 | 输入 → 输出 | State 交互 | +|------|-----------|-----------| +| PromptOptimizer | PipelineInput → string | Pre: 注入 RejectReason; Post: 写 FinalPrompt | +| AssetGenerator | string → []Image | Post: 写 RawImages | +| QualitySupervisor | []Image → bool | Post: 写 PassQuality, RejectReason, RetryCount | +| FormatAdapter | []Image → PipelineOutput | 无 State 交互,直接输出 | + +#### 3c. 类型定义 (types.go) + +一个小卡片展示三个核心结构体的字段: +- **PipelineInput**:Prompt, AssetType, ProjectStyle, TaskStyle, Params +- **PipelineState**:Input, FinalPrompt, RawImages, PassQuality, RejectReason, RetryCount +- **PipelineOutput**:Assets[], Metadata + +#### 3d. 辅助 Service + +并排两个小块: +- **auth.go**:注册 / 登录 / JWT 签发 (HS256) / Token 校验 +- **storage.go**:七牛云上传 (token 鉴权) / 下载 URL 生成 / 删除 +- **inference.go**:AI API 调用封装 (文生图 + 图片编辑) +- **prompt_agent.go**:LLM 提示词优化 Agent (OpenAI 兼容 Chat Completions, 含回退模板) + +--- + +### 第 4 层:数据访问层 + +- **db.go**:GORM SQLite 连接初始化 + 自动建表 (CREATE TABLE IF NOT EXISTS) +- **cache.go**:sync.Map 内存缓存,用于请求去重 (hash → taskId) +- **config.go**:环境变量读取 + 配置结构体 + +--- + +### 第 5 层:外部依赖 (底部并排) + +1. **SQLite** (`data/gen2d.db`) + - 5 张表:user, project, project_style, task, asset + - ER: user 1→N project 1→1 project_style, project 1→N task 1→N asset + - 全部 CASCADE 删除 + +2. **七牛云 Kodo** + - Bucket 存储 Key 格式:`users/{uid}/projects/{pid}/tasks/{tid}/output/{file}` + - CDN URL + 签名参数 (默认 3600s 过期) + +3. **LLM API (外部)** + - OpenAI 兼容 `/v1/images/generations` — 文生图 + - OpenAI 兼容 `/v1/chat/completions` — 提示词优化 + - 可替换模型提供商 + +--- + +## 色彩与排版指南 + +- **标题横幅**:深蓝 (#1E3A5F),白色文字 +- **第 2 层 (Handler)**:浅蓝 (#E8F4FD),深蓝边框 +- **第 3 层 (Service)**:浅绿 (#E6F7EE),深绿边框 — 这是核心层,用稍大的面积 +- **管线节点**:用不同深浅绿色区分: + - ① 浅绿 #D1FAE5 + - ② 中绿 #A7F3D0 + - ③ 中绿 #6EE7B7 + - ④ 深绿 #34D399 +- **第 4 层 (Data)**:浅黄 (#FEF3C7),深黄边框 +- **第 5 层 (External)**:浅灰 (#F3F4F6),深灰边框 +- **箭头颜色**: + - 正常流程:实线 绿色 + - 重试/回退:虚线 橙色 + - 降级路径:虚线 红色 + +- 文字:sans-serif,英文为主,括号内中文辅助说明 +- 所有框使用圆角 (border-radius: 8px) +- 层与层之间用虚线分隔,标注层名称在左侧 + +## 附加约束 + +- 保持技术文档风格,干净利落 +- 所有组件名称与代码库中的实际命名一致 (pipeline.go, nodes.go, types.go 等) +- 画面比例 3:4 或 A4 竖版比例,适合放入文档 +- 不要使用 3D 效果或过度装饰 diff --git a/docs/prompts/frontend-architecture-prompt.md b/docs/prompts/frontend-architecture-prompt.md new file mode 100644 index 0000000..2b44e99 --- /dev/null +++ b/docs/prompts/frontend-architecture-prompt.md @@ -0,0 +1,184 @@ +# 前端架构图 — 文生图提示词 + +你是一位前端架构可视化专家。请根据以下描述,生成一张 **gen2d 前端架构详图**,风格:**现代前端技术文档风格,深色主题,组件树 + 数据流 + 路由三重展示**。 + +## 标题 + +gen2d Frontend Architecture (Vite + React + TypeScript + zustand) + +## 整体布局 + +分为三个主要区域,从左到右排列: + +--- + +## 左区:路由与页面层 (Router & Pages) + +### Router 入口 +- **react-router-dom v6** (BrowserRouter, SPA 模式) +- **ProtectedRoute** 守卫组件 (检查 token,未登录重定向 /login) + +### 页面路由表 + +用路由匹配图展示: + +``` +/ → HomePage (项目画廊) +/login → LoginPage (登录) +/register → RegisterPage (注册) +/projects/:projectId → ProjectDetailPage (三栏工作台) +/projects/:projectId/tasks/:taskId → ResultPage (素材预览) +``` + +### 页面层级关系 + +``` +App + └─ Layout (Navbar + Outlet + ToastContainer) + ├─ HomePage + │ ├─ ProjectCard (画廊卡片) × N + │ └─ CreateProjectModal (新建弹窗) + ├─ ProjectDetailPage (三栏 CSS Grid) + │ ├─ [左栏 260px] ProjectConfigPanel + │ ├─ [中间 1fr] GenerateForm + ProgressBar + │ └─ [右栏 320px] TaskListPanel + └─ ResultPage + └─ AssetPreview +``` + +--- + +## 中区:状态管理 & 数据流 (State Management) + +### zustand Stores (7 个) + +用 7 个卡片网格展示,每个卡片包含 Store 名称、核心状态字段、主要 Action: + +| Store | 核心 State | 主要 Actions | 消费组件 | +|-------|-----------|-------------|---------| +| **auth** | user, token, isAuthenticated | login, register, logout | Layout, ProtectedRoute, LoginPage | +| **projectList** | projects[], loading | loadProjects, createProject, deleteProject | HomePage | +| **project** | projectId, name, style, draftStyle, draftName, hasUnsavedChanges | loadProject, startEditing, updateDraft, commitDraft, discardDraft | ProjectConfigPanel, ProjectDetailPage | +| **task** | prompt, assetType, taskStyle, params, enableAI, optimizedPrompt | setters, runOptimize, reset | GenerateForm | +| **generation** | taskId, stage, progress, status, retryCount, assets[], error | submit, reset | ProgressBar, GenerateForm, ResultPage | +| **theme** | mode (light/dark) | toggle | Layout (全局主题切换) | +| **toast** | toasts[] | addToast, removeToast | ToastContainer | + +### 数据流方向 + +在组件和 Store 之间画出单向数据流箭头: +- **组件 → Store**:dispatch action (用户交互) +- **Store → 组件**:useStore selector 订阅,自动重渲染 +- **Store → API**:调用 api/ 封装层 +- **API → Store**:响应数据写入 state + +### 风格编辑流程 (Draft/Commit 模式) + +用一个小流程图展示: + +``` +startEditing() → copy style → draftStyle + ↓ +updateDraft(key, value) → draftStyle 变更 → hasUnsavedChanges = true + ↓ +┌─ commitDraft() → PUT /api/v1/projects/:id/style → style = draftStyle → hasUnsavedChanges = false +└─ discardDraft() → draftStyle = style → hasUnsavedChanges = false +``` + +--- + +## 右区:组件树 & 交互流程 (Components & Interactions) + +### 组件依赖树 + +``` +Layout +├── Navbar (logo + 导航 + 用户菜单) +└── ToastContainer + └── ToastItem × N + +HomePage +├── ProjectCard (缩略图 + 名称 + 任务数 + 最近活动) +└── CreateProjectModal + ├── StyleSelector (预设风格 pill 按钮) + └── CustomTagsEditor (添加/删除自定义标签) + +ProjectDetailPage (CSS Grid: 260px 1fr 320px) +├── [左栏] ProjectConfigPanel +│ ├── 工程名 (可编辑 input) +│ ├── StyleSelector (全量风格编辑) +│ ├── CustomTagsEditor +│ └── 保存/取消 按钮 (hasUnsavedChanges 控制) +├── [中间] 生成区域 +│ ├── GenerateForm +│ │ ├── 素材类型选择 (sprite / background / ui / animation) +│ │ ├── StyleSelector (任务覆盖,仅记录差异) +│ │ ├── PromptEditor (文本输入) +│ │ ├── 技术参数 (分辨率 / 帧数 / 格式) +│ │ └── 提交按钮 + AI 优化按钮 +│ └── ProgressBar (提交后显示) +│ └── 四阶段进度条 (prompt_builder → asset_generator → quality_supervisor → format_adapter) +└── [右栏] TaskListPanel + ├── StatusBadge (状态标签: pending/running/completed/failed) + ├── TaskItem × N (点击跳转 ResultPage) + └── 自动刷新 (15s 间隔) + +ResultPage +└── AssetPreview + ├── 图片预览 (带帧信息标注) + ├── 元数据展示 (分辨率/帧数/方向数/格式) + └── 下载按钮 (GET /api/v1/assets/download?key=...) +``` + +### 生成任务交互流程 (时序简化) + +``` +User → GenerateForm (填写 prompt + 选择类型 + 参数) → [提交] + → POST /api/v1/generate → taskId + → generation store: status=running + → ProgressBar 显示 + → 轮询 GET /api/v1/tasks/:taskId (每 1.5s) + → 更新 stage + progress + → status=completed + → GET /api/v1/tasks/:taskId/assets + → 显示 "查看结果" → 跳转 ResultPage +``` + +### API 封装层结构 (api/) + +在底部用一个窄条展示: + +``` +api/ +├── client.ts — fetch 封装 (统一错误处理, JSON 解包, Bearer Token 注入) +├── auth.ts — login(), register() +├── project.ts — listProjects(), createProject(), getProject(), updateProject(), deleteProject() +├── generate.ts — submitGenerate(), getTask(), getTaskAssets() +├── prompt.ts — optimizePrompt(), extractTags() +├── mock.ts — 多工程 Mock 数据 (开发用) +└── types.ts — Project, Task, Asset, User 等类型定义 +``` + +--- + +## 色彩与排版指南 + +- **背景**:深色 (#1a1a2e 或 #0f172a) +- **左区 (Router)**:紫色调 (#8B5CF6 / #7C3AED),紫色边框 +- **中区 (State)**:青色调 (#06B6D4 / #0891B2),青色边框 +- **右区 (Components)**:绿色调 (#10B981 / #059669),绿色边框 +- **API 层**:橙色调 (#F59E0B) +- **组件框**:半透明背景 + 彩色左边框 +- **箭头**:白色或浅灰 (#94A3B8),实线 = 同步,虚线 = 异步 +- **文字**:白色为主 (#F8FAFC),次要文字浅灰 (#94A3B8) +- **Store 卡片**:微亮边框,内部字段用等宽字体 +- **所有框使用圆角** (border-radius: 6px) +- **区域标题**用较大的加粗字体 + 左侧色条 + +## 附加约束 + +- 所有组件名、Store 名、文件名与代码库保持一致 +- 中文用于辅助标注(括号内),英文为主要标注 +- 避免拥挤,分区之间留白充分 +- 画面比例 16:9 或更宽,适合横屏展示 +- 不要使用 3D 效果 diff --git a/docs/prompts/global-architecture-prompt.md b/docs/prompts/global-architecture-prompt.md new file mode 100644 index 0000000..3fa18d4 --- /dev/null +++ b/docs/prompts/global-architecture-prompt.md @@ -0,0 +1,81 @@ +# 全局架构图 — 文生图提示词 + +你是一位技术架构可视化专家。请根据以下描述,生成一张 **gen2d 全局系统架构图**,风格:**简洁现代的技术架构图,深色背景,使用清晰的方框和箭头表示组件与数据流**。 + +## 标题 + +gen2d 系统架构总览 + +## 技术栈标注(顶部或底部小字) + +Go + Gin + Eino / Vite + React + TypeScript + zustand / SQLite / 七牛云 Kodo + +## 架构层次(自上而下) + +### 第一层:前端层 (Frontend) + +放置一个圆角矩形框,标题为 **Frontend (Vite + React + TypeScript)**,内部包含: + +- **Pages (页面层)**:Login, Register, HomePage, ProjectDetailPage, ResultPage,以上下文无关方式排列 +- **State & Router (横跨栏)**: + - 左侧标注 **react-router-dom v6** (SPA Routing) + - 右侧标注 **zustand** (7 stores: auth, project, projectList, task, generation, theme, toast) +- **Components (组件层)**:StyleSelector, CustomTagsEditor, PromptEditor, GenerateForm, ProgressBar, AssetPreview + +在 Frontend 框内用水平虚线或分组分隔三个子层(页面 → 路由/状态 → 组件),展示分层关系。 + +### 第二层:通信层 + +在 Frontend 和 Backend 之间画一个横向箭头带,标注: + +- **HTTP REST /api/v1/***(实线) +- **WebSocket /api/v1/tasks/:taskId/ws**(虚线) +- 旁边小字标注 "JWT Bearer Token 认证" + +### 第三层:后端层 (Backend) + +放置一个圆角矩形框,标题为 **Backend (Go + Gin + Eino)**,内部自左向右分三层: + +#### 3a. Handler 层 (最左) +- Gin Router 入口 +- 薄层:参数绑定 + 校验 + 调用 Service +- 关键 Handler:health, auth, project, generate, prompt, storage + +#### 3b. Service 层 (中间,核心) +- 标题:**Eino compose.Graph (管线编排)** +- 四个节点从上到下,箭头连接: + 1. **PromptOptimizer** (提示词优化 + 风格合并) + 2. **AssetGenerator** (AI 推理 API 调用) + 3. **QualitySupervisor** (视觉模型质检) + 4. **FormatAdapter** (格式转换 + spritesheet 打包) +- 在第 3 步右侧标注分支逻辑:pass → FormatAdapter;fail → 回到 PromptOptimizer (最多 3 次) +- 在管线框下方放置 **中间件栏**:Logger (slog), JWT Auth, Panic Recovery + +#### 3c. Model 层 (最右) +- 数据模型:PipelineInput, PipelineState, PipelineOutput + +### 第四层:数据与基础设施层 (底部) + +放置三个并排的框: + +1. **SQLite** — 标注 5 张表:user, project, project_style, task, asset;附带 ER 关系简写 "1→N cascade" +2. **七牛云 Kodo (对象存储)** — 标注存储路径 `${user}/${project}/${task}/output/` 和 CDN URL 签名访问 +3. **LLM API (外部)** — 标注 OpenAI 兼容接口 `/v1/images/generations` 和 Chat Completions + +在前端和后端之间画出与这三个组件的连线,标注数据流方向。 + +## 色彩建议 + +- **Frontend 区域**:蓝紫色调 (#4A90D9 或类似) +- **Backend 区域**:青绿色调 (#00B4AB 或类似) +- **管线节点**:用不同深浅区分四个阶段 +- **数据层**:灰色调 (#6B7280 或类似) +- **外部服务**:橙色 (#F59E0B 或类似) +- **箭头**:实线 = 同步调用,虚线 = 异步/回调 + +## 附加约束 + +- 不要使用过于花哨的 3D 效果或阴影 +- 文字要清晰可读,字体大小不小于图中主体元素的 1/20 +- 请用英文标注组件名称(与代码库一致),中文可用于辅助说明 +- 整体比例适合 16:9 宽屏展示