# 阶段 9：闭环复盘和接口文档技能书

## A. 元数据 (Metadata)

**name**: `phase9-retro-api-docs`

**description**: 在 Datai 项目中，基于已完成的变更记录，创建复盘文档和 API 文档，总结整个需求执行过程，包括成功经验、改进点、问题分析等，并记录 API 接口的设计和实现，更新索引和会话记录。此技能确保项目的持续改进和 API 的可文档化。

---

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

### 触发关键词
当用户输入包含以下关键词时，必须觉醒此技能：
- "复盘"、"复盘文档"、"Retrospective"
- "API 文档"、"接口文档"
- "进入阶段 9"、"下一阶段"
- "总结"、"文档"、"回顾"

### 触发场景
- 用户确认阶段 8 完成，要求进入阶段 9
- 用户要求创建复盘文档和 API 文档
- 用户询问如何进行复盘
- 用户提到"按照项目规则"或"SSOT 流程"进行复盘和 API 文档编写

### 操作路径
此技能涉及以下文件和目录的操作：
- **读取**: `docs/sessions/YYYY-MM-DD-00X-session.md` (阶段 8 更新的会话记录)
- **创建**: `docs/retros/YYYY-MM-DD-00X-retro.md`
- **创建**: `docs/api-docs/YYYY-MM-DD-00X-api.md`
- **更新**: `docs/index.md`
- **更新**: `docs/requirements/YYYY-MM-DD-00X-需求名.md` (添加复盘和 API 文档引用)
- **更新**: `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\sessions\YYYY-MM-DD-00X-session.md) - 阶段 8 更新的会话记录
- [项目规则](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. 复盘文档约束（强制）
- 必须在 `docs/retros/` 目录下创建复盘文档
- 文档命名：`YYYY-MM-DD-00X-retro.md`
- 必须使用复盘文档模板
- 必须包含元数据、复盘概述、成功经验、改进点、问题分析、行动计划、相关文档等章节
- 必须对比目标与实际产出
- 必须提取模式：记录 3 条有效的 Prompt 技巧和 3 个避免的坑
- 必须进行模板迭代：如果发现模板不适用，立即执行一次"模板更新"

#### 2. API 文档约束（强制）
- 必须在 `docs/api-docs/` 目录下创建 API 文档
- 文档命名：`YYYY-MM-DD-00X-api.md`
- 必须使用 API 文档模板
- 必须包含元数据、API 概述、接口列表、错误码、相关文档等章节
- 必须详细描述每个接口的请求方式、请求路径、请求参数、响应参数、示例等

#### 3. 索引更新约束（强制）
- 必须在创建复盘和 API 文档后立即更新 `docs/index.md`
- 必须更新需求文档，添加复盘和 API 文档引用
- 采用增量更新策略，**严禁**删除现有内容
- 索引链接格式：`[文档名](./相对路径/文件名.md)`

#### 4. 会话记录约束（强制）
- 必须更新 `docs/sessions/YYYY-MM-DD-00X-session.md`
- 必须更新当前阶段为"阶段 9：闭环复盘和接口文档"
- 必须记录复盘和 API 文档链接

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

#### 步骤 1：复盘分析（Let's think step by step）
在创建复盘文档前，必须执行以下分析：

1. **回顾整个需求执行过程**
   - 从阶段 1 到阶段 8 的完整过程
   - 识别每个阶段的执行情况
   - 识别成功的经验和失败的教训

2. **识别成功经验**
   - 哪些做法是成功的，值得推广
   - 哪些决策是正确的，带来了好的结果
   - 哪些工具和方法是有效的

3. **识别改进点**
   - 哪些地方可以改进
   - 哪些决策可以优化
   - 哪些工具和方法可以改进

4. **分析问题**
   - 执行过程中遇到了哪些问题
   - 问题的根源是什么
   - 如何避免这些问题再次发生

5. **制定行动计划**
   - 针对改进点和问题，制定具体的行动计划
   - 明确责任人和时间节点

6. **提取模式**
   - 记录 3 条有效的 Prompt 技巧
   - 记录 3 个避免的坑

7. **模板迭代**
   - 检查当前使用的模板是否适用
   - 如果发现模板不适用，立即执行一次"模板更新"

#### 步骤 2：创建复盘文档
1. **确定文档路径**
   - 路径：`docs/retros/YYYY-MM-DD-00X-retro.md`
   - 使用 Write 工具创建文件
   - 确保目录存在（使用 LS 工具检查）

2. **填充文档内容**
   - **元数据**：包含需求编号、创建时间、创建人等
   - **复盘概述**：简述本次复盘的目的和范围
   - **成功经验**：记录 3-5 条成功经验
   - **改进点**：记录 3-5 个改进点
   - **问题分析**：记录 2-3 个主要问题及其分析
   - **行动计划**：记录针对改进点和问题的行动计划
   - **相关文档**：添加需求文档链接

3. **文档质量检查**
   - 使用 Read 工具读取刚创建的复盘文档
   - 检查是否符合复盘文档模板
   - 检查是否对比了目标与实际产出
   - 检查是否提取了模式
   - 检查是否进行了模板迭代

#### 步骤 3：API 文档分析（Let's think step by step）
在创建 API 文档前，必须执行以下分析：

1. **分析 API 接口的设计和实现**
   - 读取阶段 6 生成的代码文件
   - 识别所有 API 接口
   - 确定接口的请求方式、请求路径、请求参数、响应参数等
   - 确定接口的错误码

2. **确定 API 文档的结构和内容**
   - API 概述
   - 接口列表
   - 错误码
   - 相关文档

#### 步骤 4：创建 API 文档
1. **确定文档路径**
   - 路径：`docs/api-docs/YYYY-MM-DD-00X-api.md`
   - 使用 Write 工具创建文件
   - 确保目录存在（使用 LS 工具检查）

2. **填充文档内容**
   - **元数据**：包含需求编号、创建时间、创建人等
   - **API 概述**：简述 API 的核心功能和用途
   - **接口列表**：详细描述每个 API 接口：
     - 接口名称
     - 请求方式
     - 请求路径
     - 请求参数
     - 响应参数
     - 示例
   - **错误码**：描述 API 可能返回的错误码及其含义
   - **相关文档**：添加需求文档和设计文档链接

3. **文档质量检查**
   - 使用 Read 工具读取刚创建的 API 文档
   - 检查是否符合 API 文档模板
   - 检查接口描述是否详细、准确
   - 检查示例是否完整、正确
   - 检查错误码是否清晰、全面

#### 步骤 5：更新索引和需求文档
1. **读取现有索引**
   - 使用 Read 工具读取 `docs/index.md`
   - 找到"复盘文档"和"API 文档"部分
   - 如果不存在，则创建这些部分

2. **添加新文档链接**
   - 在"复盘文档"部分追加新复盘文档
   - 格式：`- [复盘文档](./retros/YYYY-MM-DD-00X-retro.md) - [功能名]`
   - 示例：`- [用户登录功能复盘](./retros/2026-01-21-001-retro.md) - 用户登录功能`
   
   - 在"API 文档"部分追加新 API 文档
   - 格式：`- [API 文档](./api-docs/YYYY-MM-DD-00X-api.md) - [功能名]`
   - 示例：`- [用户登录功能 API 文档](./api-docs/2026-01-21-001-api.md) - 用户登录功能`

3. **更新需求文档**
   - 使用 Read 工具读取需求文档
   - 在"相关文档"部分添加复盘和 API 文档引用
   - 格式：`- [复盘文档](../retros/YYYY-MM-DD-00X-retro.md)`
   - 格式：`- [API 文档](../api-docs/YYYY-MM-DD-00X-api.md)`
   - 使用 Write 工具更新需求文档

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

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

2. **更新阶段 9 信息**
   - 更新"当前阶段"为"阶段 9：闭环复盘和接口文档"
   - 更新"阶段 9：闭环复盘和接口文档"的状态为"已完成"
   - 添加生成的复盘和 API 文档链接
   - 记录复盘的主要结论

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

#### 步骤 7：确认与询问
1. **向用户确认**
   - 显示复盘文档的链接
   - 显示 API 文档的链接
   - 询问："复盘和 API 文档是否完整？"
   - 询问："是否进入下一阶段（代码提交）？"

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

### 工具调用

#### 必须使用的工具
1. **Read 工具**：读取现有文件
   - 使用场景：读取会话记录、索引、需求文档、会话记录
   - 命令：`Read(file_path="d:\\idea_demo\\datai\\docs\\sessions\\2026-01-21-001-session.md")`

2. **Write 工具**：创建或更新文件
   - 使用场景：创建复盘文档、创建 API 文档、更新索引、更新需求文档、更新会话记录
   - 命令：`Write(file_path="d:\\idea_demo\\datai\\docs\\retros\\2026-01-21-001-retro.md", content="...")`

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

4. **SearchCodebase 工具**：搜索 API 接口
   - 使用场景：查找生成的 API 接口代码
   - 命令：`SearchCodebase(information_request="查找 datai-modules-system 模块下的 Controller 类和 API 接口")`

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

---

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

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

#### 错误 1：复盘内容不真实、不深入
**错误示例**：
```markdown
## 成功经验
1. 团队协作良好
2. 进度按时完成
3. 代码质量高

## 改进点
1. 可以更快完成
2. 可以更仔细
3. 可以更好
```

**问题**：
- 复盘内容过于笼统，没有具体的案例和分析
- 没有对比目标与实际产出
- 没有提取有效的 Prompt 技巧和避免的坑
- 没有制定具体的行动计划

**正确示例**：
```markdown
## 成功经验
1. **SSOT 流程的严格执行**：从需求定义到代码提交的每个阶段都严格按照项目规则执行，确保了所有开发活动都有文档依据，提高了代码的可追溯性和可维护性。
2. **详细的提示词设计**：阶段 5 生成的提示词包含了详细的输出格式要求、代码规范要求和测试要求，确保了生成的代码符合项目规范和需求。
3. **完整的会话记录**：阶段 7 记录了完整的会话过程，包括对话记录、生成的文档和代码、关键决策等，确保了会话的可追溯性和完整性。

## 改进点
1. **阶段间的过渡可以更流畅**：在阶段转换时，可以更主动地向用户解释下一阶段的目的和流程，提高用户的理解和参与度。
2. **代码生成前的验证可以更严格**：在生成代码前，可以增加对设计文档和决策记录的再次验证，确保代码生成的准确性。
3. **API 文档的自动生成可以考虑**：可以探索使用 Swagger 等工具自动生成 API 文档，提高文档的准确性和维护性。

## 问题分析
1. **问题 1**：在阶段 6 生成代码时，发现部分代码不符合若依框架规范
   - **根因**：提示词中的代码规范要求不够具体
   - **解决方案**：在后续的提示词设计中，增加更具体的若依框架规范要求

2. **问题 2**：在阶段 7 更新会话记录时，发现部分对话记录缺失
   - **根因**：会话记录的更新不及时
   - **解决方案**：在每个阶段完成后立即更新会话记录，确保对话记录的完整性

## 行动计划
1. **针对改进点 1**：在阶段转换时，增加对下一阶段的目的和流程的解释，责任：AI Assistant，时间：立即执行
2. **针对改进点 2**：在生成代码前，增加对设计文档和决策记录的再次验证，责任：AI Assistant，时间：立即执行
3. **针对改进点 3**：探索使用 Swagger 等工具自动生成 API 文档，责任：项目团队，时间：下一个迭代
4. **针对问题 1**：在后续的提示词设计中，增加更具体的若依框架规范要求，责任：AI Assistant，时间：立即执行
5. **针对问题 2**：在每个阶段完成后立即更新会话记录，责任：AI Assistant，时间：立即执行

## 提取模式
### 有效的 Prompt 技巧
1. **具体的输出格式要求**：在提示词中明确指定需要生成的文件、路径、格式等，可以提高生成代码的准确性和规范性。
2. **引用真源**：在提示词开头引用需求文档和设计文档的链接，可以确保生成的代码符合需求和设计要求。
3. **详细的代码规范要求**：在提示词中明确指定代码规范、命名规范、注释规范等，可以提高生成代码的质量和可读性。

### 避免的坑
1. **不要使用模糊的描述**：在提示词中使用模糊的描述（如"请生成高质量的代码"），会导致生成的代码不符合预期。
2. **不要忽略测试要求**：在提示词中忽略测试要求，会导致生成的代码缺少单元测试，降低代码的质量和可靠性。
3. **不要违反项目规则**：在代码生成过程中违反项目规则（如不遵循若依框架规范），会导致生成的代码不符合项目要求，需要重新生成。

## 模板迭代
经过本次复盘，发现当前的提示词模板（`docs/Prompt/0000-template.md`）在代码规范要求方面可以更具体，特别是针对若依框架的规范要求。计划在下一个迭代中更新提示词模板，增加更具体的若依框架规范要求。
```

#### 错误 2：API 文档内容不详细、不准确
**错误示例**：
```markdown
## 接口列表
### 接口 1：登录接口
- 请求方式：POST
- 请求路径：/api/system/auth/login
- 请求参数：
  - username：用户名
  - password：密码
- 响应参数：
  - token：令牌
```

**问题**：
- API 文档内容过于简单
- 请求参数缺少类型、是否必填等信息
- 响应参数缺少类型、说明等信息
- 缺少示例
- 缺少错误码

**正确示例**：
```markdown
## 接口列表
### 接口 1：登录接口
- **功能描述**：用户登录接口，用于验证用户身份并生成令牌
- **请求方式**：POST
- **请求路径**：`/api/system/auth/login`
- **请求参数**：
  | 参数名 | 类型 | 必填 | 说明 |
  |--------|------|------|------|
  | username | String | 是 | 用户名，长度 1-30 字符 |
  | password | String | 是 | 密码，长度 6-20 字符 |
  | code | String | 是 | 验证码，长度 4 字符 |
  | uuid | String | 是 | 验证码唯一标识，长度 36 字符 |
- **响应参数**：
  | 参数名 | 类型 | 说明 |
  |--------|------|------|
  | code | Integer | 状态码（200 成功，其他失败） |
  | msg | String | 提示信息 |
  | token | String | JWT 令牌，用于后续请求的身份验证 |
- **成功示例**：
  ```json
  {
    "code": 200,
    "msg": "操作成功",
    "token": "eyJhbGciOiJIUzUxMiJ9..."
  }
  ```
- **失败示例**：
  ```json
  {
    "code": 500,
    "msg": "用户名或密码错误"
  }
  ```
- **错误码**：
  - 500：用户名或密码错误
  - 501：验证码错误
  - 502：用户已停用
  - 503：登录失败次数过多
  ```
```

#### 错误 3：不提取模式和进行模板迭代
**错误示例**：
```markdown
## 提取模式
- 无

## 模板迭代
- 无
```

**问题**：
- 违反了项目规则
- 没有从本次执行中提取有效的经验和教训
- 没有对模板进行迭代和改进
- 无法实现持续改进

**正确示例**：
```markdown
## 提取模式
### 有效的 Prompt 技巧
1. **具体的输出格式要求**：在提示词中明确指定需要生成的文件、路径、格式等，可以提高生成代码的准确性和规范性。
2. **引用真源**：在提示词开头引用需求文档和设计文档的链接，可以确保生成的代码符合需求和设计要求。
3. **详细的代码规范要求**：在提示词中明确指定代码规范、命名规范、注释规范等，可以提高生成代码的质量和可读性。

### 避免的坑
1. **不要使用模糊的描述**：在提示词中使用模糊的描述（如"请生成高质量的代码"），会导致生成的代码不符合预期。
2. **不要忽略测试要求**：在提示词中忽略测试要求，会导致生成的代码缺少单元测试，降低代码的质量和可靠性。
3. **不要违反项目规则**：在代码生成过程中违反项目规则（如不遵循若依框架规范），会导致生成的代码不符合项目要求，需要重新生成。

## 模板迭代
经过本次复盘，发现当前的提示词模板（`docs/Prompt/0000-template.md`）在代码规范要求方面可以更具体，特别是针对若依框架的规范要求。计划在下一个迭代中更新提示词模板，增加更具体的若依框架规范要求。
```

#### 错误 4：不更新索引和需求文档
**错误示例**：
```
AI：创建复盘文档和 API 文档
AI：更新会话记录
AI：完成（忘记更新索引和需求文档）
```

**问题**：
- 违反了项目规则
- 索引中没有新增的复盘和 API 文档链接
- 需求文档中没有新增的复盘和 API 文档引用
- 其他开发人员无法快速找到这些文档

**正确示例**：
```
AI：创建复盘文档和 API 文档
AI：更新索引
AI：更新需求文档
AI：更新会话记录
AI：完成
```

#### 错误 5：不询问用户确认就进入下一阶段
**错误示例**：
```
AI：创建复盘文档和 API 文档
AI：进入阶段 10：代码提交（未询问用户）
```

**正确示例**：
```
AI：创建复盘文档和 API 文档
AI：复盘文档已创建：[链接]
AI：API 文档已创建：[链接]
AI：复盘和 API 文档是否完整？
AI：是否进入下一阶段（代码提交）？
```

### 验收清单（Checklist）

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

#### 复盘文档检查
- [ ] 复盘文档已创建在 `docs/retros/` 目录下
- [ ] 文档命名符合 `YYYY-MM-DD-00X-retro.md` 格式
- [ ] 文档包含所有必需章节（元数据、复盘概述、成功经验、改进点、问题分析、行动计划、相关文档）
- [ ] 元数据已正确填写（需求编号、创建时间、创建人）
- [ ] 复盘概述清晰、准确
- [ ] 成功经验具体、有案例
- [ ] 改进点具体、可操作
- [ ] 问题分析深入、有根因和解决方案
- [ ] 行动计划具体、有责任人和时间节点
- [ ] 已对比目标与实际产出
- [ ] 已提取 3 条有效的 Prompt 技巧
- [ ] 已提取 3 个避免的坑
- [ ] 已进行模板迭代

#### API 文档检查
- [ ] API 文档已创建在 `docs/api-docs/` 目录下
- [ ] 文档命名符合 `YYYY-MM-DD-00X-api.md` 格式
- [ ] 文档包含所有必需章节（元数据、API 概述、接口列表、错误码、相关文档）
- [ ] 元数据已正确填写（需求编号、创建时间、创建人）
- [ ] API 概述清晰、准确
- [ ] 接口列表完整、详细
- [ ] 每个接口包含：
  - 功能描述
  - 请求方式
  - 请求路径
  - 请求参数（包括类型、是否必填、说明）
  - 响应参数（包括类型、说明）
  - 成功示例
  - 失败示例（可选）
  - 错误码（可选）
- [ ] 错误码清晰、全面
- [ ] 相关文档链接正确

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

#### 需求文档更新检查
- [ ] 需求文档已更新
- [ ] 需求文档的"相关文档"部分已添加复盘和 API 文档引用
- [ ] 引用格式正确：`[复盘文档](../retros/YYYY-MM-DD-00X-retro.md)`

#### 会话记录更新检查
- [ ] 会话记录已更新
- [ ] 会话记录的"当前阶段"已更新为"阶段 9：闭环复盘和接口文档"
- [ ] 会话记录的"阶段 9：闭环复盘和接口文档"状态已更新为"已完成"
- [ ] 会话记录包含复盘和 API 文档链接
- [ ] 会话记录包含复盘的主要结论

#### 用户确认检查
- [ ] 已向用户显示复盘文档链接
- [ ] 已向用户显示 API 文档链接
- [ ] 已询问用户"复盘和 API 文档是否完整？"
- [ ] 已询问用户"是否进入下一阶段？"
- [ ] 已等待用户反馈

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

### Correct vs Incorrect 代码对比

#### Incorrect（错误示例）
```markdown
# 复盘文档

## 元数据
- 需求编号：001
- 创建时间：2026-01-21
- 创建人：AI Assistant

## 复盘概述
对用户登录功能的开发过程进行复盘

## 成功经验
1. 开发顺利
2. 代码质量高
3. 用户满意

## 改进点
1. 可以更快
2. 可以更好
3. 可以更仔细

## 问题分析
1. 无

## 行动计划
1. 无

## 相关文档
- [需求文档](../requirements/2026-01-21-001-用户登录功能.md)
```

#### Correct（正确示例）
```markdown
# 复盘文档

## 元数据
- 需求编号：001
- 创建时间：2026-01-21
- 创建人：AI Assistant
- 状态：已完成

## 复盘概述
本次复盘对用户登录功能的开发过程进行了全面回顾，从需求定义到代码提交的每个阶段都进行了分析，总结了成功经验、改进点、问题分析和行动计划，旨在提高后续开发过程的效率和质量。

## 目标与实际产出对比
### 目标
- 实现用户登录功能，包括用户名和密码验证、记住密码、自动登录等功能
- 遵循 SSOT 流程，确保所有开发活动都有文档依据
- 生成符合项目规范的代码

### 实际产出
- 成功实现了用户登录功能，包括用户名和密码验证、记住密码、自动登录等功能
- 严格按照 SSOT 流程执行，每个阶段都有相应的文档
- 生成的代码符合项目规范，包含单元测试
- 完整记录了会话过程，包括对话记录、生成的文档和代码、关键决策等

## 成功经验
1. **SSOT 流程的严格执行**：从需求定义到代码提交的每个阶段都严格按照项目规则执行，确保了所有开发活动都有文档依据，提高了代码的可追溯性和可维护性。
2. **详细的提示词设计**：阶段 5 生成的提示词包含了详细的输出格式要求、代码规范要求和测试要求，确保了生成的代码符合项目规范和需求。
3. **完整的会话记录**：阶段 7 记录了完整的会话过程，包括对话记录、生成的文档和代码、关键决策等，确保了会话的可追溯性和完整性。

## 改进点
1. **阶段间的过渡可以更流畅**：在阶段转换时，可以更主动地向用户解释下一阶段的目的和流程，提高用户的理解和参与度。
2. **代码生成前的验证可以更严格**：在生成代码前，可以增加对设计文档和决策记录的再次验证，确保代码生成的准确性。
3. **API 文档的自动生成可以考虑**：可以探索使用 Swagger 等工具自动生成 API 文档，提高文档的准确性和维护性。

## 问题分析
1. **问题 1**：在阶段 6 生成代码时，发现部分代码不符合若依框架规范
   - **根因**：提示词中的代码规范要求不够具体
   - **解决方案**：在后续的提示词设计中，增加更具体的若依框架规范要求

2. **问题 2**：在阶段 7 更新会话记录时，发现部分对话记录缺失
   - **根因**：会话记录的更新不及时
   - **解决方案**：在每个阶段完成后立即更新会话记录，确保对话记录的完整性

## 行动计划
1. **针对改进点 1**：在阶段转换时，增加对下一阶段的目的和流程的解释，责任：AI Assistant，时间：立即执行
2. **针对改进点 2**：在生成代码前，增加对设计文档和决策记录的再次验证，责任：AI Assistant，时间：立即执行
3. **针对改进点 3**：探索使用 Swagger 等工具自动生成 API 文档，责任：项目团队，时间：下一个迭代
4. **针对问题 1**：在后续的提示词设计中，增加更具体的若依框架规范要求，责任：AI Assistant，时间：立即执行
5. **针对问题 2**：在每个阶段完成后立即更新会话记录，责任：AI Assistant，时间：立即执行

## 提取模式
### 有效的 Prompt 技巧
1. **具体的输出格式要求**：在提示词中明确指定需要生成的文件、路径、格式等，可以提高生成代码的准确性和规范性。
2. **引用真源**：在提示词开头引用需求文档和设计文档的链接，可以确保生成的代码符合需求和设计要求。
3. **详细的代码规范要求**：在提示词中明确指定代码规范、命名规范、注释规范等，可以提高生成代码的质量和可读性。

### 避免的坑
1. **不要使用模糊的描述**：在提示词中使用模糊的描述（如"请生成高质量的代码"），会导致生成的代码不符合预期。
2. **不要忽略测试要求**：在提示词中忽略测试要求，会导致生成的代码缺少单元测试，降低代码的质量和可靠性。
3. **不要违反项目规则**：在代码生成过程中违反项目规则（如不遵循若依框架规范），会导致生成的代码不符合项目要求，需要重新生成。

## 模板迭代
经过本次复盘，发现当前的提示词模板（`docs/Prompt/0000-template.md`）在代码规范要求方面可以更具体，特别是针对若依框架的规范要求。计划在下一个迭代中更新提示词模板，增加更具体的若依框架规范要求，包括：
- 若依框架的包结构规范
- 若依框架的注解使用规范
- 若依框架的异常处理规范
- 若依框架的权限控制规范

## 相关文档
- [需求文档](../requirements/2026-01-21-001-用户登录功能.md)
- [设计文档](../design/2026-01-21-001-用户登录功能-设计.md)
- [决策记录](../decisions/2026-01-21-001-ADR-用户登录功能-技术选型.md)
```

---

## 附录：快速参考

### 文件路径速查
- 复盘文档：`docs/retros/YYYY-MM-DD-00X-retro.md`
- API 文档：`docs/api-docs/YYYY-MM-DD-00X-api.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\\sessions\\2026-01-21-001-session.md")

# 创建复盘文档
Write(file_path="d:\\idea_demo\\datai\\docs\\retros\\2026-01-21-001-retro.md", content="...")

# 创建 API 文档
Write(file_path="d:\\idea_demo\\datai\\docs\\api-docs\\2026-01-21-001-api.md", content="...")

# 读取索引
Read(file_path="d:\\idea_demo\\datai\\docs\\index.md")

# 更新索引
Write(file_path="d:\\idea_demo\\datai\\docs\\index.md", content="...")

# 搜索 API 接口
SearchCodebase(information_request="查找 datai-modules-system 模块下的 Controller 类和 API 接口")
```

### 阶段 9 输出清单
- [ ] 复盘文档：`docs/retros/YYYY-MM-DD-00X-retro.md`
- [ ] API 文档：`docs/api-docs/YYYY-MM-DD-00X-api.md`
- [ ] 更新的索引：`docs/index.md`
- [ ] 更新的需求文档：`docs/requirements/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) 的"阶段 10：代码提交"
- 准备检查所有生成的代码文件和文档文件
- 准备提交代码到本地仓库
- 准备询问用户是否提交到远程仓库