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
@@ -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    # 类型检查
+```