317 lines
9.2 KiB
Markdown
317 lines
9.2 KiB
Markdown
<!-- 由 BMAD™ Core 驱动 -->
|
||
|
||
# review-story
|
||
|
||
执行全面的测试架构审查并做出质量门禁决策。这种自适应、风险感知的审查会创建一个故事更新和一个详细的门禁文件。
|
||
|
||
## 输入
|
||
|
||
```yaml
|
||
required:
|
||
- story_id: '{epic}.{story}' # 例如, "1.3"
|
||
- story_path: '{devStoryLocation}/{epic}.{story}.*.md' # 来自core-config.yaml的路径
|
||
- story_title: '{title}' # 如果缺少，则从故事文件的H1派生
|
||
- story_slug: '{slug}' # 如果缺少，则从标题派生 (小写，连字符连接)
|
||
```
|
||
|
||
## 先决条件
|
||
|
||
- 故事状态必须是“待审查”
|
||
- 开发人员已完成所有任务并更新了文件列表
|
||
- 所有自动化测试均已通过
|
||
|
||
## 审查流程 - 自适应测试架构
|
||
|
||
### 1. 风险评估（决定审查深度）
|
||
|
||
**在以下情况下自动升级为深度审查：**
|
||
|
||
- 触及了认证/支付/安全文件
|
||
- 故事中没有添加任何测试
|
||
- 差异 > 500行
|
||
- 上一个门禁是FAIL/CONCERNS
|
||
- 故事有 > 5个验收标准
|
||
|
||
### 2. 综合分析
|
||
|
||
**A. 需求可追溯性**
|
||
|
||
- 将每个验收标准映射到其验证测试（用Given-When-Then记录映射，而非测试代码）
|
||
- 识别覆盖差距
|
||
- 验证所有需求都有相应的测试用例
|
||
|
||
**B. 代码质量审查**
|
||
|
||
- 架构和设计模式
|
||
- 重构机会（并执行它们）
|
||
- 代码重复或效率低下
|
||
- 性能优化
|
||
- 安全漏洞
|
||
- 遵守最佳实践
|
||
|
||
**C. 测试架构评估**
|
||
|
||
- 在适当级别上的测试覆盖率是否足够
|
||
- 测试级别的适当性（什么是单元测试、集成测试、端到端测试）
|
||
- 测试设计的质量和可维护性
|
||
- 测试数据管理策略
|
||
- 模拟/桩的使用是否适当
|
||
- 边缘情况和错误场景的覆盖
|
||
- 测试执行时间和可靠性
|
||
|
||
**D. 非功能性需求（NFR）**
|
||
|
||
- 安全性：认证、授权、数据保护
|
||
- 性能：响应时间、资源使用
|
||
- 可靠性：错误处理、恢复机制
|
||
- 可维护性：代码清晰度、文档
|
||
|
||
**E. 可测试性评估**
|
||
|
||
- 可控性：我们能控制输入吗？
|
||
- 可观察性：我们能观察输出吗？
|
||
- 可调试性：我们能轻松调试失败吗？
|
||
|
||
**F. 技术债务识别**
|
||
|
||
- 累积的捷径
|
||
- 缺失的测试
|
||
- 过时的依赖项
|
||
- 违反架构
|
||
|
||
### 3. 主动重构
|
||
|
||
- 在安全和适当的情况下重构代码
|
||
- 运行测试以确保更改不会破坏功能
|
||
- 在QA结果部分记录所有更改，并附上清晰的“为什么”和“如何”
|
||
- 不要修改QA结果部分之外的故事内容
|
||
- 不要更改故事状态或文件列表；仅建议下一个状态
|
||
|
||
### 4. 标准合规性检查
|
||
|
||
- 验证是否遵守`docs/coding-standards.md`
|
||
- 检查是否符合`docs/unified-project-structure.md`
|
||
- 根据`docs/testing-strategy.md`验证测试方法
|
||
- 确保遵守故事中提到的所有准则
|
||
|
||
### 5. 验收标准验证
|
||
|
||
- 验证每个AC是否已完全实现
|
||
- 检查是否有任何缺失的功能
|
||
- 验证边缘情况是否已处理
|
||
|
||
### 6. 文档和注释
|
||
|
||
- 验证代码在可能的情况下是否是自文档化的
|
||
- 如果缺少，为复杂逻辑添加注释
|
||
- 确保任何API更改都已记录
|
||
|
||
## 输出1：仅更新故事文件 - QA结果部分
|
||
|
||
**关键**：您仅被授权更新故事文件的“QA结果”部分。请勿修改任何其他部分。
|
||
|
||
**QA结果锚点规则：**
|
||
|
||
- 如果`## QA结果`不存在，则在文件末尾追加它
|
||
- 如果存在，则在现有条目下方追加一个新的带日期的条目
|
||
- 切勿编辑其他部分
|
||
|
||
审查和任何重构后，将您的结果附加到故事文件的QA结果部分：
|
||
|
||
```markdown
|
||
## QA结果
|
||
|
||
### 审查日期：[日期]
|
||
|
||
### 审查员：Quinn（测试架构师）
|
||
|
||
### 代码质量评估
|
||
|
||
[对实施质量的总体评估]
|
||
|
||
### 执行的重构
|
||
|
||
[列出您执行的任何重构并附上解释]
|
||
|
||
- **文件**：[文件名]
|
||
- **更改**：[更改了什么]
|
||
- **原因**：[更改原因]
|
||
- **方式**：[它如何改进代码]
|
||
|
||
### 合规性检查
|
||
|
||
- 编码标准：[✓/✗] [如有说明]
|
||
- 项目结构：[✓/✗] [如有说明]
|
||
- 测试策略：[✓/✗] [如有说明]
|
||
- 所有AC均已满足：[✓/✗] [如有说明]
|
||
|
||
### 改进清单
|
||
|
||
[勾选您自己处理的项目，未勾选的留给开发人员处理]
|
||
|
||
- [x] 为更好的错误处理重构了用户服务 (services/user.service.ts)
|
||
- [x] 添加了缺失的边缘情况测试 (services/user.service.test.ts)
|
||
- [ ] 考虑将验证逻辑提取到单独的验证器类中
|
||
- [ ] 为错误场景添加集成测试
|
||
- [ ] 为新的错误代码更新API文档
|
||
|
||
### 安全审查
|
||
|
||
[发现的任何安全问题以及是否已解决]
|
||
|
||
### 性能考虑
|
||
|
||
[发现的任何性能问题以及是否已解决]
|
||
|
||
### 审查期间修改的文件
|
||
|
||
[如果您修改了文件，请在此处列出 - 要求开发人员更新文件列表]
|
||
|
||
### 门禁状态
|
||
|
||
Gate: {STATUS} → qa.qaLocation/gates/{epic}.{story}-{slug}.yml
|
||
Risk profile: qa.qaLocation/assessments/{epic}.{story}-risk-{YYYYMMDD}.md
|
||
NFR assessment: qa.qaLocation/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md
|
||
|
||
# 注意：路径应引用core-config.yaml以获取自定义配置
|
||
|
||
### 推荐状态
|
||
|
||
[✓ 准备完成] / [✗ 需要更改 - 见上方未勾选项目]
|
||
（故事所有者决定最终状态）
|
||
```
|
||
|
||
## 输出2：创建质量门禁文件
|
||
|
||
**模板和目录：**
|
||
|
||
- 从`../templates/qa-gate-tmpl.yaml`渲染
|
||
- 在`qa.qaLocation/gates`中创建目录（参见`bmad-core/core-config.yaml`），如果不存在
|
||
- 保存到：`qa.qaLocation/gates/{epic}.{story}-{slug}.yml`
|
||
|
||
门禁文件结构：
|
||
|
||
```yaml
|
||
schema: 1
|
||
story: '{epic}.{story}'
|
||
story_title: '{story title}'
|
||
gate: PASS|CONCERNS|FAIL|WAIVED
|
||
status_reason: '1-2句话解释门禁决策'
|
||
reviewer: 'Quinn (测试架构师)'
|
||
updated: '{ISO-8601时间戳}'
|
||
|
||
top_issues: [] # 如果没有问题则为空
|
||
waiver: { active: false } # 仅在WAIVED时设置active: true
|
||
|
||
# 扩展字段（可选但推荐）：
|
||
quality_score: 0-100 # 100 - (20*FAILs) - (10*CONCERNS) 或使用technical-preferences.md权重
|
||
expires: '{ISO-8601时间戳}' # 通常为审查后2周
|
||
|
||
evidence:
|
||
tests_reviewed: { count }
|
||
risks_identified: { count }
|
||
trace:
|
||
ac_covered: [1, 2, 3] # 有测试覆盖的AC编号
|
||
ac_gaps: [4] # 缺少覆盖的AC编号
|
||
|
||
nfr_validation:
|
||
security:
|
||
status: PASS|CONCERNS|FAIL
|
||
notes: '具体发现'
|
||
performance:
|
||
status: PASS|CONCERNS|FAIL
|
||
notes: '具体发现'
|
||
reliability:
|
||
status: PASS|CONCERNS|FAIL
|
||
notes: '具体发现'
|
||
maintainability:
|
||
status: PASS|CONCERNS|FAIL
|
||
notes: '具体发现'
|
||
|
||
recommendations:
|
||
immediate: # 生产前必须修复
|
||
- action: '添加速率限制'
|
||
refs: ['api/auth/login.ts']
|
||
future: # 以后可以解决
|
||
- action: '考虑缓存'
|
||
refs: ['services/data.ts']
|
||
```
|
||
|
||
### 门禁决策标准
|
||
|
||
**确定性规则（按顺序应用）：**
|
||
|
||
如果存在risk_summary，则首先应用其阈值（≥9 → FAIL，≥6 → CONCERNS），然后是NFR状态，然后是top_issues严重性。
|
||
|
||
1. **风险阈值（如果存在risk_summary）：**
|
||
- 如果任何风险评分≥9 → Gate = FAIL（除非豁免）
|
||
- 否则如果任何评分≥6 → Gate = CONCERNS
|
||
|
||
2. **测试覆盖差距（如果trace可用）：**
|
||
- 如果缺少任何来自test-design的P0测试 → Gate = CONCERNS
|
||
- 如果缺少安全/数据丢失P0测试 → Gate = FAIL
|
||
|
||
3. **问题严重性：**
|
||
- 如果任何`top_issues.severity == high` → Gate = FAIL（除非豁免）
|
||
- 否则如果任何`severity == medium` → Gate = CONCERNS
|
||
|
||
4. **NFR状态：**
|
||
- 如果任何NFR状态为FAIL → Gate = FAIL
|
||
- 否则如果任何NFR状态为CONCERNS → Gate = CONCERNS
|
||
- 否则 → Gate = PASS
|
||
|
||
- WAIVED仅在waiver.active: true并有理由/批准者时
|
||
|
||
详细标准：
|
||
|
||
- **PASS**：所有关键要求均已满足，没有阻塞性问题
|
||
- **CONCERNS**：存在非关键问题，团队应审查
|
||
- **FAIL**：应解决的关键问题
|
||
- **WAIVED**：问题已确认但团队明确豁免
|
||
|
||
### 质量分数计算
|
||
|
||
```text
|
||
quality_score = 100 - (20 × FAIL数量) - (10 × CONCERNS数量)
|
||
范围在0到100之间
|
||
```
|
||
|
||
如果`technical-preferences.md`定义了自定义权重，则使用这些权重。
|
||
|
||
### 建议的所有者约定
|
||
|
||
对于`top_issues`中的每个问题，包括一个`suggested_owner`：
|
||
|
||
- `dev`：需要代码更改
|
||
- `sm`：需要澄清需求
|
||
- `po`：需要业务决策
|
||
|
||
## 关键原则
|
||
|
||
- 您是一名提供全面质量评估的测试架构师
|
||
- 在适当时，您有权直接改进代码
|
||
- 始终解释您的更改以供学习
|
||
- 在完美与实用之间取得平衡
|
||
- 专注于基于风险的优先级排序
|
||
- 提供具有明确所有权的可操作建议
|
||
|
||
## 阻塞条件
|
||
|
||
如果出现以下情况，请停止审查并请求澄清：
|
||
|
||
- 故事文件不完整或缺少关键部分
|
||
- 文件列表为空或明显不完整
|
||
- 在需要时不存在测试
|
||
- 代码更改与故事需求不符
|
||
- 需要讨论的关键架构问题
|
||
|
||
## 完成
|
||
|
||
审查后：
|
||
|
||
1. 更新故事文件中的QA结果部分
|
||
2. 在`qa.qaLocation/gates`的目录中创建门禁文件
|
||
3. 推荐状态：“准备完成”或“需要更改”（所有者决定）
|
||
4. 如果修改了文件，请在QA结果中列出并要求开发人员更新文件列表
|
||
5. 始终提供建设性反馈和可操作的建议
|