---
description: 全仓注释规范——解释「为什么」，不写废话与过时注释；改代码必须过交付门禁
alwaysApply: true
---

# 注释规范

**核心原则**：代码说明「做什么」，注释说明「为什么这么做」——业务背景、边界条件、踩坑原因、为何不用其他方案。

## 交付硬门禁（强制）

凡本次会话**新增或修改**了下列符号/文件，**缺注释不得声称任务完成、不得结束回合**：

| 改动类型 | 必写 |
|----------|------|
| 新 `.ts` / `.vue` 业务文件（utils/store/api/composables/service 等） | 文件头 JSDoc（职责 + 适用场景） |
| 导出的 `function` / `class` 公开方法 / Composable / Store action | 方法 JSDoc（作用；非自解释时写 `@param` / `@returns` / `@note`） |
| 导出的 `interface` / `type` / `enum` | 类型说明；非自解释字段/枚举值逐项注释 |
| 复杂业务分支、费率/累计预扣、兼容坑点 | 逻辑上方块注释写清规则或 why |
| 复杂页面 `.vue`（多步骤主流程） | `script` 顶部短块注释：页面职责 + 主流程 |

**自检清单（改完代码后逐项打勾，未完成则继续改，禁止只口头说「已遵守」）：**

1. [ ] 新增/改动的文件是否有文件头（或页面 script 顶职责说明）？
2. [ ] 新增/改动的导出函数、action、Composable 是否有 JSDoc？
3. [ ] 新增/改动的类型字段、枚举值是否对非自解释项写了注释？
4. [ ] 复杂规则/坑点是否有 why 块注释，且与实现一致？
5. [ ] 有无废话注释、过时注释？有则删或改。

项目 `stop` hook 会在本回合改过源码时自动追问上述清单；被追问后必须补齐再结束。

## 必写注释（5 类）

### 1. 文件 / 类 / 核心接口头部

说明职责与适用场景，让阅读者一眼知道模块边界。

```typescript
/**
 * 工资条 OCR 识别与字段映射
 * 职责：调用 OcrService，将识别结果映射为 SalarySlipForm 字段
 * 适用：verify 页上传识别、历史记录回填
 */
export class SalarySlipRecognizeService { ... }
```

### 2. 复杂业务逻辑

多条件分支、状态流转、金额/费率计算等——代码再清晰也写不出业务规则，必须在逻辑上方用块注释列出规则。

```typescript
// 社保基数封顶规则（2025 北京）：
// 1. 基数低于下限按下限计
// 2. 基数高于上限按上限计
// 3. 自定义基数仅 admin 角色可改
```

### 3. 特殊处理、坑点、兼容逻辑（最重要）

写清原因、背景、影响范围；非常规写法必须注释，否则易被当 bug 删掉。

```typescript
// 必须用 String() 比较：历史数据 status 混存 number/string，=== 曾导致线上漏单
if (String(order.status) === '1') { ... }

// 超时 3s 不可改：第三方支付 3s 无响应会回滚，本地超时更长会出现「本地超时但已扣款」
await this.http.post(url, data, { timeout: 3000 })
```

### 4. 常量与枚举

每个值说明含义与业务规则，尤其状态码、类型枚举。

```typescript
/** 识别最大重试次数；限制 3 次避免重复调用 OCR 接口 */
const MAX_RETRY = 3

enum VerifyStatus {
  /** 待核对：OCR 完成，用户未确认 */
  Pending = 0,
  /** 已通过：与计算结果一致 */
  Passed = 1,
}
```

### 5. 对外 / 核心方法的文档注释

`public` 方法、跨模块工具函数、Composable、Store action 等用 JSDoc：作用、参数、返回值、异常、注意事项。

```typescript
/**
 * 根据表单参数计算税后到手工资
 * @param input 含城市、基数、专项扣除等
 * @returns 分项明细与合计；基数非法时抛 ValidationError
 * @note 税率表来自 store，切换城市会触发重新拉取
 */
export function calcNetSalary(input: SalaryCalcInput): SalaryCalcResult { ... }
```

Vue Composable 同理：`/** 工资条拍照识别：选图 → 上传 → 字段映射 */`

## 禁止写的注释（4 类）

| 类型 | 说明 | 示例 |
|------|------|------|
| 废话注释 | 把代码翻译成中文 | `// 给 a 赋值` `// 循环 10 次` |
| 过时注释 | 与实现不一致 | 注释写 3 次重试，代码已是 10 次 → **改代码必同步改注释，过时即删** |
| 情绪 / 吐槽 | 不专业，有合规风险 | `// 产品瞎改的` `// 第三方接口跟屎一样` |
| 拼音 / 黑话 | 他人无法理解 | `// 处理 cz 失败的 dd` |

## 与本仓库的衔接

- **默认**：好代码应自解释；只在上述 5 类场景补充注释，不追求「每行都有注释」。
- **语言**：中文或英文均可，团队内统一即可；禁止只有作者能懂的缩写。
- **各 App 补充约定**（在全局规范之上，详见对应规则文件）：
  - **server**：plugins 与业务边界、错误码映射、主流程编排步骤 → `nestjs-server.mdc`
  - **uni**：Composable、store、平台差异、表单校验 → `vue-uni.mdc`
  - **admin**：API、权限、动态路由、列表页模式 → `vue-admin.mdc`

## 快速自检

写或改代码时问自己：

1. 删掉注释，同事还能否理解**为何**这样写？
2. 注释是否在解释 **what** 而非 **why**？→ 删掉或改写
3. 改逻辑后，相关注释是否仍正确？→ 同步更新或删除