---
name: code-maintainability-observability-review
scope:
  - '*'
products:
  - '*'
id: ka-review-rule-代码可维护性与可观测性审查
type: review_rule
asset_kind: review_rule
lifecycle_status: active
authority: canonical
owner_mechanism_id: mc-code-maintainability-observability-contract
routes:
  - code_change
  - review
primary_triggers:
  - 代码审查
  - review
  - 验证
secondary_triggers:
  - 业务代码
  - 接口实现
negative_triggers:
  - 纯文档
  - 纯样式
priority: P1
specificity: 4
consumes:
version: 1.1.0
last_reviewed: '2026-06-01'
stages: ["代码审查"]
---

## 审查维度

### 1. 日志完整性
检查 changed files 中:
- 支付/金额/退款操作是否有含对象 ID 和前后值的日志
- 权限拒绝是否有含操作人和拒绝原因的日志
- 外部调用是否有含目标、响应码和重试信息的失败日志
- 状态变更是否有含前后状态和触发原因的流转日志
- 数据修复/迁移是否有含修复前值和影响行数的审计日志

### 2. 敏感信息泄漏
检查所有日志输出是否:
- 不包含 token、password、cookie 全量
- 不包含身份证、手机号、银行卡全量
- 不包含健康隐私信息

### 3. 注释质量
检查 changed files 中:
- 复杂业务规则是否有说明"为什么"的注释
- 金额计算是否有设计意图注释
- 状态机是否有状态流转注释
- 不检查纯复述代码的废话注释

### 4. Logger 使用
检查是否使用了项目已有 logger:
- Java/Spring 项目是否使用 Slf4j
- Node 项目是否使用 pino/winston
- NestJS 项目是否使用 NestJS Logger
- 前端项目是否避免裸 console

### 5. 异常处理
检查 catch 块是否:
- 不吞异常（至少记录日志）
- 不只输出 "error" / "failed" 这类不可定位信息

## 审查输出格式
每条 finding 包含:
- 类别 (category)
- 严重度 (P0/P1/P2/P3)
- 文件路径
- 证据位置
- 中文修复建议

## 低风险跳过规则
- 纯样式、文案修改不触发审查
- 简单 getter/setter 不触发审查
- 测试 fixture 不触发审查
- 低风险只读查询（且已有统一 access log）不触发审查
