技术方案设计（阶段二）
前置条件：用户已确认阶段一（/proj-analyze-req）的需求分析文档，且全流程任务文档已创建 目标：设计技术实现方案，明确数据库、接口、代码结构 产出：技术方案文档（用户确认后进入开发阶段）
执行流程
Step 0: 校验任务文档 → Step 1: 探索现有代码 → Step 2: 设计技术方案 → Step 3: 输出方案文档 → Step 4: 用户确认 → Step 5: 生成任务
Step 0: 校验任务文档
- 确认全流程任务文档存在
- 若缺失，先创建任务文档骨架并补齐流程状态与上下文快照
Step 1: 探索现有代码
在设计方案前，先了解项目现状：
| 探索内容 | 目的 |
|---|---|
| 相关模块代码 | 了解现有实现方式 |
| 类似功能实现 | 参考已有模式 |
| 公共类和工具 | 复用现有组件 |
| 数据库表结构 | 了解关联关系 |
Step 2: 设计技术方案
2.1 数据库设计
表命名规范：
- 表名：小写下划线，单数（如
sys_user,order_item） - 字段名：小写下划线（如
user_id,create_time） - 主键：
id BIGINT AUTO_INCREMENT - 外键：
{关联表}_id - 索引：
idx_{表名}_{字段}
关键字检查（必须做）：新增或重命名的表、字段禁止与目标 MySQL 版本的关键字完全同名（大小写不敏感，包含保留字和非保留关键字），不得用反引号规避。按 SQL 命名规范与校验方法 检查，并在技术方案中记录目标版本、校验来源、结果及改名映射。已有数据库的冲突名称先提交迁移方案，未经确认不得直接改名。
通用字段（每张业务表必须包含）：
sqlid 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" | 补充接口设计，再次确认 |
| "取消"/"不做了" | 结束流程 |
注意事项
- 前置检查 - 确保阶段一需求已确认，否则不能开始
- 参考现有 - 设计前先看项目已有实现，保持风格一致
- 命名规范 - 严格遵循 CLAUDE.md 命名规范
- 不要过度设计 - 按需求来，不主动加功能
- 确认再开发 - 方案确认前禁止创建/修改任何代码文件
Step 5: 生成任务（用户确认后）
用户确认技术方案后：
- 保存方案文档（中等/复杂需求）：
docs/design/{YYYYMMDD}_{中文模块名}_技术.md - 生成任务清单：调用
/proj-task创建任务 - 开始开发：按顺序 SQL → Entity → Mapper → DTO → Service → Controller
- 开发完成：调用
/proj-review自检
同步更新任务文档：
- 标记“方案确认”状态为已完成
- 更新“下一步指令”为进入任务拆分
