docs: 优化 README 与文档索引结构

- README 新增目录导航、参考链接、路线图、文档索引模块 - README 采用居中标题、Badge 行、快速链接栏的顶级开源项目风格 - 技术栈表增加说明列，项目结构细化各模块用途 - API 已实现/规划中拆分展示，合并近期新增接口 - docs/_index 新增 ASCII 系统架构图、核心概念概览、命令行参考
2026-05-25 20:48:50 +08:00
parent 8657fe5d28
commit e8abc41c2a
2 changed files with 301 additions and 88 deletions
@@ -1,48 +1,71 @@
 # gen2d

-AI 驱动的 2D 游戏素材生成工具。通过文本提示词或可视化参数，生成风格一致、管线友好的 Sprite、背景、UI 元素与动画帧，无缝融入 Unity / Godot 等主流 2D 游戏引擎工作流。
+<p align="center">
+  <b>AI 驱动的 2D 游戏素材生成工具</b><br/>
+  文本描述 + 风格参数 → 风格一致、管线友好的 Sprite、背景、UI 与动画帧<br/>
+  无缝融入 Unity / Godot 等主流 2D 游戏引擎工作流
+</p>

-[![Go](https://img.shields.io/badge/Go-1.26-00ADD8?logo=go&logoColor=white)](https://go.dev/)
-[![Gin](https://img.shields.io/badge/Gin-1.12-008ECF?logo=gin&logoColor=white)](https://gin-gonic.com/)
-[![Eino](https://img.shields.io/badge/Eino-0.8-blue)](https://github.com/cloudwego/eino)
-[![React](https://img.shields.io/badge/React-18-61DAFB?logo=react&logoColor=black)](https://react.dev/)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.6-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![Vite](https://img.shields.io/badge/Vite-6-646CFF?logo=vite&logoColor=white)](https://vite.dev/)
-[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)
+<p align="center">
+  <a href="https://go.dev/"><img src="https://img.shields.io/badge/Go-1.26-00ADD8?logo=go&logoColor=white" alt="Go" /></a>
+  <a href="https://gin-gonic.com/"><img src="https://img.shields.io/badge/Gin-1.12-008ECF?logo=gin&logoColor=white" alt="Gin" /></a>
+  <a href="https://github.com/cloudwego/eino"><img src="https://img.shields.io/badge/Eino-0.8-blue" alt="Eino" /></a>
+  <a href="https://react.dev/"><img src="https://img.shields.io/badge/React-18-61DAFB?logo=react&logoColor=black" alt="React" /></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.6-3178C6?logo=typescript&logoColor=white" alt="TypeScript" /></a>
+  <a href="https://vite.dev/"><img src="https://img.shields.io/badge/Vite-6-646CFF?logo=vite&logoColor=white" alt="Vite" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License" /></a>
+</p>

-### **[在线体验 http://47.121.181.112:10000](http://47.121.181.112:10000)**
+<p align="center">
+  <b><a href="http://47.121.181.112:10000">在线体验</a></b>
+  &nbsp;|&nbsp;
+  <b><a href="docs/_index.md">文档</a></b>
+  &nbsp;|&nbsp;
+  <b><a href="#快速开始">快速开始</a></b>
+  &nbsp;|&nbsp;
+  <b><a href="#api">API</a></b>
+</p>
+
+---
+
+## 目录
+
+- [特性](#特性)
+- [快速开始](#快速开始)
+- [配置](#配置)
+- [架构](#架构)
+  - [生成管线](#生成管线)
+  - [提示词优化链路](#提示词优化链路)
+  - [预设风格键](#预设风格键)
+- [API](#api)
+- [技术栈](#技术栈)
+- [项目结构](#项目结构)
+- [部署](#部署)
+- [文档](#文档)
+- [路线图](#路线图)
+- [参与贡献](#参与贡献)
+- [参考链接](#参考链接)
+- [License](#license)

 ## 特性

- **多智能体协作管线** — PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter，基于 Eino `compose.Graph` 编排
+- **多智能体协作管线** — PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter，基于 Eino `compose.Graph` 编排，支持质检重试与降级输出
 - **提示词优化** — Eino Chain 驱动的 PromptAgent，支持任意 OpenAI 兼容 API，无 key 时自动回退模板生成
 - **风格系统** — 预设美术风格、色调、线条、场景、光照、情绪等维度，支持工程级与任务级风格覆盖
 - **实时进度** — WebSocket 推送管线各阶段状态、进度与质检重试信息
- **异步任务** — 内存队列 + 通道模型，支持并发控制、失败重试（最多 3 次）与降级输出
- **请求去重** — 相同 `prompt + assetType + params` 的并发请求自动合并
+- **异步任务** — goroutine 模型，支持并发控制、失败重试（最多 3 次）与降级输出
+- **请求去重** — 相同 `prompt + assetType + params` 的并发请求自动合并，返回已有 taskId
 - **暗色主题** — 前端支持 Light / Dark 双主题，CSS 自定义属性驱动
- **一键部署** — Docker Compose 双容器架构 + `deploy.sh` 脚本 + Gitee CI/CD 流水线
-
-## 技术栈
-
-| 层 | 技术 |
-|---|------|
-| 后端语言 | Go 1.26 |
-| HTTP 框架 | Gin v1.12 |
-| 管线编排 | [Eino](https://github.com/cloudwego/eino) v0.8 — `compose.Graph` + `compose.Chain` |
-| ORM | GORM + SQLite |
-| 认证 | JWT (golang-jwt) + bcrypt |
-| 配置 | Viper + godotenv（环境变量 > config.yml > 默认值） |
-| 前端框架 | React 18 + TypeScript 5.6 |
-| 构建工具 | Vite 6 |
-| 状态管理 | Zustand 5 |
-| 路由 | react-router-dom v7 |
-| 样式 | CSS Modules + CSS 自定义属性 |
-| 容器化 | Docker 多阶段构建 + nginx 反向代理 |
-| CI/CD | Gitee Workflow + deploy.sh |
+- **一键部署** — Docker Compose 双容器架构 + `deploy.sh` 脚本

 ## 快速开始

+### 环境要求
+
+- Go 1.26+
+- Node.js 20+
+- Docker & Docker Compose（部署用）
+
 ### 后端

 ```bash
@@ -62,14 +85,14 @@ npm install
 npm run dev
 ```

-开发服务器默认运行在 `http://localhost:5173`，通过 Vite proxy 转发 `/api` 和 `/auth` 请求到后端。
+开发服务器运行在 `http://localhost:5173`，通过 Vite proxy 转发 `/api` 和 `/auth` 请求到后端。

 ## 配置

 配置通过 Viper 读取，优先级从高到低：

 | 优先级 | 来源 | 说明 |
-|--------|------|------|
+|:---:|------|------|
 | 1 | 环境变量 | 适合 Docker / CI，敏感字段推荐使用 |
 | 2 | `.env` 文件 | 位于 `backend/.env`，通过 godotenv 加载 |
 | 3 | `config.yml` | 位于 `backend/internal/config/config.yml`，存放非敏感默认值 |
@@ -80,7 +103,7 @@ npm run dev
 | 环境变量 | YAML 路径 | 默认值 | 说明 |
 |----------|-----------|--------|------|
 | `GEN2D_LLM_BASE_URL` | `llm.base_url` | `https://api.deepseek.com/v1` | LLM API 地址（兼容 OpenAI 接口） |
-| `GEN2D_LLM_API_KEY` | `llm.api_key` | (空) | API 密钥，请通过环境变量设置 |
+| `GEN2D_LLM_API_KEY` | `llm.api_key` | (空) | API 密钥 |
 | `GEN2D_LLM_MODEL` | `llm.model` | `deepseek-v4-pro` | 模型名称 |
 | `GEN2D_LLM_TEMPERATURE` | `llm.temperature` | `0.7` | 生成温度 (0-2) |
 | `GEN2D_LLM_MAX_TOKENS` | `llm.max_tokens` | `2048` | 最大输出 token 数 |
@@ -90,7 +113,7 @@ npm run dev
 | 环境变量 | YAML 路径 | 默认值 | 说明 |
 |----------|-----------|--------|------|
 | `GEN2D_IMAGE_BASE_URL` | `image_gen.base_url` | `https://api.stability.ai/v1` | 文生图 API 地址 |
-| `GEN2D_IMAGE_API_KEY` | `image_gen.api_key` | (空) | API 密钥，请通过环境变量设置 |
+| `GEN2D_IMAGE_API_KEY` | `image_gen.api_key` | (空) | API 密钥 |
 | `GEN2D_IMAGE_MODEL` | `image_gen.model` | `stable-diffusion-xl` | 模型名称 |
 | `GEN2D_IMAGE_WIDTH` | `image_gen.width` | `1024` | 生成图片宽度 |
 | `GEN2D_IMAGE_HEIGHT` | `image_gen.height` | `1024` | 生成图片高度 |
@@ -149,8 +172,6 @@ graph TD
 | 光照 | `lighting` | bright, dim, dramatic, ambient, neon |
 | 情绪 | `mood` | cheerful, dark, mysterious, epic, calm |

-详细架构说明见 [docs/_index.md](docs/_index.md)。
-
 ## API

 接口统一前缀 `/api/v1/`，统一响应格式：
@@ -169,21 +190,87 @@ graph TD
 | POST | `/auth/register` | 用户注册 |
 | POST | `/auth/login` | 用户登录（返回 JWT Token） |
 | POST | `/api/v1/prompt/optimize` | 提示词优化 |
+| GET/POST | `/api/v1/projects` | 工程列表 / 创建工程 |
+| GET/PUT/DELETE | `/api/v1/projects/:id` | 工程详情 / 更新 / 删除 |
+| GET/PUT | `/api/v1/projects/:id/style` | 工程风格读写 |
+| POST | `/api/v1/generate` | 提交生成任务 |
+| GET | `/api/v1/tasks/:id` | 任务状态与进度 |
+| GET | `/api/v1/tasks/:id/assets` | 生成结果素材列表 |
+| GET | `/api/v1/assets/download` | 下载素材（重定向到 CDN） |

 ### 规划中

 | 方法 | 路径 | 说明 |
 |------|------|------|
-| GET/POST | `/api/v1/projects` | 工程列表 / 创建工程 |
-| GET/DELETE | `/api/v1/projects/:id` | 工程详情 / 删除工程 |
-| GET/PUT | `/api/v1/projects/:id/style` | 工程风格读写 |
-| POST | `/api/v1/generate` | 提交生成任务 |
-| GET | `/api/v1/tasks/:id` | 任务状态与进度 |
-| GET | `/api/v1/tasks/:id/assets` | 生成结果素材列表 |
 | WS | `/api/v1/tasks/:id/ws` | WebSocket 实时进度推送 |
+| GET | `/api/v1/auth/me` | 获取当前用户信息 |
+| PUT | `/api/v1/auth/password` | 修改密码 |

 完整 API 文档见 [docs/api.md](docs/api.md)。

+## 技术栈
+
+| 层 | 技术 | 说明 |
+|---|------|------|
+| 后端语言 | Go 1.26 | — |
+| HTTP 框架 | Gin v1.12 | 路由、中间件、JSON 绑定 |
+| 管线编排 | [Eino](https://github.com/cloudwego/eino) v0.8 | `compose.Graph` + `compose.Chain` |
+| ORM | GORM + SQLite | 零配置数据库 |
+| 认证 | JWT (golang-jwt) + bcrypt | 无状态认证 |
+| 配置 | Viper + godotenv | 多层配置优先级 |
+| 对象存储 | 七牛云 Kodo | CDN 加速、私有 Bucket 签名访问 |
+| 前端框架 | React 18 + TypeScript 5.6 | 函数组件 + Hooks |
+| 构建工具 | Vite 6 | HMR 开发体验 |
+| 状态管理 | Zustand 5 | 轻量、不可变状态 |
+| 路由 | react-router-dom v7 | SPA 路由 |
+| 样式 | CSS Modules + CSS 自定义属性 | 主题切换 |
+| 容器化 | Docker 多阶段构建 | nginx 反向代理 |
+| CI/CD | Gitee Workflow | 自动构建部署 |
+
+## 项目结构
+
+```
+gen2d/
+├── backend/                    # Go + Gin API 服务
+│   ├── cmd/main.go             # 入口：加载配置 → 初始化 DB → 注册路由 → 启动
+│   ├── internal/
+│   │   ├── config/             # Viper 配置加载 + config.yml
+│   │   ├── db/                 # SQLite + GORM 初始化
+│   │   ├── handler/            # HTTP 处理器（health, prompt, auth, generate, storage）
+│   │   ├── model/              # 数据模型（User, Response）
+│   │   ├── mildware/           # 中间件（JWT 认证、日志、恢复）
+│   │   ├── logger/             # 日志包（基于 log/slog）
+│   │   └── service/            # 业务逻辑
+│   │       ├── pipeline.go     # Eino Graph 四阶段管线编排
+│   │       ├── prompt_agent.go # Eino Chain 提示词优化
+│   │       ├── nodes.go        # 管线节点实现
+│   │       ├── inference.go    # 文生图推理
+│   │       ├── auth.go         # 注册 / 登录 / JWT
+│   │       └── storage.go      # 七牛云对象存储
+│   └── pkg/splitsprite/        # 精灵表拆分工具
+├── frontend/                   # Vite + React 前端
+│   └── src/
+│       ├── api/                # HTTP 客户端与类型定义
+│       ├── components/         # UI 组件
+│       ├── pages/              # 页面（Login, Register, Home, Project, Result）
+│       ├── stores/             # Zustand 状态管理
+│       ├── hooks/              # 自定义 Hooks
+│       ├── router/             # 路由配置
+│       ├── utils/              # 工具函数
+│       └── styles/             # 全局样式与主题变量
+├── docs/                       # 项目文档
+│   ├── _index.md               # 文档索引
+│   ├── api.md                  # API 设计
+│   ├── backend.md              # 后端工程
+│   ├── frontend.md             # 前端工程
+│   ├── database.md             # 数据存储
+│   ├── async-tasks.md          # 异步任务
+│   └── style-keys.md           # 预设风格键
+├── docker-compose.yml          # 容器编排
+├── deploy.sh                   # 一键部署脚本
+└── .workflow/                  # CI/CD 流水线配置
+```
+
 ## 部署

 ### Docker Compose
@@ -196,7 +283,7 @@ docker compose up -d --build
 ```

 - 后端：Go 多阶段构建，暴露 8080 端口
- 前端：Node 构建 + nginx 反向代理，默认映射到宿主机 10000 端口
+- 前端：Node 构建 + nginx 反向代理，默认映射宿主机 10000 端口
 - 数据持久化：`backend-data` 卷挂载 SQLite 数据库与生成素材

 ### 一键脚本
@@ -207,45 +294,33 @@ bash deploy.sh

 自动完成仓库克隆/拉取、环境检查、`.env` 模板复制、`docker compose up`。

-## 项目结构
+## 文档

-```
-gen2d/
-├── backend/                    # Go + Gin API 服务
-│   ├── cmd/main.go             # 入口：加载配置 → 初始化 DB → 注册路由 → 启动
-│   ├── internal/
-│   │   ├── config/             # Viper 配置加载 + config.yml
-│   │   ├── db/                 # SQLite + GORM 初始化
-│   │   ├── handler/            # HTTP 处理器（health, prompt, auth）
-│   │   ├── model/              # 数据模型（User, Response）
-│   │   └── service/            # 业务逻辑
-│   │       ├── pipeline.go     # Eino Graph 四阶段管线
-│   │       ├── prompt_agent.go # Eino Chain 提示词优化
-│   │       ├── nodes.go        # 管线节点实现
-│   │       ├── inference.go    # 文生图推理（Mock）
-│   │       └── auth.go         # 注册 / 登录 / JWT
-│   └── pkg/splitsprite/        # 精灵表拆分工具
-├── frontend/                   # Vite + React 前端
-│   └── src/
-│       ├── api/                # HTTP 客户端与类型定义
-│       ├── components/         # UI 组件（StyleSelector, PromptEditor, GenerateForm...）
-│       ├── pages/              # 页面（Login, Register, Project, Generate, Result）
-│       ├── stores/             # Zustand 状态管理
-│       ├── hooks/              # 自定义 Hooks
-│       ├── router/             # 路由配置
-│       └── styles/             # 全局样式与主题变量
-├── docs/                       # 项目文档
-│   ├── _index.md               # 文档索引
-│   ├── api.md                  # API 设计
-│   ├── backend.md              # 后端工程
-│   ├── frontend.md             # 前端工程
-│   ├── database.md             # 数据存储
-│   ├── async-tasks.md          # 异步任务
-│   └── style-keys.md           # 预设风格键
-├── docker-compose.yml          # 容器编排
-├── deploy.sh                   # 一键部署脚本
-└── .workflow/deploy.yml        # Gitee CI/CD 流水线
-```
+详细设计文档见 [docs/](docs/) 目录：
+
+| 文档 | 说明 |
+|------|------|
+| [docs/_index.md](docs/_index.md) | 文档索引与架构概述 |
+| [docs/api.md](docs/api.md) | API 接口设计、请求/响应示例、错误码 |
+| [docs/backend.md](docs/backend.md) | 后端分层结构、管线设计、风格模型、缓存层 |
+| [docs/frontend.md](docs/frontend.md) | 前端组件树、状态管理、路由、交互流程 |
+| [docs/database.md](docs/database.md) | SQLite 选型、表结构、ER 关系、对象存储、去重策略 |
+| [docs/async-tasks.md](docs/async-tasks.md) | 任务生命周期、并发控制、重试策略、进度推送 |
+| [docs/style-keys.md](docs/style-keys.md) | 预设风格键分类与可选值 |
+
+## 路线图
+
+- [x] 提示词优化 Agent（Eino Chain）
+- [x] 多智能体生成管线（Eino Graph）
+- [x] 工程风格系统 + 任务级覆盖
+- [x] 用户认证（JWT + bcrypt）
+- [x] 异步任务 + 实时进度推送
+- [x] 素材帧预览、GIF 动画与导出
+- [x] 自定义标签
+- [ ] WebSocket 实时进度推送（待完成）
+- [ ] 批量生成与队列调度
+- [ ] 文生图多模型适配（DALL-E, Midjourney）
+- [ ] 素材版本管理与历史记录

 ## 参与贡献

@@ -254,6 +329,42 @@ gen2d/
 3. 提交代码
 4. 新建 Pull Request

+## 参考链接
+
+### 后端
+
+- [Go](https://go.dev/) — 编程语言
+- [Gin](https://gin-gonic.com/) — HTTP 框架
+- [Eino](https://github.com/cloudwego/eino) — AI 管线编排框架
+- [GORM](https://gorm.io/) — Go ORM
+- [golang-jwt](https://github.com/golang-jwt/jwt) — JWT 库
+- [Viper](https://github.com/spf13/viper) — 配置管理
+
+### 前端
+
+- [React](https://react.dev/) — UI 框架
+- [TypeScript](https://www.typescriptlang.org/) — 类型安全
+- [Vite](https://vite.dev/) — 构建工具
+- [Zustand](https://github.com/pmndrs/zustand) — 状态管理
+- [react-router](https://reactrouter.com/) — 路由
+
+### AI / 模型
+
+- [DeepSeek API](https://platform.deepseek.com/) — 默认 LLM
+- [Stability AI](https://platform.stability.ai/) — 默认文生图
+- [OpenAI API](https://platform.openai.com/) — 兼容接口
+
+### 游戏引擎
+
+- [Unity 2D](https://unity.com/solutions/2d) — 支持精灵图集导入
+- [Godot Engine](https://godotengine.org/) — 开源 2D/3D 引擎
+
+### 基础设施
+
+- [Docker](https://www.docker.com/) — 容器化
+- [SQLite](https://www.sqlite.org/) — 嵌入式数据库
+- [七牛云 Kodo](https://www.qiniu.com/products/kodo) — 对象存储
+
 ## License

 [MIT](LICENSE)
@@ -8,9 +8,111 @@ Go + Gin + Eino / Vite + React + TypeScript + zustand / SQLite / 七牛云对象

 ## 文档索引

- [后端工程](backend.md) — 分层结构、管线设计（PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter）、风格模型
- [前端工程](frontend.md) — 组件树、状态管理、路由、三栏工作台、自定义标签
- [异步任务](async-tasks.md) — 任务队列、状态机、并发控制、失败重试
- [数据存储](database.md) — SQLite 选型、表结构、七牛云对象存储
- [API 设计](api.md) — 接口列表、请求/响应示例、实现状态
- [预设风格键](style-keys.md) — 美术风格、色调、线条等风格键分类与可选值
+| 文档 | 说明 |
+|------|------|
+| [后端工程](backend.md) | 分层结构、管线设计（PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter）、风格模型 |
+| [前端工程](frontend.md) | 组件树、状态管理、路由、三栏工作台、自定义标签 |
+| [API 设计](api.md) | 接口列表、请求/响应示例、错误码、认证 |
+| [数据存储](database.md) | SQLite 选型、表结构、ER 关系、对象存储、去重策略 |
+| [异步任务](async-tasks.md) | 任务生命周期、并发控制、重试策略、进度推送 |
+| [预设风格键](style-keys.md) | 美术风格、色调、线条等风格键分类与可选值 |
+
+## 系统架构
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                     Frontend (Vite + React)              │
+│  ┌─────────┐ ┌──────────┐ ┌────────────┐ ┌──────────┐  │
+│  │ 画廊页   │ │ 三栏工作台 │ │ 结果预览页  │ │ 登录注册  │  │
+│  └─────────┘ └──────────┘ └────────────┘ └──────────┘  │
+│                      │ HTTP / WebSocket                  │
+└──────────────────────┼──────────────────────────────────┘
+                       │
+┌──────────────────────┼──────────────────────────────────┐
+│                 Backend (Go + Gin + Eino)                │
+│                      │                                   │
+│  ┌───────────────────▼──────────────────────────────┐   │
+│  │              Eino compose.Graph                    │   │
+│  │  ┌──────────────┐  ┌──────────────┐               │   │
+│  │  │PromptOptimizer│─▶│AssetGenerator│               │   │
+│  │  └──────────────┘  └──────────────┘               │   │
+│  │          ▲                 │                       │   │
+│  │          │    ┌────────────▼──────────┐            │   │
+│  │          │    │  QualitySupervisor    │            │   │
+│  │          │    └────────────┬──────────┘            │   │
+│  │          │          pass   │  fail (retry < 3)      │   │
+│  │          └────────────────┘                        │   │
+│  │          fail, retry ≥ 3                           │   │
+│  │                    │  ┌──────────────┐              │   │
+│  │                    └─▶│FormatAdapter │              │   │
+│  │                       └──────────────┘              │   │
+│  └────────────────────────────────────────────────────┘  │
+│                      │                                   │
+│         ┌────────────┼────────────┐                      │
+│         │            │            │                      │
+│    ┌────▼───┐  ┌─────▼────┐ ┌───▼──────┐               │
+│    │ SQLite  │  │ 七牛云 Kodo│ │ LLM API  │               │
+│    └────────┘  └──────────┘ └──────────┘               │
+└─────────────────────────────────────────────────────────┘
+```
+
+## 核心概念
+
+### 生成管线（Pipeline）
+
+基于 Eino `compose.Graph` 的四阶段管线。每个阶段是一个 Lambda 节点，通过 `StatePreHandler` / `StatePostHandler` 读写全局状态。质检不通过时，Graph 分支自动触发重优化，最多重试 3 次，超过后降级输出保证任务不阻塞。
+
+详见 [后端工程](backend.md#多阶段生成管线)。
+
+### 风格系统（Style）
+
+风格分为两层：
+
+- **工程风格（Project Style）**：工程级别的 kvPairs，保证同一工程下所有素材风格一致
+- **任务风格覆盖（Task Style Override）**：单次生成任务的风格差异，仅覆盖需要变化的键
+
+合并逻辑：`finalStyle = merge(projectStyle, taskStyle)`，任务同名键覆盖工程风格。
+
+详见 [后端工程 — 风格模型](backend.md#风格模型) 和 [预设风格键](style-keys.md)。
+
+### 任务系统（Task）
+
+采用"提交-异步执行-轮询/推送"模式。API 同步返回 taskId，后台 goroutine 执行管线，前端通过 HTTP 轮询或 WebSocket 获取实时进度。
+
+详见 [异步任务](async-tasks.md)。
+
+### 数据模型
+
+```
+user 1──N project
+project 1──1 project_style
+project 1──N task
+task 1──N asset
+```
+
+详见 [数据存储](database.md#er-关系)。
+
+## 命令行参考
+
+### 后端
+
+```bash
+cd backend
+go mod tidy                  # 安装依赖
+go run cmd/main.go           # 开发服务器
+go build -o bin/gen2d cmd/main.go  # 构建
+go test ./...                # 全部测试
+go test -run TestX ./internal/service/  # 单测
+golangci-lint run            # 代码检查
+```
+
+### 前端
+
+```bash
+cd frontend
+npm install          # 安装依赖
+npm run dev          # 开发服务器
+npm run build        # 生产构建
+npm run preview      # 预览构建产物
+npm run typecheck    # 类型检查
+```