---
name: 代码注释与日志契约规则
scope:
  - '*'
products:
  - '*'
id: ka-hard-rule-代码注释与日志契约规则
asset_kind: hard_rule
lifecycle_status: active
authority: canonical
owner_mechanism_id: mc-code-maintainability-observability-contract
routes:
  - code_change
  - artifact_generation
  - operation
  - multi_stage_plan
primary_triggers:
  - 业务编码
  - 接口实现
  - 状态流转
  - 支付
  - 权限
  - 迁移脚本
  - 数据修复
secondary_triggers:
  - Service
  - Controller
  - UseCase
  - Handler
  - Router
  - Form
  - Store
  - 异常处理
negative_triggers:
  - 文案
  - 样式
  - getter
  - setter
  - fixture
priority: P0
specificity: 5
consumes:
  - mc-coding-readiness
hard_blocks:
  - code_observability_work_package_missing
  - sensitive_log_leak
  - catch_swallow
  - missing_log_critical
  - missing_comment_complex_unresolved
  - missing_class_doc
  - missing_method_doc
  - missing_important_line_comment
  - non_chinese_log
  - non_chinese_comment
fallback: manual_required
required_evidence:
  - code_observability_work_package
  - review_findings
  - verification_result
version: 1.0.0
last_reviewed: '2026-05-26'
---

## 注释契约

### 中文 Javadoc 必须具备
- Java/Kotlin 后端类、接口、枚举、记录必须有中文文档注释，说明类型职责、业务边界和使用场景。
- 后端每个业务方法必须有中文文档注释，说明方法作用；有入参时说明参数语义；有返回值时说明返回对象或结果含义。
- Controller、Service、UseCase、DomainService、Repository、Mapper、DTO、VO、Request、Response、Entity 等均适用。
- 关键业务行必须有中文行注释，尤其是事务双写、状态流转、级联删除、账号联动、外部调用、审计写入、补偿和回滚边界。
- 允许保留英文代码标识符，但业务说明、风险说明、参数说明、返回说明必须中文表达。

### 必须有注释
- 业务规则不直观时
- 领域不变量（如"一个用户同一时间只能有一个有效业务办理"）
- 金额、账单、折扣、支付、退款、核验逻辑
- 状态流转逻辑（如 pending → paid → refunded）
- 幂等、分布式锁、事务、并发控制
- 权限、安全、审计判断
- 外部系统兼容、历史包袱、第三方接口限制
- 复杂 SQL、复杂查询条件、非显而易见算法
- 前端复杂交互规则：权限控制、状态流转、表单联动、乐观更新/回滚、支付与敏感操作

### 必须禁止
- 每行废话注释
- 复述代码字面含义的注释
- 注释与代码行为不一致
- 注释承诺了代码没有做到的安全性、幂等性或事务性
- 用户项目业务注释全英文
- 只写 `{@inheritDoc}` 但没有说明本实现的业务边界、入参和出参

## 日志契约

### 必须有日志
- 用户登录、登出、认证失败
- 权限拒绝、越权访问
- 创建、修改、删除关键业务对象
- 状态变更、金额变更、支付、退款、折扣、核验
- 合同、业务办理、账单、证照、人员角色变更
- 外部 API 调用失败、超时、重试
- 异步任务开始、成功、失败、重试、跳过
- 数据修复、批处理、迁移脚本
- 捕获异常后继续执行
- 降级、兜底、补偿逻辑
- 前端关键交互：表单提交、状态变更、权限动作、支付/敏感操作、上传导入、API 调用失败

### 日志必须具备
- 中文事件名或中文动作说明
- 事件名或动作名
- 业务对象 ID
- 操作人或系统来源
- traceId / correlationId（如果项目已有）
- 失败原因
- 关键状态变化前后值
- 合理日志级别

### 必须禁止
- 裸 console.log（生产代码）
- 生产代码遗留调试日志
- catch 后无日志直接吞异常
- 只打印 "error"、"failed" 这类不可定位日志
- 用户项目业务日志全英文
- 打印 password、token、secret、cookie、身份证全量、手机号全量、银行卡全量、健康隐私
- 高频循环里刷屏日志
- 日志拼接大对象导致性能或隐私问题

## 项目 logger 识别
- Java/Spring: Slf4j + LoggerFactory
- Node/Express/NestJS: pino, winston, NestJS Logger, 项目封装 logger
- Python/FastAPI、Go handler、.NET、Ruby 等后端: 使用项目现有 logger 或先建立 logger 包装
- NestJS: Logger
- React/Vue/Svelte 等前端: 项目封装 logger、埋点或错误上报，生产环境禁止裸 console
- 如果项目没有 logger，要求先建立项目 logger 包装

## 跨技术栈适用范围
- 后端不限定 Spring：Controller、Service、UseCase、Handler、Router、Resolver、ViewSet、Repository、Mapper 等写操作都适用。
- 前端不限定框架：React、Vue、Svelte、移动端页面和状态 store 的业务提交、状态变更、权限动作和 API 失败都适用。
- Entity、Request、Response、VO、DTO、Schema、Serializer、Model 等用户项目契约类的业务字段需要中文含义说明或 Schema 注解。
- Java Entity 使用 Getter/Setter 分层访问策略；DTO、VO、Request、Response 使用 Data 风格承载边界数据，不得混用导致领域模型语义被抹平。

## 严重度
- P0 阻断: 敏感信息泄漏、catch 吞异常、支付/金额/权限变更无日志
- P1 阻断: 状态流转无日志、复杂规则无注释、后端类/方法中文 Javadoc 缺失、关键行中文注释缺失、中文日志缺失、外部调用无日志、裸 console.log
- P2 警告: 日志级别不合理、上下文字段不足
- P3 建议: 普通可读性优化

## 低风险跳过
- 纯样式、文案、简单 getter/setter、简单类型定义、测试 fixture
- 低风险只读查询且已有统一 access log
- 简单配置修改、一次性本地实验代码
