---
name: 代码注释与日志验收模板
when: '代码可维护性验收, 日志契约验收, 注释质量验收, 代码审查验收'
scope:
  - backend
  - frontend
  - script
products:
  - '*'
id: ka-artifact_template-代码注释与日志验收模板
asset_kind: artifact_template
lifecycle_status: active
authority: canonical
owner_mechanism_id: mc-code-maintainability-observability-contract
routes:
  - code_change
  - verification_only
primary_triggers:
  - 代码注释与日志验收模板
secondary_triggers:
  - 日志验收
negative_triggers: []
priority: P1
specificity: 5
consumes:
  - mc-code-maintainability-observability-contract
emits:
  - acceptance_report
required_evidence:
  - code_observability_work_package
  - review_findings
version: 1.0.0
last_reviewed: '2026-05-26'
---

# 代码注释与日志验收清单

## 日志契约验收

- [ ] 关键业务写操作（支付、金额、退款、核验）有结构化日志
- [ ] 日志包含事件名、业务对象 ID、操作人
- [ ] 状态流转日志包含前后状态值
- [ ] 外部调用失败日志包含目标、响应码和重试信息
- [ ] 数据修复/迁移脚本有审计日志（含修复前值、后值、影响行数）
- [ ] 权限拒绝有安全日志
- [ ] catch 块不吞异常（至少有日志记录）
- [ ] 无裸 console.log（使用项目 logger）
- [ ] 无不可定位日志（仅含 "error"/"failed"）

## 敏感信息验收

- [ ] 日志不包含 password、token、secret 明文
- [ ] 日志不包含身份证全量
- [ ] 日志不包含手机号全量
- [ ] 日志不包含银行卡号全量
- [ ] 日志不包含健康隐私信息
- [ ] 敏感字段已脱敏（仅显示部分或哈希）

## 注释质量验收

- [ ] 复杂业务规则有注释说明设计意图
- [ ] 金额计算有注释说明计算逻辑
- [ ] 状态机有状态流转注释
- [ ] 事务/幂等/并发控制有注释
- [ ] 无废话注释（不复述代码字面含义）
- [ ] 无注释与代码不一致

## Logger 使用验收

- [ ] 使用项目已有 logger（不是裸 console）
- [ ] 日志级别合理（INFO/WARN/ERROR）
- [ ] 无高频循环刷屏日志

## 低风险跳过确认

- [ ] 简单样式/文案修改未被过度要求注释和日志
- [ ] 简单 getter/setter 未被要求补日志
- [ ] 测试 fixture 未被要求满足生产代码日志标准
