584 lines
13 KiB
Markdown
584 lines
13 KiB
Markdown
---
|
||
name: 0011-verification-commit
|
||
description: 测试与版本提交，运行测试并执行 Git 提交
|
||
---
|
||
|
||
# 技能：测试与版本提交 (Verification & Git Commit)
|
||
|
||
## 元数据 (Metadata)
|
||
|
||
- **name**: verification-commit
|
||
- **description**: 测试与版本提交，运行测试并执行 Git 提交
|
||
- **version**: 1.0.0
|
||
- **author**: SSOT Architect
|
||
- **lastUpdated**: 2026-01-15
|
||
|
||
## 触发与定位 (Triggers & Scope)
|
||
|
||
### 触发条件 (Triggers)
|
||
当以下情况发生时，AI 应当"觉醒"本技能：
|
||
|
||
1. **代码变更完成**: 完成代码编写和变更记录后，需要测试和提交
|
||
2. **功能开发完成**: 功能开发完成，需要测试和提交
|
||
3. **Bug 修复完成**: Bug 修复完成，需要测试和提交
|
||
4. **代码重构完成**: 代码重构完成，需要测试和提交
|
||
5. **工作流阶段 8**: 用户进入工作流的"测试与版本提交"阶段
|
||
|
||
### 定位范围 (Scope)
|
||
- **适用模块**: 所有 Datai 项目模块
|
||
- **影响操作**: 测试运行、Git 提交
|
||
- **相关技能**: skill-retrospective, skill-define-requirements
|
||
|
||
## 核心指令集 (Instructions)
|
||
|
||
### 架构约束 (Architecture Constraints)
|
||
|
||
1. **测试要求**:
|
||
- 确保代码通过所有单元测试
|
||
- 满足阶段 1 定义的验收标准（AC）
|
||
- 确保代码质量符合项目规范
|
||
|
||
2. **提交原子性**:
|
||
- 确保本次提交仅包含当前任务的变更
|
||
- 不包含无关的代码变更
|
||
- 不包含调试代码或临时文件
|
||
|
||
3. **文档同源**:
|
||
- 提交必须包含代码变更
|
||
- 提交必须包含上述步骤产生的所有文档变更（Requirements, ADR, Prompts, Session Logs, Retros）
|
||
|
||
4. **Commit Message 规范**:
|
||
```
|
||
<type>(<scope>): <subject>
|
||
|
||
- Implements: [需求链接/ID]
|
||
- Decision: [ADR 链接/ID]
|
||
- Context: Based on session [Session Log ID]
|
||
```
|
||
|
||
### 业务逻辑 SOP (Business Logic SOP)
|
||
|
||
#### 步骤 1: 运行测试
|
||
```markdown
|
||
## 运行测试
|
||
|
||
### 单元测试
|
||
```bash
|
||
# 运行所有单元测试
|
||
mvn test
|
||
|
||
# 运行特定测试类
|
||
mvn test -Dtest=ClassName
|
||
|
||
# 运行特定测试方法
|
||
mvn test -Dtest=ClassName#methodName
|
||
```
|
||
|
||
### 集成测试
|
||
```bash
|
||
# 运行集成测试
|
||
mvn verify
|
||
|
||
# 运行特定集成测试
|
||
mvn verify -Dit.test=ClassName
|
||
```
|
||
|
||
### 测试覆盖率
|
||
```bash
|
||
# 生成测试覆盖率报告
|
||
mvn jacoco:report
|
||
|
||
# 查看覆盖率报告
|
||
open target/site/jacoco/index.html
|
||
```
|
||
|
||
### 验收标准验证
|
||
| 验收标准 | 测试方法 | 结果 | 状态 |
|
||
|----------|----------|------|------|
|
||
| [AC1] | [测试方法] | [测试结果] | [通过/失败] |
|
||
| [AC2] | [测试方法] | [测试结果] | [通过/失败] |
|
||
| [AC3] | [测试方法] | [测试结果] | [通过/失败] |
|
||
```
|
||
|
||
#### 步骤 2: 代码质量检查
|
||
```markdown
|
||
## 代码质量检查
|
||
|
||
### 静态代码分析
|
||
```bash
|
||
# 运行 Checkstyle
|
||
mvn checkstyle:check
|
||
|
||
# 运行 SpotBugs
|
||
mvn spotbugs:check
|
||
|
||
# 运行 PMD
|
||
mvn pmd:check
|
||
```
|
||
|
||
### 代码格式检查
|
||
```bash
|
||
# 检查代码格式
|
||
mvn spotless:check
|
||
|
||
# 自动格式化代码
|
||
mvn spotless:apply
|
||
```
|
||
|
||
### 代码规范检查
|
||
- [ ] 命名规范
|
||
- [ ] 注释规范
|
||
- [ ] 异常处理规范
|
||
- [ ] 日志记录规范
|
||
- [ ] 安全规范
|
||
|
||
### 代码审查清单
|
||
- [ ] 代码逻辑正确
|
||
- [ ] 没有硬编码
|
||
- [ ] 没有重复代码
|
||
- [ ] 没有未使用的代码
|
||
- [ ] 没有安全隐患
|
||
- [ ] 性能合理
|
||
- [ ] 可维护性好
|
||
```
|
||
|
||
#### 步骤 3: 检查变更文件
|
||
```markdown
|
||
## 检查变更文件
|
||
|
||
### 查看变更
|
||
```bash
|
||
# 查看工作区变更
|
||
git status
|
||
|
||
# 查看暂存区变更
|
||
git diff --cached
|
||
|
||
# 查看未暂存变更
|
||
git diff
|
||
```
|
||
|
||
### 变更文件清单
|
||
| 文件 | 变更类型 | 说明 |
|
||
|------|----------|------|
|
||
| [文件1] | [新增/修改/删除] | [说明] |
|
||
| [文件2] | [新增/修改/删除] | [说明] |
|
||
|
||
### 代码变更
|
||
- [ ] 仅包含当前任务的代码变更
|
||
- [ ] 不包含无关的代码变更
|
||
- [ ] 不包含调试代码
|
||
- [ ] 不包含临时文件
|
||
|
||
### 文档变更
|
||
- [ ] 需求文档已更新
|
||
- [ ] ADR 文档已更新
|
||
- [ ] Prompt 文档已更新
|
||
- [ ] Session Log 已更新
|
||
- [ ] Retro 文档已更新
|
||
- [ ] CHANGELOG 已更新
|
||
- [ ] docs/index.md 已更新
|
||
```
|
||
|
||
#### 步骤 4: 暂存变更文件
|
||
```markdown
|
||
## 暂存变更文件
|
||
|
||
### 暂存代码变更
|
||
```bash
|
||
# 暂存所有变更
|
||
git add .
|
||
|
||
# 暂存特定文件
|
||
git add path/to/file1.java
|
||
git add path/to/file2.java
|
||
|
||
# 暂存特定目录
|
||
git add path/to/directory/
|
||
```
|
||
|
||
### 暂存文档变更
|
||
```bash
|
||
# 暂存需求文档
|
||
git add docs/requirements/REQ-XXX.md
|
||
|
||
# 暂存 ADR 文档
|
||
git add docs/decisions/adr/ADR-XXX.md
|
||
|
||
# 暂存 Prompt 文档
|
||
git add docs/prompts/PROMPT-XXX.md
|
||
|
||
# 暂存 Session Log
|
||
git add docs/sessions/YYYYMMDD-TaskName.md
|
||
|
||
# 暂存 Retro 文档
|
||
git add docs/retros/YYYYMMDD-Review.md
|
||
|
||
# 暂存 CHANGELOG
|
||
git add CHANGELOG.md
|
||
|
||
# 暂存 docs/index.md
|
||
git add docs/index.md
|
||
```
|
||
|
||
### 验证暂存
|
||
```bash
|
||
# 查看暂存区变更
|
||
git diff --cached
|
||
|
||
# 确认暂存内容正确
|
||
```
|
||
```
|
||
|
||
#### 步骤 5: 编写 Commit Message
|
||
```markdown
|
||
## 编写 Commit Message
|
||
|
||
### Commit Message 格式
|
||
```
|
||
<type>(<scope>): <subject>
|
||
|
||
<body>
|
||
|
||
<footer>
|
||
```
|
||
|
||
### Type 说明
|
||
- **feat**: 新功能
|
||
- **fix**: 修复 Bug
|
||
- **docs**: 文档更新
|
||
- **style**: 代码格式（不影响代码运行的变动）
|
||
- **refactor**: 重构（既不是新增功能，也不是修改 Bug 的代码变动）
|
||
- **perf**: 性能优化
|
||
- **test**: 测试相关
|
||
- **chore**: 构建/工具相关
|
||
- **revert**: 回滚
|
||
|
||
### Subject 说明
|
||
- 使用祈使句，现在时态
|
||
- 首字母小写
|
||
- 结尾不加句号
|
||
- 限制在 50 个字符以内
|
||
|
||
### Body 说明
|
||
- 使用祈使句，现在时态
|
||
- 应该包括修改的动机和与之前行为的对比
|
||
- 每行限制在 72 个字符以内
|
||
|
||
### Footer 说明
|
||
- 关联 Issue
|
||
- 关联需求
|
||
- 关联 ADR
|
||
- 关联 Session Log
|
||
|
||
### Commit Message 示例
|
||
```
|
||
feat(integration): 新增用户批量导入功能
|
||
|
||
- Implements: REQ-001
|
||
- Decision: ADR-001
|
||
- Context: Based on session 20260115-TaskName
|
||
|
||
新增用户批量导入功能，支持 CSV 格式导入，
|
||
单次最多导入 1000 条记录，提供详细的错误信息。
|
||
|
||
主要变更：
|
||
- 新增 UserImportService 接口和实现类
|
||
- 新增 UserImportController 控制器
|
||
- 新增 CSV 文件解析工具类
|
||
- 新增导入错误日志记录
|
||
- 更新相关文档（REQ-001, ADR-001, Session Log）
|
||
|
||
Closes #123
|
||
```
|
||
```
|
||
|
||
#### 步骤 6: 执行 Git 提交
|
||
```markdown
|
||
## 执行 Git 提交
|
||
|
||
### 提交变更
|
||
```bash
|
||
# 使用 -m 参数提交
|
||
git commit -m "feat(integration): 新增用户批量导入功能
|
||
|
||
- Implements: REQ-001
|
||
- Decision: ADR-001
|
||
- Context: Based on session 20260115-TaskName
|
||
|
||
新增用户批量导入功能，支持 CSV 格式导入，
|
||
单次最多导入 1000 条记录，提供详细的错误信息。"
|
||
|
||
# 使用编辑器提交
|
||
git commit
|
||
```
|
||
|
||
### 验证提交
|
||
```bash
|
||
# 查看提交历史
|
||
git log --oneline -n 5
|
||
|
||
# 查看提交详情
|
||
git show HEAD
|
||
|
||
# 确认提交内容正确
|
||
```
|
||
|
||
### 推送到远程仓库
|
||
```bash
|
||
# 推送到当前分支
|
||
git push
|
||
|
||
# 推送到指定分支
|
||
git push origin feature/branch-name
|
||
|
||
# 推送到所有分支
|
||
git push --all
|
||
```
|
||
```
|
||
|
||
#### 步骤 7: 创建测试与提交记录
|
||
```markdown
|
||
---
|
||
name: VERIFICATION-20260115
|
||
description: 测试与提交记录
|
||
---
|
||
|
||
# 测试与提交记录: [任务名称]
|
||
|
||
## 元数据 (Metadata)
|
||
|
||
- **Date**: 2026-01-15
|
||
- **Task**: [任务名称]
|
||
- **Related Requirements**: [REQ-XXX](../requirements/REQ-XXX.md)
|
||
- **Related Session**: [20260115-TaskName](../sessions/20260115-TaskName.md)
|
||
- **Commit Hash**: [Commit Hash]
|
||
|
||
## 测试结果
|
||
|
||
### 单元测试
|
||
```bash
|
||
# 测试命令
|
||
mvn test
|
||
|
||
# 测试结果
|
||
Tests run: 100, Failures: 0, Errors: 0, Skipped: 0
|
||
```
|
||
|
||
### 集成测试
|
||
```bash
|
||
# 测试命令
|
||
mvn verify
|
||
|
||
# 测试结果
|
||
Tests run: 50, Failures: 0, Errors: 0, Skipped: 0
|
||
```
|
||
|
||
### 测试覆盖率
|
||
```bash
|
||
# 覆盖率命令
|
||
mvn jacoco:report
|
||
|
||
# 覆盖率结果
|
||
- 指令覆盖率: 85%
|
||
- 分支覆盖率: 80%
|
||
- 行覆盖率: 85%
|
||
- 方法覆盖率: 90%
|
||
- 类覆盖率: 95%
|
||
```
|
||
|
||
### 验收标准验证
|
||
| 验收标准 | 测试方法 | 结果 | 状态 |
|
||
|----------|----------|------|------|
|
||
| [AC1] | [测试方法] | [测试结果] | [通过/失败] |
|
||
| [AC2] | [测试方法] | [测试结果] | [通过/失败] |
|
||
| [AC3] | [测试方法] | [测试结果] | [通过/失败] |
|
||
|
||
## 代码质量检查
|
||
|
||
### 静态代码分析
|
||
```bash
|
||
# Checkstyle
|
||
mvn checkstyle:check
|
||
结果: 通过
|
||
|
||
# SpotBugs
|
||
mvn spotbugs:check
|
||
结果: 通过
|
||
|
||
# PMD
|
||
mvn pmd:check
|
||
结果: 通过
|
||
```
|
||
|
||
### 代码格式检查
|
||
```bash
|
||
# Spotless
|
||
mvn spotless:check
|
||
结果: 通过
|
||
```
|
||
|
||
### 代码规范检查
|
||
- [x] 命名规范
|
||
- [x] 注释规范
|
||
- [x] 异常处理规范
|
||
- [x] 日志记录规范
|
||
- [x] 安全规范
|
||
|
||
## 变更文件清单
|
||
|
||
### 代码变更
|
||
| 文件 | 变更类型 | 说明 |
|
||
|------|----------|------|
|
||
| [文件1](../../path/to/file1.java) | [新增/修改/删除] | [说明] |
|
||
| [文件2](../../path/to/file2.java) | [新增/修改/删除] | [说明] |
|
||
|
||
### 文档变更
|
||
| 文件 | 变更类型 | 说明 |
|
||
|------|----------|------|
|
||
| [REQ-XXX](../requirements/REQ-XXX.md) | [新增/修改/删除] | [说明] |
|
||
| [ADR-XXX](../decisions/adr/ADR-XXX.md) | [新增/修改/删除] | [说明] |
|
||
| [PROMPT-XXX](../prompts/PROMPT-XXX.md) | [新增/修改/删除] | [说明] |
|
||
| [Session Log](../sessions/YYYYMMDD-TaskName.md) | [新增/修改/删除] | [说明] |
|
||
| [Retro](../retros/YYYYMMDD-Review.md) | [新增/修改/删除] | [说明] |
|
||
| [CHANGELOG](../../CHANGELOG.md) | [修改] | [说明] |
|
||
| [docs/index.md](../index.md) | [修改] | [说明] |
|
||
|
||
## Git 提交
|
||
|
||
### Commit Message
|
||
```
|
||
[Commit Message]
|
||
```
|
||
|
||
### Commit Hash
|
||
[Commit Hash: abc123def456]
|
||
|
||
### 提交验证
|
||
- [x] 仅包含当前任务的变更
|
||
- [x] 包含所有文档变更
|
||
- [x] Commit Message 符合规范
|
||
- [x] 已推送到远程仓库
|
||
|
||
## 相关文档 (Related Documents)
|
||
|
||
- [需求文档](../requirements/REQ-XXX.md)
|
||
- [ADR 文档](../decisions/adr/ADR-XXX.md)
|
||
- [会话记录](../sessions/YYYYMMDD-TaskName.md)
|
||
- [复盘文档](../retros/YYYYMMDD-Review.md)
|
||
```
|
||
|
||
### 工具调用 (Tool Usage)
|
||
|
||
1. **测试运行工具**:
|
||
- 使用 `RunCommand` 运行单元测试
|
||
- 使用 `RunCommand` 运行集成测试
|
||
- 使用 `RunCommand` 生成测试覆盖率报告
|
||
|
||
2. **代码质量检查工具**:
|
||
- 使用 `RunCommand` 运行 Checkstyle
|
||
- 使用 `RunCommand` 运行 SpotBugs
|
||
- 使用 `RunCommand` 运行 PMD
|
||
- 使用 `RunCommand` 运行 Spotless
|
||
|
||
3. **Git 操作工具**:
|
||
- 使用 `RunCommand` 执行 git status
|
||
- 使用 `RunCommand` 执行 git add
|
||
- 使用 `RunCommand` 执行 git commit
|
||
- 使用 `RunCommand` 执行 git push
|
||
|
||
4. **诊断工具**:
|
||
- 使用 `GetDiagnostics` 获取代码诊断信息
|
||
|
||
## 错误陷阱与验证 (Anti-Patterns & Checklist)
|
||
|
||
### 常见错误 (Anti-Patterns)
|
||
|
||
1. **错误**: 测试失败但仍然提交
|
||
- **后果**: 代码质量低，可能引入 Bug
|
||
- **修正**: 必须确保所有测试通过后才能提交
|
||
|
||
2. **错误**: 提交包含无关的代码变更
|
||
- **后果**: 提交不原子，难以追踪
|
||
- **修正**: 确保提交仅包含当前任务的变更
|
||
|
||
3. **错误**: 提交不包含文档变更
|
||
- **后果**: 违反文档同源原则
|
||
- **修正**: 必须包含所有文档变更（Requirements, ADR, Prompts, Session Logs, Retros）
|
||
|
||
4. **错误**: Commit Message 不符合规范
|
||
- **后果**: 难以理解提交内容
|
||
- **修正**: 必须遵循 Commit Message 规范
|
||
|
||
5. **错误**: 提交包含调试代码或临时文件
|
||
- **后果**: 代码质量低，可能影响运行
|
||
- **修正**: 必须清理调试代码和临时文件
|
||
|
||
### 验收清单 (Acceptance Checklist)
|
||
|
||
- [ ] 所有单元测试通过
|
||
- [ ] 所有集成测试通过
|
||
- [ ] 测试覆盖率符合要求
|
||
- [ ] 所有验收标准验证通过
|
||
- [ ] 静态代码分析通过
|
||
- [ ] 代码格式检查通过
|
||
- [ ] 代码规范检查通过
|
||
- [ ] 变更文件清单已确认
|
||
- [ ] 仅包含当前任务的变更
|
||
- [ ] 包含所有文档变更
|
||
- [ ] Commit Message 符合规范
|
||
- [ ] 已暂存所有变更文件
|
||
- [ ] 已执行 Git 提交
|
||
- [ ] 已推送到远程仓库
|
||
- [ ] 测试与提交记录已创建
|
||
|
||
### Correct vs Incorrect 对比
|
||
|
||
#### Correct 示例
|
||
```bash
|
||
# 运行测试
|
||
mvn test
|
||
# 结果: Tests run: 100, Failures: 0, Errors: 0, Skipped: 0
|
||
|
||
# 检查变更
|
||
git status
|
||
# 结果: 仅包含当前任务的变更
|
||
|
||
# 暂存变更
|
||
git add .
|
||
|
||
# 提交
|
||
git commit -m "feat(integration): 新增用户批量导入功能
|
||
|
||
- Implements: REQ-001
|
||
- Decision: ADR-001
|
||
- Context: Based on session 20260115-TaskName
|
||
|
||
新增用户批量导入功能，支持 CSV 格式导入，
|
||
单次最多导入 1000 条记录，提供详细的错误信息。"
|
||
|
||
# 推送
|
||
git push
|
||
```
|
||
|
||
#### Incorrect 示例
|
||
```bash
|
||
# 运行测试
|
||
mvn test
|
||
# 结果: Tests run: 100, Failures: 2, Errors: 0, Skipped: 0
|
||
|
||
# 忽略测试失败，直接提交
|
||
git add .
|
||
git commit -m "新增批量导入功能"
|
||
git push
|
||
```
|
||
|
||
**问题**: 测试失败但仍然提交，Commit Message 不符合规范，缺少文档链接。
|
||
|
||
## 相关文档 (Related Documents)
|
||
|
||
- [工作流提示词](../prompts/03-创建工作流提示词.md#阶段-8-测试与版本提交-verification--git-commit)
|
||
- [闭环复盘技能](./0010-retrospective.md)
|
||
- [需求定义技能](./0004-define-requirements.md)
|
||
- [Commit Message 规范](../../CONTRIBUTING.md#commit-message-规范)
|