Phase 2: 设计

目标：用 AI 从需求文档产出完整的系统设计方案——数据模型、API、架构图、UI 原型。

预计时间：1-1.5 小时

前置：Phase 1 的需求文档（6 层分析 + MoSCoW 清单 + 用户故事）

工具：Claude Code（主力）、v0.dev（UI 原型）

为什么设计要在写代码之前

设计阶段改方案，成本约等于 0——改几行文档就行。开发阶段改方案，可能要重写半个系统。

AI 写代码很快，但如果数据模型设计错了，改起来比重写还痛苦。所以：先让 AI 帮你做设计，审核通过了再写代码。

AI 参与度

环节	你做	AI 做
数据模型	审核实体关系	生成 Schema
API 设计	确认端点合理性	生成 RESTful 规范
架构图	判断复杂度是否匹配	生成 Mermaid 代码
UI 原型	确认交互逻辑	生成可交互组件
技术选型	最终决策	对比分析

2.1 数据模型设计

方法论

数据模型设计分两步：

概念模型：先确定有哪些实体（表）、它们之间是什么关系——不涉及具体字段
物理模型：确定每个实体的字段、类型、约束、索引

为什么分两步？因为 AI 直接出物理模型容易”一上来就细节”，漏掉关键关系。先在概念层面达成共识，再往下走。

实操

Step 1：概念模型

基于以下需求分析，请设计数据库的概念模型。

## 核心功能（Must）
1. 创建和管理项目
2. 创建、分配、更新任务
3. 看板视图（按状态分列）
4. 按成员查看任务
5. 基础权限（管理员 vs 普通成员）

## 要求
- 只列出实体名称和关系，不需要具体字段
- 用 "一对多" "多对多" 标注关系类型
- 画出 Mermaid ER 图
- 说明每个实体的职责（一句话）

审核概念模型时重点看：

实体是否遗漏？（常见遗漏：项目成员关系表、任务状态变更记录）
关系类型对不对？（一个用户能属于多个项目 → 多对多，需要中间表）
是否过度设计？（10 人工具不需要”组织""部门”等实体）

Step 2：物理模型

概念模型已确认，请生成完整的物理模型。

## 要求
- 使用 Go + GORM 的 struct 格式
- 每个字段标注 gorm tag（类型、约束、索引）
- 每个字段加中文注释说明用途
- 特别注意：
  - 枚举字段用 string 还是 int？说明理由
  - 哪些字段需要索引？说明查询场景
  - 软删除还是硬删除？说明理由
  - created_at / updated_at 用 GORM 自动管理

审查要点

对照代码审查清单的数据模型部分：

主键用什么？自增 ID vs UUID？
外键关系正确吗？级联删除还是 SET NULL？
常用查询字段有索引吗？
敏感字段（密码）存储方式对吗？
状态字段（任务状态）有没有定义明确的枚举值？

产出

Mermaid ER 图（概念模型）
Go struct 定义（物理模型）

2.2 API 设计

方法论

数据模型定好后，设计 API。核心原则：

围绕资源设计：URL 是名词（/projects、/tasks），不是动词
先列端点，再定义格式：别一上来就写 JSON，先确认需要哪些端点
考虑前端怎么用：看板页面需要一次拿到哪些数据？

实操

Prompt：

基于以下数据模型和用户故事，设计 RESTful API。

[粘贴 Step 2 的数据模型]

## 要求

1. 先列出所有端点（Method + URL + 说明），分模块组织
2. 对每个端点定义：
   - 请求参数（Path / Query / Body）
   - 成功响应（JSON 示例）
   - 错误响应（状态码 + 消息）
3. 列表接口必须支持分页（cursor-based 或 offset）
4. 需要认证的接口标注 🔒
5. 关注点：
   - 看板页面需要哪些数据？是一个接口还是多个？
   - 任务状态变更是 PATCH 还是专门的 action 端点？
   - 批量操作需要吗？（如批量移动任务）

审查要点

对照配方手册的 API 设计速查表：

分页方式选对了吗？（offset 简单但有跳页问题，cursor 适合无限滚动）
需要限流吗？（10 人内部工具，大概率不需要）
错误响应格式统一吗？
有没有 N+1 查询风险？（看板页面一次要查项目 + 所有任务 + 任务分配人）

产出

API 端点列表
关键端点的请求/响应 JSON 示例

2.3 架构图

方法论

用 AI 生成 Mermaid 代码，可以直接在 Markdown 中渲染。重点是让 AI 理解你的实际规模，不要画出比你系统复杂 10 倍的架构图。

实操

Prompt：

请为项目管理工具生成两张架构图（Mermaid 格式）：

## 图 1：系统架构图
- 技术栈：React 前端 + Go/Gin 后端 + PostgreSQL
- 10 人内部使用，单机部署
- 不需要 Redis、消息队列、微服务
- 标注每一层的职责

## 图 2：核心数据流图
以"用户在看板上拖拽任务到下一个状态"为例，画出完整的数据流：
- 前端操作 → API 请求 → 后端处理 → 数据库变更 → 响应 → 前端更新

审查要点

架构是否和实际规模匹配？（10 人工具不需要 Load Balancer）
数据流是否完整？（有没有漏掉认证检查、权限校验）
是否可以直接给开发用？（图中的技术选择和你的一致吗）

产出

系统架构 Mermaid 图
核心数据流 Mermaid 图

2.4 UI/UX 原型

方法论

在写前端代码之前，先让 AI 生成原型。不需要精美——关键是把页面结构和交互逻辑确定下来。

两种路径：

快速路径：让 AI 用文字描述页面布局，你脑补
可视路径：让 AI 生成 React 组件 / 用 v0.dev 生成可交互原型

实操

方式 A：Claude Code 生成 React 原型

请为项目管理工具生成看板页面的 React 组件原型。

## 页面结构
- 顶部：项目名称 + 成员头像列表 + 筛选按钮
- 主体：3-4 列看板（待办 / 进行中 / 测试中 / 已完成）
- 每列：任务卡片列表（标题、分配人、截止日期、优先级标签）
- 任务卡片可拖拽到其他列

## 要求
- 使用 React + Tailwind CSS
- 不需要真实数据，用 mock data
- 不需要拖拽功能，只需要静态布局
- 生成一个独立的 HTML 文件，可以直接在浏览器打开预览

方式 B：v0.dev（如果有访问权限）

直接在 v0.dev 输入：

A project management kanban board with columns for Todo, In Progress, Testing, Done.
Each card shows task title, assignee avatar, due date, and priority tag.
Clean, minimal design. Light theme.

需要原型的关键页面：

看板页面（核心页面）
项目列表页
任务详情弹窗/页面
成员管理页面（管理员）

不需要每个页面都做精美原型。看板页面做一个可视原型，其他页面文字描述就够。

审查要点

页面信息层级对吗？（最重要的信息是否最显眼）
用户操作路径是否顺畅？（创建任务 → 分配 → 拖拽状态，几步完成？）
有没有遗漏的页面状态？（空状态、加载状态、错误状态）

产出

看板页面可视原型（HTML 或截图）
其他页面的文字描述

2.5 技术选型

方法论

技术选型不是选”最好的”技术，而是选最适合你约束条件的。用 ADR（Architecture Decision Record）格式记录选型理由，方便以后回溯”当时为什么选这个”。

实操

Prompt：

请为项目管理工具做技术选型，输出 ADR 格式。

## 约束条件
- 1 人开发（AI 辅助），1 个月 MVP
- 10 人内部使用，不需要公网访问
- 数据敏感，需要自部署
- 开发者熟悉 Go 和 React（或者都不熟悉，AI 辅助学习）

## 需要决策的点
1. 后端框架：Go/Gin vs Node/Express vs Python/FastAPI
2. 前端框架：React vs Vue vs 纯 HTML
3. 数据库：PostgreSQL vs SQLite vs MySQL
4. 部署方式：Docker Compose vs 直接跑 vs 云服务
5. 认证方式：JWT vs Session vs 简单密码

## ADR 格式
每个决策点写：
- **选择**：选了什么
- **理由**：为什么选这个（不超过 3 条）
- **代价**：选这个放弃了什么
- **替代方案**：考虑过但没选的，为什么不选

审查要点

选型是否和约束匹配？（一个月 MVP 不适合用不熟悉的技术栈）
AI 有没有推荐过度复杂的方案？（Kubernetes 部署 10 人工具）
是否考虑了 AI 辅助的因素？（AI 对某些技术栈的支持更好）

产出

一份 ADR 技术选型文档。

常见陷阱

陷阱	症状	对策
数据模型漏索引	AI 生成的 struct 没有 gorm 索引标注	明确要求在 Prompt 中加索引
API 忘记分页	列表接口返回所有数据	在 Prompt 中要求”列表必须分页”
架构过度复杂	10 人工具画出了微服务架构	在 Prompt 中写明用户规模和部署方式
跳过原型直接开发	做出来的 UI 和预期不一样	至少做看板页面的原型
技术选型跟风	AI 推荐 Next.js + Prisma（因为流行）	回到约束条件：1 人 1 个月

Mini Exercise

基于 Phase 1 的需求文档，产出以下设计文档：

✅ 概念模型 ER 图 + 物理模型 Go struct（2.1）
✅ API 端点列表 + 关键接口的 JSON 示例（2.2）
✅ 系统架构 Mermaid 图（2.3）
✅ 看板页面可视原型（2.4）
✅ ADR 技术选型文档（2.5）

提示：这 5 份文档加起来就是你的”设计包”，Phase 3 开发时直接喂给 AI。