Cursor rule

1---
2description: 全仓注释规范——解释「为什么」，不写废话与过时注释；改代码必须过交付门禁
3alwaysApply: true
4---
5 
6# 注释规范
7 
8**核心原则**：代码说明「做什么」，注释说明「为什么这么做」——业务背景、边界条件、踩坑原因、为何不用其他方案。
9 
10## 交付硬门禁（强制）
11 
12凡本次会话**新增或修改**了下列符号/文件，**缺注释不得声称任务完成、不得结束回合**：
13 
14| 改动类型 | 必写 |
15|----------|------|
16| 新 `.ts` / `.vue` 业务文件（utils/store/api/composables/service 等） | 文件头 JSDoc（职责 + 适用场景） |
17| 导出的 `function` / `class` 公开方法 / Composable / Store action | 方法 JSDoc（作用；非自解释时写 `@param` / `@returns` / `@note`） |
18| 导出的 `interface` / `type` / `enum` | 类型说明；非自解释字段/枚举值逐项注释 |
19| 复杂业务分支、费率/累计预扣、兼容坑点 | 逻辑上方块注释写清规则或 why |
20| 复杂页面 `.vue`（多步骤主流程） | `script` 顶部短块注释：页面职责 + 主流程 |
21 
22**自检清单（改完代码后逐项打勾，未完成则继续改，禁止只口头说「已遵守」）：**
23 
241. [ ] 新增/改动的文件是否有文件头（或页面 script 顶职责说明）？
252. [ ] 新增/改动的导出函数、action、Composable 是否有 JSDoc？
263. [ ] 新增/改动的类型字段、枚举值是否对非自解释项写了注释？
274. [ ] 复杂规则/坑点是否有 why 块注释，且与实现一致？
285. [ ] 有无废话注释、过时注释？有则删或改。
29 
30项目 `stop` hook 会在本回合改过源码时自动追问上述清单；被追问后必须补齐再结束。
31 
32## 必写注释（5 类）
33 
34### 1. 文件 / 类 / 核心接口头部
35 
36说明职责与适用场景，让阅读者一眼知道模块边界。
37 
38```typescript
39/**
40 * 工资条 OCR 识别与字段映射
41 * 职责：调用 OcrService，将识别结果映射为 SalarySlipForm 字段
42 * 适用：verify 页上传识别、历史记录回填
43 */
44export class SalarySlipRecognizeService { ... }
45```
46 
47### 2. 复杂业务逻辑
48 
49多条件分支、状态流转、金额/费率计算等——代码再清晰也写不出业务规则，必须在逻辑上方用块注释列出规则。
50 
51```typescript
52// 社保基数封顶规则（2025 北京）：
53// 1. 基数低于下限按下限计
54// 2. 基数高于上限按上限计
55// 3. 自定义基数仅 admin 角色可改
56```
57 
58### 3. 特殊处理、坑点、兼容逻辑（最重要）
59 
60写清原因、背景、影响范围；非常规写法必须注释，否则易被当 bug 删掉。
61 
62```typescript
63// 必须用 String() 比较：历史数据 status 混存 number/string，=== 曾导致线上漏单
64if (String(order.status) === '1') { ... }
65 
66// 超时 3s 不可改：第三方支付 3s 无响应会回滚，本地超时更长会出现「本地超时但已扣款」
67await this.http.post(url, data, { timeout: 3000 })
68```
69 
70### 4. 常量与枚举
71 
72每个值说明含义与业务规则，尤其状态码、类型枚举。
73 
74```typescript
75/** 识别最大重试次数；限制 3 次避免重复调用 OCR 接口 */
76const MAX_RETRY = 3
77 
78enum VerifyStatus {
79  /** 待核对：OCR 完成，用户未确认 */
80  Pending = 0,
81  /** 已通过：与计算结果一致 */
82  Passed = 1,
83}
84```
85 
86### 5. 对外 / 核心方法的文档注释
87 
88`public` 方法、跨模块工具函数、Composable、Store action 等用 JSDoc：作用、参数、返回值、异常、注意事项。
89 
90```typescript
91/**
92 * 根据表单参数计算税后到手工资
93 * @param input 含城市、基数、专项扣除等
94 * @returns 分项明细与合计；基数非法时抛 ValidationError
95 * @note 税率表来自 store，切换城市会触发重新拉取
96 */
97export function calcNetSalary(input: SalaryCalcInput): SalaryCalcResult { ... }
98```
99 
100Vue Composable 同理：`/** 工资条拍照识别：选图 → 上传 → 字段映射 */`
101 
102## 禁止写的注释（4 类）
103 
104| 类型 | 说明 | 示例 |
105|------|------|------|
106| 废话注释 | 把代码翻译成中文 | `// 给 a 赋值` `// 循环 10 次` |
107| 过时注释 | 与实现不一致 | 注释写 3 次重试，代码已是 10 次 → **改代码必同步改注释，过时即删** |
108| 情绪 / 吐槽 | 不专业，有合规风险 | `// 产品瞎改的` `// 第三方接口跟屎一样` |
109| 拼音 / 黑话 | 他人无法理解 | `// 处理 cz 失败的 dd` |
110 
111## 与本仓库的衔接
112 
113- **默认**：好代码应自解释；只在上述 5 类场景补充注释，不追求「每行都有注释」。
114- **语言**：中文或英文均可，团队内统一即可；禁止只有作者能懂的缩写。
115- **各 App 补充约定**（在全局规范之上，详见对应规则文件）：
116  - **server**：plugins 与业务边界、错误码映射、主流程编排步骤 → `nestjs-server.mdc`
117  - **uni**：Composable、store、平台差异、表单校验 → `vue-uni.mdc`
118  - **admin**：API、权限、动态路由、列表页模式 → `vue-admin.mdc`
119 
120## 快速自检
121 
122写或改代码时问自己：
123 
1241. 删掉注释，同事还能否理解**为何**这样写？
1252. 注释是否在解释 **what** 而非 **why**？→ 删掉或改写
1263. 改逻辑后，相关注释是否仍正确？→ 同步更新或删除
127