# 阶段 8：变更记录与归档技能书

## A. 元数据 (Metadata)

**name**: `phase8-changelog`

**description**: 在 Datai 项目中，基于已完成的会话记录，创建变更日志，记录所有变更内容，包括新增功能、修改功能、删除功能、Bug 修复等，并更新索引和会话记录。此技能确保变更的可追溯性和透明性。

---

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

### 触发关键词
当用户输入包含以下关键词时，必须觉醒此技能：
- "变更记录"、"变更日志"、"Changelog"
- "归档"、"记录变更"
- "进入阶段 8"、"下一阶段"
- "变更"、"日志"、"记录"

### 触发场景
- 用户确认阶段 7 完成，要求进入阶段 8
- 用户要求创建变更日志
- 用户询问如何记录变更
- 用户提到"按照项目规则"或"SSOT 流程"进行变更记录

### 操作路径
此技能涉及以下文件和目录的操作：
- **创建**: `docs/changelog/YYYY-MM-DD-00X-changelog.md`
- **更新**: `CHANGELOG.md`（根目录）
- **更新**: `docs/index.md`
- **更新**: `docs/requirements/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\sessions\YYYY-MM-DD-00X-session.md) - 阶段 7 更新的会话记录
- [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 架构师提示词
- `CHANGELOG.md` - 根目录的变更日志

---

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

### 架构约束

#### 1. 变更日志约束（强制）
- 必须在 `docs/changelog/` 目录下创建变更日志
- 文档命名：`YYYY-MM-DD-00X-changelog.md`
- 必须使用变更日志模板
- 必须包含元数据、变更概述、变更内容、影响范围、相关文档等章节

#### 2. CHANGELOG.md 更新约束（强制）
- 必须更新根目录的 `CHANGELOG.md`
- 采用增量更新策略，**严禁**删除现有内容
- 必须按照时间顺序追加新的变更记录

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

#### 4. 会话记录约束（强制）
- 必须更新 `docs/sessions/YYYY-MM-DD-00X-session.md`
- 必须更新当前阶段为"阶段 8：变更记录与归档"
- 必须记录变更日志链接

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

#### 步骤 1：变更分析（Let's think step by step）
在创建变更日志前，必须执行以下分析：

1. **识别所有变更内容**
   - 读取阶段 7 更新的会话记录
   - 识别新增功能
   - 识别修改功能
   - 识别删除功能
   - 识别 Bug 修复
   - 识别性能优化
   - 识别文档更新

2. **确定变更的类型和影响范围**
   - 变更类型：新增功能、修改功能、删除功能、Bug 修复、性能优化、文档更新
   - 影响范围：
     - 模块级别（如 `datai-modules-system`）
     - 文件级别（如 `SysLoginController.java`）
     - 功能级别（如 "用户登录功能"）

3. **按照变更日志格式组织内容**
   - 按照变更类型分类
   - 按照影响范围排序
   - 确保每个变更项清晰、准确

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

2. **填充文档内容**
   - **元数据**：包含需求编号、创建时间、创建人等
   - **变更概述**：简述本次变更对项目的影响
   - **变更内容**：
     - 新增功能
     - 修改功能
     - 删除功能
     - Bug 修复
   - **影响范围**：描述变更的影响范围
   - **相关文档**：添加需求文档链接

3. **文档质量检查**
   - 使用 Read 工具读取刚创建的变更日志
   - 检查是否符合变更日志模板
   - 检查变更内容是否完整、准确
   - 检查影响范围是否清晰

#### 步骤 3：更新根目录 CHANGELOG.md
1. **读取现有 CHANGELOG.md**
   - 使用 Read 工具读取根目录的 `CHANGELOG.md`
   - 了解现有 CHANGELOG.md 的内容和结构

2. **追加新的变更记录**
   - 在 CHANGELOG.md 的顶部追加新的变更记录
   - 格式：
     ```markdown
     ## [版本号] - YYYY-MM-DD
     ### Added
     - 新增功能 1
     - 新增功能 2

     ### Changed
     - 修改功能 1
     - 修改功能 2

     ### Removed
     - 删除功能 1
     - 删除功能 2

     ### Fixed
     - Bug 修复 1
     - Bug 修复 2
     ```

3. **更新版本号**
   - 如果是主版本更新，版本号格式：`v1.0.0`
   - 如果是次版本更新，版本号格式：`v1.1.0`
   - 如果是补丁更新，版本号格式：`v1.1.1`

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

2. **添加新变更日志链接**
   - 在"变更日志"部分追加新变更日志
   - 格式：`- [变更日志](./changelog/YYYY-MM-DD-00X-changelog.md) - [变更概述]`
   - 示例：`- [用户登录功能变更日志](./changelog/2026-01-21-001-changelog.md) - 实现用户登录功能`

3. **在 docs/index.md 中标注该需求已完成**
   - 在需求文档链接后添加 "- 已完成" 标识
   - 示例：`- [用户登录功能](./requirements/2026-01-21-001-用户登录功能.md) - 已完成`

4. **更新需求文档**
   - 使用 Read 工具读取需求文档
   - 在"相关文档"部分添加变更日志引用
   - 格式：`- [变更日志](../changelog/YYYY-MM-DD-00X-changelog.md)`
   - 使用 Write 工具更新需求文档

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

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

2. **更新阶段 8 信息**
   - 更新"当前阶段"为"阶段 8：变更记录与归档"
   - 更新"阶段 8：变更记录与归档"的状态为"已完成"
   - 添加生成的变更日志链接
   - 记录变更的主要内容

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

#### 步骤 6：确认与询问
1. **向用户确认**
   - 显示变更日志的链接
   - 显示更新后的 CHANGELOG.md 的链接
   - 询问："变更日志是否准确？"
   - 询问："是否进入下一阶段（闭环复盘和接口文档）？"

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

### 工具调用

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

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

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

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

---

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

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

#### 错误 1：变更记录不完整
**错误示例**：
```markdown
## 变更内容
### 新增功能
- 用户登录功能
```

**问题**：
- 变更记录过于简单
- 没有描述具体的功能点
- 没有描述影响范围
- 没有描述相关文档

**正确示例**：
```markdown
## 变更内容
### 新增功能
- 实现用户登录功能，包括：
  - 用户名和密码验证
  - 记住密码功能
  - 自动登录功能
  - 登录失败提示
  - 登录成功后跳转到首页
- 新增相关代码文件：
  - `SysLoginController.java`
  - `SysLoginService.java`
  - `SysUserMapper.java`
  - `SysUser.java`
  - `SecurityConfig.java`
  - `SysLoginServiceTest.java`
```

#### 错误 2：不更新根目录 CHANGELOG.md
**错误示例**：
```
AI：创建变更日志
AI：更新 docs/index.md
AI：完成（忘记更新根目录 CHANGELOG.md）
```

**问题**：
- 违反了项目规则
- 根目录 CHANGELOG.md 是项目的主要变更记录
- 其他开发人员无法快速了解项目的变更情况

**正确示例**：
```
AI：创建变更日志
AI：更新根目录 CHANGELOG.md
AI：更新 docs/index.md
AI：完成
```

#### 错误 3：不标注需求已完成
**错误示例**：
```
AI：创建变更日志
AI：更新 CHANGELOG.md
AI：更新 docs/index.md，但没有标注需求已完成
AI：完成
```

**问题**：
- 违反了项目规则
- 无法从索引中快速了解需求的状态
- 其他开发人员无法快速了解项目的进度

**正确示例**：
```
AI：创建变更日志
AI：更新 CHANGELOG.md
AI：更新 docs/index.md，标注该需求已完成
AI：完成
```

#### 错误 4：不更新需求文档的变更日志引用
**错误示例**：
```
AI：创建变更日志
AI：更新 CHANGELOG.md
AI：更新 docs/index.md
AI：完成（忘记更新需求文档）
```

**问题**：
- 违反了 SSOT 原则
- 需求文档与变更日志之间缺少双向引用
- 无法从需求文档快速找到相关的变更日志

**正确示例**：
```
AI：创建变更日志
AI：更新 CHANGELOG.md
AI：更新 docs/index.md
AI：更新需求文档，添加变更日志引用
AI：完成
```

#### 错误 5：不询问用户确认就进入下一阶段
**错误示例**：
```
AI：创建变更日志
AI：进入阶段 9：闭环复盘和接口文档（未询问用户）
```

**正确示例**：
```
AI：创建变更日志
AI：变更日志已创建：[链接]
AI：CHANGELOG.md 已更新
AI：变更日志是否准确？
AI：是否进入下一阶段（闭环复盘和接口文档）？
```

### 验收清单（Checklist）

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

#### 变更日志完整性检查
- [ ] 变更日志已创建在 `docs/changelog/` 目录下
- [ ] 文档命名符合 `YYYY-MM-DD-00X-changelog.md` 格式
- [ ] 文档包含所有必需章节（元数据、变更概述、变更内容、影响范围、相关文档）
- [ ] 元数据已正确填写（需求编号、创建时间、创建人）
- [ ] 变更概述清晰、准确
- [ ] 变更内容完整、详细
- [ ] 影响范围明确
- [ ] 相关文档链接正确

#### 根目录 CHANGELOG.md 更新检查
- [ ] 根目录 CHANGELOG.md 已更新
- [ ] 新的变更记录已追加到 CHANGELOG.md 的顶部
- [ ] 变更记录格式符合要求
- [ ] 版本号格式正确

#### 索引更新检查
- [ ] `docs/index.md` 已更新
- [ ] 新变更日志链接已添加到"变更日志"部分
- [ ] 在 `docs/index.md` 中标注该需求已完成
- [ ] 索引链接格式正确：`[文档名](./相对路径/文件名.md)`
- [ ] 索引更新采用增量更新策略，未删除现有内容

#### 需求文档更新检查
- [ ] 需求文档已更新
- [ ] 需求文档的"相关文档"部分已添加变更日志引用
- [ ] 变更日志引用格式正确：`[变更日志](../changelog/YYYY-MM-DD-00X-changelog.md)`

#### 会话记录更新检查
- [ ] 会话记录已更新
- [ ] 会话记录的"当前阶段"已更新为"阶段 8：变更记录与归档"
- [ ] 会话记录的"阶段 8：变更记录与归档"状态已更新为"已完成"
- [ ] 会话记录包含变更日志链接
- [ ] 会话记录包含变更的主要内容

#### 用户确认检查
- [ ] 已向用户显示变更日志链接
- [ ] 已向用户显示更新后的 CHANGELOG.md 链接
- [ ] 已询问用户"变更日志是否准确？"
- [ ] 已询问用户"是否进入下一阶段？"
- [ ] 已等待用户反馈

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

### Correct vs Incorrect 代码对比

#### Incorrect（错误示例）
```markdown
# 变更日志

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

## 变更概述
实现用户登录功能

## 变更内容
### 新增功能
- 用户登录功能

## 影响范围
系统模块

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

#### Correct（正确示例）
```markdown
# 变更日志

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

## 变更概述
实现用户登录功能，包括用户名和密码验证、记住密码、自动登录、登录失败提示、登录成功后跳转到首页等功能。

## 变更内容
### 新增功能
- 实现用户登录功能，包括：
  - 用户名和密码验证（使用 BCrypt 加密）
  - 记住密码功能（使用 Cookie 存储）
  - 自动登录功能（使用 JWT Token）
  - 登录失败提示（显示具体错误信息）
  - 登录成功后跳转到首页（根据用户权限）

### 新增文档
- [需求文档](../requirements/2026-01-21-001-用户登录功能.md)
- [设计文档](../design/2026-01-21-001-用户登录功能-设计.md)
- [决策记录](../decisions/2026-01-21-001-ADR-用户登录功能-技术选型.md)
- [SQL 脚本](../sql/2026-01-21-001-user-login.sql)
- [提示词](../prompts/2026-01-21-001-prompt-用户登录功能.md)
- [参考代码文档](../reference-code/2026-01-21-001-code-用户登录功能.md)
- [实施方案文档](../implementation/2026-01-21-001-implementation-用户登录功能.md)

### 新增代码文件
- `datai-modules-system/src/main/java/com/datai/modules/system/controller/SysLoginController.java`
- `datai-modules-system/src/main/java/com/datai/modules/system/service/SysLoginService.java`
- `datai-modules-system/src/main/java/com/datai/modules/system/mapper/SysUserMapper.java`
- `datai-modules-system/src/main/java/com/datai/modules/system/domain/SysUser.java`
- `datai-modules-system/src/main/java/com/datai/modules/system/config/SecurityConfig.java`
- `datai-modules-system/src/test/java/com/datai/modules/system/service/SysLoginServiceTest.java`

## 影响范围
- 模块：`datai-modules-system`
- 功能：用户认证与授权
- 文件：6 个新文件

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

---

## 附录：快速参考

### 文件路径速查
- 变更日志：`docs/changelog/YYYY-MM-DD-00X-changelog.md`
- 根目录 CHANGELOG.md：`d:\\idea_demo\\datai\\CHANGELOG.md`
- 主索引：`docs/index.md`
- 会话记录：`docs/sessions/YYYY-MM-DD-00X-session.md`
- 项目规则：`.trae/rules/project_rules.md`
- SSOT 架构师提示词：`docs/Prompt/0004-单一真源文档驱动架构师.md`

### 工具命令速查
```powershell
# 读取根目录 CHANGELOG.md
Read(file_path="d:\\idea_demo\\datai\\CHANGELOG.md")

# 创建变更日志
Write(file_path="d:\\idea_demo\\datai\\docs\\changelog\\2026-01-21-001-changelog.md", content="...")

# 更新根目录 CHANGELOG.md
Write(file_path="d:\\idea_demo\\datai\\CHANGELOG.md", content="...")

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

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

### 阶段 8 输出清单
- [ ] 变更日志：`docs/changelog/YYYY-MM-DD-00X-changelog.md`
- [ ] 更新的根目录 CHANGELOG.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) 的"阶段 9：闭环复盘和接口文档"
- 准备创建复盘文档
- 准备创建 API 文档
- 准备更新索引和会话记录