datai/docs/skill/phase6-code-generation.md

# 阶段 6：执行代码生成技能书

## A. 元数据 (Metadata)

**name**: `phase6-code-generation`

**description**: 在 Datai 项目中，基于已创建的需求文档、设计文档、决策记录和提示词，生成符合项目规范的代码文件，创建参考代码文档和实施方案文档，并更新索引和会话记录。此技能确保代码生成的准确性和规范性。

---

## B. 触发与定位 (Triggers & Scope)

### 触发关键词
当用户输入包含以下关键词时，必须觉醒此技能：
- "执行代码生成"、"生成代码"、"代码生成"
- "参考代码"、"实施方案"
- "进入阶段 6"、"下一阶段"
- "代码"、"实现"、"开发"

### 触发场景
- 用户确认阶段 5 完成，要求进入阶段 6
- 用户要求生成代码
- 用户询问如何执行代码生成
- 用户提到"按照项目规则"或"SSOT 流程"进行代码生成

### 操作路径
此技能涉及以下文件和目录的操作：
- **读取**: `docs/requirements/YYYY-MM-DD-00X-需求名.md` (阶段 1 创建的需求文档)
- **读取**: `docs/design/YYYY-MM-DD-00X-设计名.md` (阶段 2 创建的设计文档)
- **读取**: `docs/decisions/YYYY-MM-DD-00X-ADR-决策名.md` (阶段 3 创建的决策记录)
- **读取**: `docs/prompts/YYYY-MM-DD-00X-prompt-提示词名.md` (阶段 5 创建的提示词)
- **创建**: 项目目录下的 Java 代码文件（根据提示词要求）
- **创建**: `docs/reference-code/YYYY-MM-DD-00X-code-功能名.md`
- **创建**: `docs/implementation/YYYY-MM-DD-00X-implementation-功能名.md`
- **更新**: `docs/index.md`
- **更新**: `docs/design/YYYY-MM-DD-00X-设计名.md` (添加代码实现引用)
- **更新**: `docs/sessions/YYYY-MM-DD-00X-session.md`
- **读取**: `.trae/rules/project_rules.md` (项目规则)
- **读取**: `docs/Prompt/0004-单一真源文档驱动架构师.md` (SSOT 架构师提示词)

### SSOT 依赖
必须参考以下"唯一真源"：
- [需求文档](file:///d:\idea_demo\datai\docs\requirements\YYYY-MM-DD-00X-需求名.md) - 阶段 1 创建的需求文档
- [设计文档](file:///d:\idea_demo\datai\docs\design\YYYY-MM-DD-00X-设计名.md) - 阶段 2 创建的设计文档
- [决策记录](file:///d:\idea_demo\datai\docs\decisions\YYYY-MM-DD-00X-ADR-决策名.md) - 阶段 3 创建的决策记录
- [提示词](file:///d:\idea_demo\datai\docs\prompts\YYYY-MM-DD-00X-prompt-提示词名.md) - 阶段 5 创建的提示词
- [project_rules.md](file:///d:\idea_demo\datai\.trae\rules\project_rules.md) - 项目规则和阶段定义
- [0004-单一真源文档驱动架构师.md](file:///d:\idea_demo\datai\docs\Prompt\0004-单一真源文档驱动架构师.md) - SSOT 架构师提示词

---

## C. 核心指令集 (Instructions)

### 架构约束

#### 1. 代码生成约束（强制）
- 必须严格按照阶段 5 生成的提示词要求生成代码
- 必须遵循 Spring Boot 最佳实践
- 必须遵循若依框架规范
- 必须使用 MyBatis Plus 进行数据库操作（如果需要）
- 必须使用指定的包结构和文件路径
- 必须包含单元测试

#### 2. 参考代码文档约束（强制）
- 必须在 `docs/reference-code/` 目录下创建参考代码文档
- 文档命名：`YYYY-MM-DD-00X-code-功能名.md`
- 必须包含关键代码片段和说明
- 必须包含代码的使用方法和注意事项

#### 3. 实施方案文档约束（强制）
- 必须在 `docs/implementation/` 目录下创建实施方案文档
- 文档命名：`YYYY-MM-DD-00X-implementation-功能名.md`
- 必须包含实施步骤和注意事项
- 必须包含部署说明和验证方法

#### 4. 索引更新约束（强制）
- 必须在生成代码和文档后立即更新 `docs/index.md`
- 必须更新设计文档，添加代码实现引用
- 采用增量更新策略，**严禁**删除现有内容
- 索引链接格式：`[文档名](./相对路径/文件名.md)`
- 必须在 `docs/index.md` 中添加到"参考代码"和"实施方案"部分

#### 5. 会话记录约束（强制）
- 必须更新 `docs/sessions/YYYY-MM-DD-00X-session.md`
- 必须更新当前阶段为"阶段 6：执行代码生成"
- 必须记录生成的代码文件列表
- 必须记录参考代码和实施方案文档链接
- 必须记录 AI 的质疑、替代方案以及最终的复现步骤

### 业务逻辑 SOP（标准操作流程）

#### 步骤 1：代码生成分析（Let's think step by step）
在生成代码前，必须执行以下分析：

1. **分析需求和设计文档**
   - 读取阶段 1 创建的需求文档
   - 读取阶段 2 创建的设计文档
   - 读取阶段 3 创建的决策记录
   - 明确需求的核心功能和非功能需求
   - 明确设计的技术方案和架构

2. **确定需要生成的代码文件**
   - 读取阶段 5 创建的提示词
   - 明确需要生成的代码文件类型和路径
   - 明确代码规范和测试要求

3. **遵循 Spring Boot 最佳实践**
   - 明确 Spring Boot 的代码结构和规范
   - 明确若依框架的代码结构和规范
   - 明确 MyBatis Plus 的使用规范

#### 步骤 2：首句申明
在生成代码前，必须明确当前"现状"与"目标"：
```
现状：已完成需求定义、方案设计、方案决策、数据库结构生成和提示词生成
目标：根据提示词生成符合项目规范的代码文件，创建参考代码文档和实施方案文档
```

#### 步骤 3：加载阶段 5 准备的 Prompt，观察输出
1. **加载提示词**
   - 读取阶段 5 创建的提示词
   - 按照提示词的要求生成代码

2. **生成代码**
   - 生成 Java 代码文件
   - 保存到对应的项目目录
   - 确保代码符合项目规范
   - 确保代码包含单元测试

3. **观察输出**
   - 记录 AI 的质疑
   - 记录替代方案
   - 记录最终的复现步骤

#### 步骤 4：创建参考代码文档
1. **确定文档路径**
   - 路径：`docs/reference-code/YYYY-MM-DD-00X-code-功能名.md`
   - 使用 Write 工具创建文件
   - 确保目录存在（使用 LS 工具检查）

2. **填充文档内容**
   - **元数据**：包含需求编号、创建时间、创建人、状态等
   - **功能概述**：描述功能的核心内容
   - **代码结构**：描述生成的代码文件结构
   - **关键代码片段**：包含核心功能的代码片段
   - **使用方法**：描述代码的使用方法
   - **注意事项**：描述代码的注意事项

3. **文档质量检查**
   - 使用 Read 工具读取刚创建的文档
   - 检查是否符合参考代码文档约束
   - 检查代码片段是否正确
   - 检查使用方法是否清晰

#### 步骤 5：创建实施方案文档
1. **确定文档路径**
   - 路径：`docs/implementation/YYYY-MM-DD-00X-implementation-功能名.md`
   - 使用 Write 工具创建文件
   - 确保目录存在（使用 LS 工具检查）

2. **填充文档内容**
   - **元数据**：包含需求编号、创建时间、创建人、状态等
   - **实施概述**：描述实施的核心内容
   - **实施步骤**：描述实施的详细步骤
   - **注意事项**：描述实施的注意事项
   - **部署说明**：描述部署的方法和步骤
   - **验证方法**：描述验证的方法和步骤

3. **文档质量检查**
   - 使用 Read 工具读取刚创建的文档
   - 检查是否符合实施方案文档约束
   - 检查实施步骤是否清晰
   - 检查部署说明是否详细

#### 步骤 6：更新索引和设计文档
1. **读取现有索引**
   - 使用 Read 工具读取 `docs/index.md`
   - 找到"参考代码"和"实施方案"部分
   - 如果不存在，则创建这些部分

2. **添加新文档链接**
   - 在"参考代码"部分追加新参考代码
   - 格式：`- [参考代码名](./reference-code/YYYY-MM-DD-00X-code-功能名.md) - [描述]`
   - 示例：`- [用户登录功能参考代码](./reference-code/2026-01-21-001-code-用户登录功能.md) - 用户登录功能的参考代码`
   
   - 在"实施方案"部分追加新实施方案
   - 格式：`- [实施方案名](./implementation/YYYY-MM-DD-00X-implementation-功能名.md) - [描述]`
   - 示例：`- [用户登录功能实施方案](./implementation/2026-01-21-001-implementation-用户登录功能.md) - 用户登录功能的实施方案`

3. **更新设计文档**
   - 使用 Read 工具读取设计文档
   - 在"相关文档"部分添加代码实现引用
   - 格式：`- [参考代码](../reference-code/YYYY-MM-DD-00X-code-功能名.md)`
   - 格式：`- [实施方案](../implementation/YYYY-MM-DD-00X-implementation-功能名.md)`
   - 使用 Write 工具更新设计文档

4. **保存索引**
   - 使用 Write 工具更新 `docs/index.md`
   - **严禁**删除现有内容，只追加新内容

#### 步骤 7：更新会话记录
1. **读取现有会话记录**
   - 使用 Read 工具读取 `docs/sessions/YYYY-MM-DD-00X-session.md`

2. **更新阶段 6 信息**
   - 更新"当前阶段"为"阶段 6：执行代码生成"
   - 更新"阶段 6：执行代码生成"的状态为"已完成"
   - 添加生成的代码文件列表
   - 添加参考代码和实施方案文档链接
   - 记录 AI 的质疑、替代方案以及最终的复现步骤

3. **保存会话记录**
   - 使用 Write 工具更新会话记录

#### 步骤 8：确认与询问
1. **向用户确认**
   - 显示生成的代码文件列表
   - 显示参考代码和实施方案文档的链接
   - 询问："代码是否正确？"
   - 询问："是否进入下一阶段（记录当前会话）？"

2. **等待用户反馈**
   - 如果用户不满意，询问具体需要修改的地方
   - 如果用户要求回退，执行回退机制（见错误陷阱部分）
   - 如果用户确认，标记阶段 6 为已完成，准备进入阶段 7

### 工具调用

#### 必须使用的工具
1. **Read 工具**：读取现有文件
   - 使用场景：读取需求文档、设计文档、决策记录、提示词、索引、会话记录
   - 命令：`Read(file_path="d:\\idea_demo\\datai\\docs\\prompts\\2026-01-21-001-prompt-用户登录功能.md")`

2. **Write 工具**：创建或更新文件
   - 使用场景：生成代码文件、创建参考代码文档、创建实施方案文档、更新索引、更新设计文档、更新会话记录
   - 命令：`Write(file_path="d:\\idea_demo\\datai\\datai-modules-system\\src\\main\\java\\com\\datai\\modules\\system\\controller\\SysLoginController.java", content="...")`

3. **LS 工具**：检查目录是否存在
   - 使用场景：创建文档前检查 `docs/reference-code/` 和 `docs/implementation/` 目录
   - 命令：`LS(path="d:\\idea_demo\\datai\\docs")`

4. **RunCommand 工具**：运行代码验证
   - 使用场景：运行单元测试验证代码正确性
   - 命令：`RunCommand(command="mvn test", blocking=true, requires_approval=false, target_terminal="new")`

#### 可选使用的工具
1. **SearchCodebase 工具**：搜索现有代码
   - 使用场景：查找现有代码作为参考
   - 命令：`SearchCodebase(information_request="查找 datai-modules-system 模块下的 Controller 类")`

2. **GetDiagnostics 工具**：获取代码诊断
   - 使用场景：检查代码的语法错误和类型错误
   - 命令：`GetDiagnostics(uri="d:\\idea_demo\\datai\\datai-modules-system\\src\\main\\java\\com\\datai\\modules\\system\\controller\\SysLoginController.java")`

3. **TodoWrite 工具**：管理任务
   - 使用场景：跟踪阶段执行进度
   - 命令：`TodoWrite(todos=[...])`

---

## D. 错误陷阱与验证 (Anti-Patterns & Checklist)

### 常见错误（Anti-Patterns）

#### 错误 1：不按提示词要求生成代码
**错误示例**：
```
AI：读取提示词，要求生成 Controller、Service、Mapper、Entity
AI：只生成了 Controller 和 Service，没有生成 Mapper 和 Entity
```

**问题**：
- 没有按照提示词要求生成所有代码文件
- 违反了阶段 5 生成的提示词约束

**正确示例**：
```
AI：读取提示词，要求生成 Controller、Service、Mapper、Entity
AI：按照提示词要求，生成了所有代码文件
AI：确保代码符合提示词的代码规范和测试要求
```

#### 错误 2：不包含单元测试
**错误示例**：
```
AI：生成代码，不包含单元测试
AI：违反了提示词的测试要求
```

**正确示例**：
```
AI：生成代码，包含单元测试
AI：确保单元测试覆盖率不低于 80%
AI：确保测试用例包含正常场景和异常场景
```

#### 错误 3：代码不符合项目规范
**错误示例**：
```java
// 违反若依框架规范的代码
public class loginController {
    public String login(String username, String password) {
        // 代码逻辑
    }
}
```

**问题**：
- 类名不符合规范（首字母小写，驼峰命名错误）
- 方法参数不符合规范（没有使用 DTO 类）
- 没有使用若依框架的注解
- 没有异常处理

**正确示例**：
```java
// 符合若依框架规范的代码
@RestController
@RequestMapping("/system/auth")
public class SysLoginController {
    @Autowired
    private SysLoginService loginService;

    @PostMapping("/login")
    public AjaxResult login(@RequestBody LoginBody loginBody) {
        // 代码逻辑
        return AjaxResult.success(token);
    }
}
```

#### 错误 4：不创建参考代码文档和实施方案文档
**错误示例**：
```
AI：生成代码
AI：更新索引和会话记录
AI：完成（忘记创建参考代码文档和实施方案文档）
```

**问题**：
- 违反了阶段 6 的要求
- 缺少代码的参考文档和实施方案

**正确示例**：
```
AI：生成代码
AI：创建参考代码文档
AI：创建实施方案文档
AI：更新索引和会话记录
AI：完成
```

#### 错误 5：不更新设计文档的代码实现引用
**错误示例**：
```
AI：生成代码
AI：创建参考代码文档和实施方案文档
AI：更新 docs/index.md
AI：完成（忘记更新设计文档）
```

**正确示例**：
```
AI：生成代码
AI：创建参考代码文档和实施方案文档
AI：更新 docs/index.md
AI：更新设计文档，添加代码实现引用
AI：完成
```

#### 错误 6：不询问用户确认就进入下一阶段
**错误示例**：
```
AI：生成代码
AI：进入阶段 7：记录当前会话（未询问用户）
```

**正确示例**：
```
AI：生成代码
AI：代码已生成，参考代码和实施方案文档已创建
AI：代码是否正确？
AI：是否进入下一阶段（记录当前会话）？
```

### 验收清单（Checklist）

在完成阶段 6 前，必须检查以下项目：

#### 代码生成检查
- [ ] 已按照提示词要求生成所有代码文件
- [ ] 代码文件保存到了正确的项目目录
- [ ] 代码符合 Spring Boot 最佳实践
- [ ] 代码符合若依框架规范
- [ ] 代码符合 MyBatis Plus 使用规范
- [ ] 代码包含单元测试
- [ ] 单元测试覆盖率不低于 80%
- [ ] 测试用例包含正常场景和异常场景
- [ ] 代码没有语法错误和类型错误

#### 参考代码文档检查
- [ ] 参考代码文档已创建在 `docs/reference-code/` 目录下
- [ ] 文档命名符合 `YYYY-MM-DD-00X-code-功能名.md` 格式
- [ ] 文档包含元数据
- [ ] 文档包含功能概述
- [ ] 文档包含代码结构
- [ ] 文档包含关键代码片段
- [ ] 文档包含代码的使用方法和注意事项

#### 实施方案文档检查
- [ ] 实施方案文档已创建在 `docs/implementation/` 目录下
- [ ] 文档命名符合 `YYYY-MM-DD-00X-implementation-功能名.md` 格式
- [ ] 文档包含元数据
- [ ] 文档包含实施概述
- [ ] 文档包含实施步骤
- [ ] 文档包含注意事项
- [ ] 文档包含部署说明
- [ ] 文档包含验证方法

#### 索引更新检查
- [ ] `docs/index.md` 已更新
- [ ] 新参考代码链接已添加到"参考代码"部分
- [ ] 新实施方案链接已添加到"实施方案"部分
- [ ] 索引链接格式正确：`[文档名](./相对路径/文件名.md)`
- [ ] 索引更新采用增量策略，未删除现有内容

#### 设计文档更新检查
- [ ] 设计文档已更新
- [ ] 设计文档的"相关文档"部分已添加参考代码和实施方案引用
- [ ] 引用格式正确：`[参考代码](../reference-code/YYYY-MM-DD-00X-code-功能名.md)`

#### 会话记录更新检查
- [ ] 会话记录已更新
- [ ] 会话记录的"当前阶段"已更新为"阶段 6：执行代码生成"
- [ ] 会话记录的"阶段 6：执行代码生成"状态已更新为"已完成"
- [ ] 会话记录包含生成的代码文件列表
- [ ] 会话记录包含参考代码和实施方案文档链接
- [ ] 会话记录包含 AI 的质疑、替代方案以及最终的复现步骤

#### 用户确认检查
- [ ] 已向用户显示生成的代码文件列表
- [ ] 已向用户显示参考代码和实施方案文档的链接
- [ ] 已询问用户"代码是否正确？"
- [ ] 已询问用户"是否进入下一阶段？"
- [ ] 已等待用户反馈

#### 回退机制检查（如果需要）
- [ ] 如果用户不满意，已询问具体需要修改的地方
- [ ] 如果用户要求回退，已删除相关代码文件
- [ ] 如果用户要求回退，已删除参考代码文档和实施方案文档
- [ ] 如果用户要求回退，已撤销索引更新
- [ ] 如果用户要求回退，已撤销设计文档更新
- [ ] 如果用户要求回退，已更新会话记录

### Correct vs Incorrect 代码对比

#### Incorrect（错误示例）
```java
// 违反若依框架规范的代码
public class loginController {
    public String login(String username, String password) {
        // 简单的用户名密码验证
        if ("admin".equals(username) && "123456".equals(password)) {
            return "success";
        } else {
            return "failure";
        }
    }
}
```

#### Correct（正确示例）
```java
// 符合若依框架规范的代码
@RestController
@RequestMapping("/system/auth")
public class SysLoginController {
    private static final Logger log = LoggerFactory.getLogger(SysLoginController.class);

    @Autowired
    private SysLoginService loginService;

    /**
     * 登录方法
     * 
     * @param loginBody 登录信息
     * @return 结果
     */
    @PostMapping("/login")
    public AjaxResult login(@RequestBody LoginBody loginBody) {
        AjaxResult ajax = AjaxResult.success();
        // 生成令牌
        String token = loginService.login(loginBody.getUsername(), loginBody.getPassword(), loginBody.getCode(),
                loginBody.getUuid());
        ajax.put(Constants.TOKEN, token);
        return ajax;
    }
}
```

---

## 附录：快速参考

### 文件路径速查
- 需求文档：`docs/requirements/YYYY-MM-DD-00X-需求名.md`
- 设计文档：`docs/design/YYYY-MM-DD-00X-设计名.md`
- 决策记录：`docs/decisions/YYYY-MM-DD-00X-ADR-决策名.md`
- 提示词：`docs/prompts/YYYY-MM-DD-00X-prompt-提示词名.md`
- 参考代码文档：`docs/reference-code/YYYY-MM-DD-00X-code-功能名.md`
- 实施方案文档：`docs/implementation/YYYY-MM-DD-00X-implementation-功能名.md`
- 主索引：`docs/index.md`
- 会话记录：`docs/sessions/YYYY-MM-DD-00X-session.md`
- 项目规则：`.trae/rules/project_rules.md`
- SSOT 架构师提示词：`docs/Prompt/0004-单一真源文档驱动架构师.md`

### 工具命令速查
```powershell
# 读取提示词
Read(file_path="d:\\idea_demo\\datai\\docs\\prompts\\2026-01-21-001-prompt-用户登录功能.md")

# 生成代码文件
Write(file_path="d:\\idea_demo\\datai\\datai-modules-system\\src\\main\\java\\com\\datai\\modules\\system\\controller\\SysLoginController.java", content="...")

# 创建参考代码文档
Write(file_path="d:\\idea_demo\\datai\\docs\\reference-code\\2026-01-21-001-code-用户登录功能.md", content="...")

# 创建实施方案文档
Write(file_path="d:\\idea_demo\\datai\\docs\\implementation\\2026-01-21-001-implementation-用户登录功能.md", content="...")

# 运行单元测试
RunCommand(command="mvn test", blocking=true, requires_approval=false, target_terminal="new")

# 检查代码诊断
GetDiagnostics(uri="d:\\idea_demo\\datai\\datai-modules-system\\src\\main\\java\\com\\datai\\modules\\system\\controller\\SysLoginController.java")
```

### 阶段 6 输出清单
- [ ] 代码文件：项目目录下的 Java 文件
- [ ] 参考代码文档：`docs/reference-code/YYYY-MM-DD-00X-code-功能名.md`
- [ ] 实施方案文档：`docs/implementation/YYYY-MM-DD-00X-implementation-功能名.md`
- [ ] 更新的索引：`docs/index.md`
- [ ] 更新的设计文档：`docs/design/YYYY-MM-DD-00X-设计名.md`
- [ ] 更新的会话记录：`docs/sessions/YYYY-MM-DD-00X-session.md`

### 下一阶段提示
如果用户确认进入下一阶段，请参考：
- [project_rules.md](file:///d:\idea_demo\datai\.trae\rules\project_rules.md) 的"阶段 7：记录当前会话"
- 准备回顾整个会话过程
- 准备更新会话记录
- 准备更新索引