技术方案设计（阶段二）

前置条件：用户已确认阶段一（/proj-analyze-req）的需求分析文档，且全流程任务文档已创建 目标：设计技术实现方案，明确数据库、接口、代码结构 产出：技术方案文档（用户确认后进入开发阶段）

---

执行流程

Step 0: 校验任务文档 → Step 1: 探索现有代码 → Step 2: 设计技术方案 → Step 3: 输出方案文档 → Step 4: 用户确认 → Step 5: 生成任务

---

Step 0: 校验任务文档

• 确认全流程任务文档存在
• 若缺失，先创建任务文档骨架并补齐流程状态与上下文快照

---

Step 1: 探索现有代码

在设计方案前，先了解项目现状：

探索内容	目的
相关模块代码	了解现有实现方式
类似功能实现	参考已有模式
公共类和工具	复用现有组件
数据库表结构	了解关联关系

---

Step 2: 设计技术方案

2.1 数据库设计

表命名规范：

• 表名：小写下划线，单数（如 user, order_item）
• 字段名：小写下划线（如 user_id, create_time）
• 主键：id BIGINT AUTO_INCREMENT
• 外键：{关联表}_id
• 索引：idx_{表名}_{字段}

通用字段（每张业务表必须包含）：

id BIGINT AUTO_INCREMENT PRIMARY KEY,
del_flag TINYINT(1) DEFAULT 0 COMMENT '删除标记',
create_by VARCHAR(64) COMMENT '创建人',
create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
update_by VARCHAR(64) COMMENT '更新人',
update_time DATETIME COMMENT '更新时间'

2.2 接口设计规范

接口文档要求：

• 完整参数：必须包含所有请求参数的类型、是否必填、示例值
• 响应格式：提供完整的JSON响应示例，包含所有字段
• 错误码：列出所有可能的错误码和说明
• 业务场景：说明接口的使用场景和业务含义

2.3 枚举类设计规范

标准枚举格式：参考模板中的枚举类设计，必须包含getByCode和getMessageByCode方法

2.4 技术架构澄清

按需澄清原则：只在涉及相关技术时才需要澄清

常见澄清场景：

• 消息/通知功能 → 澄清：推送服务 vs 前端轮询？
• 实时数据展示 → 澄清：Redis vs 数据库？
• 历史数据管理 → 澄清：永久保存 vs 定期清理？
• 在线状态功能 → 澄清：实时更新机制？存储位置？

---

Step 3: 输出方案文档

在充分澄清后，使用模板输出技术方案文档。

模板文件：技术方案模板

保存位置：docs/design/{YYYYMMDD}_{中文模块名}_技术.md

注意：技术方案设计时如发现需求遗漏或变更，需同步更新需求文档。

同步更新任务文档：

• 将“技术方案”状态标记为进行中/已完成
• 在产物清单中记录技术方案文档路径
• 更新上下文快照与下一步指令

---

Step 4: 用户确认

4.1 确认话术

输出技术方案后，必须使用以下话术请求确认：

以上是技术实现方案，请确认：
1. 数据库表结构和字段是否符合预期？
2. 接口设计是否满足需求？
3. 是否需要调整？

确认后我将开始编码开发。

4.2 用户反馈处理

用户反馈	处理方式
"确认"/"没问题"/"可以"	调用 /proj-task 拆分任务，开始开发
"字段需要调整xxx"	修改表结构设计，再次确认
"接口需要增加xxx"	补充接口设计，再次确认
"取消"/"不做了"	结束流程

---

注意事项

1. 前置检查 - 确保阶段一需求已确认，否则不能开始
2. 参考现有 - 设计前先看项目已有实现，保持风格一致
3. 命名规范 - 严格遵循 CLAUDE.md 命名规范
4. 不要过度设计 - 按需求来，不主动加功能
5. 确认再开发 - 方案确认前禁止创建/修改任何代码文件

---

Step 5: 生成任务（用户确认后）

用户确认技术方案后：

1. 保存方案文档（中等/复杂需求）：docs/design/{YYYYMMDD}_{中文模块名}_技术.md
2. 生成任务清单：调用 /proj-task 创建任务
3. 开始开发：按顺序 SQL → Entity → Mapper → DTO → Service → Controller
4. 开发完成：调用 /proj-review 自检

同步更新任务文档：

• 标记“方案确认”状态为已完成
• 更新“下一步指令”为进入任务拆分