kris/datai

DESKTOP-368IV5S\Kris 55b053346d docs(salesforce): 新增技能文档和优化代码

- 新增 11 个技能文档，指导 AI 完成特定开发任务
- 新增参考代码文件，用于代码分析和重构
- 优化 DataiIntegrationBatchServiceImpl.java，提取常量到 SalesforceConstants.java
- 移动 SessionManager.java 到 auth 模块
- 更新 docs/index.md，添加技能文档索引

主要变更：
- 新增技能文档：Bootstrap、SSOT Hub、信息架构、需求定义、架构决策、提示词资产化、上下文锚定、执行记录、变更归档、闭环复盘、测试提交
- 提取常量：批次处理、状态值、字段名、日志消息等
- 优化代码：改进代码结构和可读性

Related:
- Prompts: docs/prompts/03-创建工作流提示词.md
- Prompts: docs/prompts/07生成技能书提示词.md

2026-01-15 14:09:15 +08:00

13 KiB

Raw Blame History

name	description
0011-verification-commit	测试与版本提交，运行测试并执行 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 应当"觉醒"本技能：

代码变更完成: 完成代码编写和变更记录后，需要测试和提交
功能开发完成: 功能开发完成，需要测试和提交
Bug 修复完成: Bug 修复完成，需要测试和提交
代码重构完成: 代码重构完成，需要测试和提交
工作流阶段 8: 用户进入工作流的"测试与版本提交"阶段

定位范围 (Scope)

适用模块: 所有 Datai 项目模块
影响操作: 测试运行、Git 提交
相关技能: skill-retrospective, skill-define-requirements

核心指令集 (Instructions)

架构约束 (Architecture Constraints)

测试要求:
- 确保代码通过所有单元测试
- 满足阶段 1 定义的验收标准（AC）
- 确保代码质量符合项目规范
提交原子性:
- 确保本次提交仅包含当前任务的变更
- 不包含无关的代码变更
- 不包含调试代码或临时文件
文档同源:
- 提交必须包含代码变更
- 提交必须包含上述步骤产生的所有文档变更（Requirements, ADR, Prompts, Session Logs, Retros）
Commit Message 规范:

<type>(<scope>): <subject>

- Implements: [需求链接/ID]
- Decision: [ADR 链接/ID]
- Context: Based on session [Session Log ID]

业务逻辑 SOP (Business Logic SOP)

步骤 1: 运行测试

## 运行测试

### 单元测试
```bash
# 运行所有单元测试
mvn test

# 运行特定测试类
mvn test -Dtest=ClassName

# 运行特定测试方法
mvn test -Dtest=ClassName#methodName

集成测试

# 运行集成测试
mvn verify

# 运行特定集成测试
mvn verify -Dit.test=ClassName

测试覆盖率

# 生成测试覆盖率报告
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

代码格式检查

# 检查代码格式
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/

暂存文档变更

# 暂存需求文档
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

验证暂存

# 查看暂存区变更
git diff --cached

# 确认暂存内容正确


#### 步骤 5: 编写 Commit Message
```markdown
## 编写 Commit Message

### Commit Message 格式

():

```

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

验证提交

# 查看提交历史
git log --oneline -n 5

# 查看提交详情
git show HEAD

# 确认提交内容正确

推送到远程仓库

# 推送到当前分支
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

集成测试

# 测试命令
mvn verify

# 测试结果
Tests run: 50, Failures: 0, Errors: 0, Skipped: 0

测试覆盖率

# 覆盖率命令
mvn jacoco:report

# 覆盖率结果
- 指令覆盖率: 85%
- 分支覆盖率: 80%
- 行覆盖率: 85%
- 方法覆盖率: 90%
- 类覆盖率: 95%

验收标准验证

验收标准	测试方法	结果	状态
[AC1]	[测试方法]	[测试结果]	[通过/失败]
[AC2]	[测试方法]	[测试结果]	[通过/失败]
[AC3]	[测试方法]	[测试结果]	[通过/失败]

代码质量检查

静态代码分析

# Checkstyle
mvn checkstyle:check
结果: 通过

# SpotBugs
mvn spotbugs:check
结果: 通过

# PMD
mvn pmd:check
结果: 通过

代码格式检查

# Spotless
mvn spotless:check
结果: 通过

代码规范检查

命名规范
注释规范
异常处理规范
日志记录规范
安全规范

变更文件清单

代码变更

文件	变更类型	说明
文件1	[新增/修改/删除]	[说明]
文件2	[新增/修改/删除]	[说明]

文档变更

文件	变更类型	说明
REQ-XXX	[新增/修改/删除]	[说明]
ADR-XXX	[新增/修改/删除]	[说明]
PROMPT-XXX	[新增/修改/删除]	[说明]
Session Log	[新增/修改/删除]	[说明]
Retro	[新增/修改/删除]	[说明]
CHANGELOG	[修改]	[说明]
docs/index.md	[修改]	[说明]

Git 提交

Commit Message

[Commit Message]

Commit Hash

[Commit Hash: abc123def456]

提交验证

仅包含当前任务的变更
包含所有文档变更
Commit Message 符合规范
已推送到远程仓库


### 工具调用 (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 示例

# 运行测试
mvn test
# 结果: Tests run: 100, Failures: 2, Errors: 0, Skipped: 0

# 忽略测试失败，直接提交
git add .
git commit -m "新增批量导入功能"
git push

问题: 测试失败但仍然提交，Commit Message 不符合规范，缺少文档链接。

13 KiB Raw Blame History Unescape Escape

技能：测试与版本提交 (Verification & Git Commit)

元数据 (Metadata)

触发与定位 (Triggers & Scope)

触发条件 (Triggers)

定位范围 (Scope)

核心指令集 (Instructions)

架构约束 (Architecture Constraints)

业务逻辑 SOP (Business Logic SOP)

步骤 1: 运行测试

集成测试

测试覆盖率

验收标准验证

代码格式检查

代码规范检查

代码审查清单

变更文件清单

代码变更

文档变更

暂存文档变更

验证暂存

Type 说明

Subject 说明

Body 说明

Footer 说明

Commit Message 示例

验证提交

推送到远程仓库

集成测试

测试覆盖率

验收标准验证

代码质量检查

静态代码分析

代码格式检查

代码规范检查

变更文件清单

代码变更

文档变更

Git 提交

Commit Message

Commit Hash

提交验证

相关文档 (Related Documents)

Incorrect 示例

相关文档 (Related Documents)

13 KiB

Raw Blame History