← 返回首页
代码注释与文档规范
# anenreo 代码注释、目录说明与 HTML 文档关联规范
## 1. 基本原则
1. 人工编写的注释统一使用简体中文。
2. 类名、方法名、变量名、字段名、文件名、目录名和 API 技术标识仍使用英文，并遵循 TypeScript、NestJS、Nuxt、Vue 和 uni-app 的命名规范。
3. 注释重点说明：
- 代码承担什么业务职责；
- 为什么采用当前实现和分层；
- 与哪些模块、文件、接口和数据结构存在调用关系；
- 有哪些业务约束、边界条件、事务、并发、幂等、隐私或副作用；
- 对应哪一份离线 HTML 文档。
4. 禁止只把代码字面含义翻译成中文。
不推荐：
```ts
// 获取用户
const user = await userService.getCurrentUser()
```
推荐：
```ts
// 查询当前登录用户的完整资料，用于初始化个人中心页面；返回值不包含密码和令牌。
const user = await userService.getCurrentUser()
```
5. 修改实现时必须同步修改注释和 HTML 文档，禁止保留与代码不一致的过期说明。
6. 禁止无信息量占位注释，例如“这是一个方法”“定义变量”“执行相关逻辑”“后续补充”“处理数据”。
7. 注释不得虚构不存在的模块、文件、接口、任务编号、业务规则或安全能力。
8. 注释不得包含密码、密钥、令牌、真实个人数据或可恢复秘密。
## 2. 文件头注释规范
除自动生成文件、第三方文件、锁文件、编译产物、压缩文件和不支持注释的标准 JSON 外，每个源代码文件开头必须包含中文文件说明。
文件头至少包含：
- 文件用途；
- 所属模块；
- 关联文件及具体关联关系；
- 主要职责；
- 关键依赖；
- 必要的输入、输出、副作用和使用限制；
- 对应 HTML 文档的 `@see` 或“文档关联”。
### 2.1 TypeScript 文件头
```ts
/**
* 文件用途：
* 编排个人记忆创建、修订、查询和导出流程。
*
* 所属模块：
* 记忆、日记与周期报告（Memory Module）
*
* 关联文件：
* - memory.controller.ts：接收 HTTP 请求并调用本服务。
* - memory.repository.ts：由本服务调用，保存当前状态和修订历史。
* - memory.aggregate.ts：定义用户原文不可覆盖等领域不变量。
* - interview.module-api.ts：访谈候选经确认后调用记忆模块公共接口。
*
* 主要职责：
* 1. 保留用户原文。
* 2. 维护修订号和乐观锁。
* 3. 生成可移植导出。
*
* 注意事项：
* - 本文件不直接创建数据库连接。
* - AI 整理稿不得覆盖用户原文。
*
* @see ../../../../../docs-site/modules/memory.html
*/
```
### 2.2 Vue 单文件组件文件头
```vue
<!--
文件用途：
展示个人记忆列表并提供创建入口。
所属模块：
记忆、日记与周期报告（Memory Module）
关联文件：
- useApi.ts：统一调用后端接口并转换错误。
- memory.controller.ts：提供页面所需 HTTP 接口。
- memory.html：说明页面状态、隐私和版本规则。
主要职责：
1. 展示加载、空数据、错误和正常状态。
2. 提交用户原始正文和时间语义。
注意事项：
- 页面不直接使用数据库结构。
- 页面不自行判断服务端权限。
文档关联：
docs-site/modules/memory.html
-->
```
### 2.3 文件头关联规则
关联文件不能只列名称，必须说明调用方向和作用。
推荐：
```text
- decision.controller.ts：调用本服务创建和复盘决策。
- decision.repository.ts：由本服务调用，持久化决策及其预测。
- constitution.module-api.ts：由本服务调用，读取与决策相关的个人原则引用。
```
不推荐：
```text
decision.controller.ts
decision.repository.ts
constitution.module-api.ts
```
## 3. 类、接口、类型和枚举注释规范
所有类、接口、类型别名、枚举和枚举成员都必须有中文注释，说明业务含义和适用范围。
```ts
/**
* 用户应用服务。
*
* 负责协调用户领域对象、仓储和外部服务，
* 不负责处理 HTTP 参数和数据库底层连接。
*/
export class UserService {}
```
```ts
/**
* 用户资料查询结果。
*
* 用于用户中心页面展示，不包含密码、令牌和内部审计字段。
*/
export interface UserProfile {}
```
```ts
/**
* 系统支持的用户状态。
*
* active：账号可正常登录；
* disabled：账号已停用；
* pending：账号尚未完成激活。
*/
export type UserStatus = 'active' | 'disabled' | 'pending'
```
```ts
/** 订单支付状态。 */
export enum PaymentStatus {
/** 尚未发起支付。 */
Pending = 'pending',
/** 支付平台已确认支付成功。 */
Paid = 'paid',
/** 支付失败或交易已关闭。 */
Failed = 'failed'
}
```
## 4. 方法、函数、Hook 和事件处理函数
所有业务方法、公共方法、导出函数、Composable、Hook、事件处理函数和具有明确业务语义的内部方法都必须有中文文档注释。
方法注释按实际情况包含：
- 方法用途；
- 参数的业务含义、格式、单位和有效范围；
- 返回结果；
- 可能抛出的异常；
- 副作用；
- 前置条件；
- 重要业务规则；
- 事务、并发、幂等和缓存要求。
```ts
/**
* 根据注册参数创建新用户。
*
* 业务规则：
* - 邮箱在系统内不区分大小写且保持唯一；
* - 密码在持久化前必须完成不可逆哈希；
* - 用户创建和默认角色绑定位于同一事务；
* - 激活邮件发送失败不回滚用户创建事务，但会生成重试任务。
*
* @param input 用户注册参数
* @returns 创建后的公开用户信息，不包含密码哈希
* @throws EmailAlreadyExistsError 邮箱已经注册时抛出
* @throws InvalidPasswordError 密码不符合安全规则时抛出
*/
async function createUser(input: CreateUserInput): Promise<UserProfile> {}
```
简单方法也应说明真实用途：
```ts
/**
* 判断当前用户是否具有后台管理权限。
*
* @param user 待判断的用户对象
* @returns 用户角色中包含管理员角色时返回 true
*/
function isAdmin(user: User): boolean {
return user.roles.includes(UserRole.Admin)
}
```
异步方法应说明副作用：
```ts
/**
* 取消指定订单并释放已锁定库存。
*
* 该操作更新订单状态并调用库存模块释放库存。
* 方法按照 orderId 保证业务幂等，重复取消不会重复释放库存。
*
* @param orderId 待取消的订单编号
* @throws OrderNotFoundError 订单不存在时抛出
* @throws OrderCannotBeCancelledError 当前状态不允许取消时抛出
*/
async function cancelOrder(orderId: string): Promise<void> {}
```
## 5. 参数注释规范
参数注释不能只重复参数名称，应说明：
- 业务含义；
- 数据格式；
- 单位；
- 有效范围；
- 是否允许为空；
- 默认行为；
- 特殊约束。
```ts
/**
* 计算订单应付金额。
*
* @param items 订单商品列表，必须至少包含一个商品
* @param discountAmount 优惠金额，单位为分，不得小于 0
* @param shippingFee 配送费用，单位为分，未传入时按 0 处理
* @returns 最终应付金额，单位为分，结果不会小于 0
*/
function calculatePayableAmount(
items: OrderItem[],
discountAmount: number,
shippingFee = 0
): number {}
```
Boolean 参数优先改为配置对象：
```ts
/** 删除用户时的关联处理选项。 */
export interface DeleteUserOptions {
/** 是否同时删除用户上传的文件。 */
deleteUploadedFiles: boolean
/** 是否向用户发送账号注销通知。 */
sendNotification: boolean
}
```
## 6. 字段和属性注释规范
以下字段必须有中文注释：
- 类属性；
- 接口属性；
- DTO 字段；
- 数据库实体字段；
- 配置项；
- 状态字段；
- 常量；
- 枚举成员；
- 对外对象属性。
字段说明按需要包含业务含义、来源、格式、单位、可空性、默认值、范围、敏感性、持久化方式和生命周期。
```ts
/** 创建用户时使用的请求参数。 */
export class CreateUserDto {
/**
* 用户登录邮箱。
* 必须为合法邮箱格式，系统内不区分大小写且保持唯一。
*/
email!: string
/**
* 用户原始密码。
* 仅用于接收请求，不得持久化、返回或记录到日志。
*/
password!: string
/** 用户显示名称，长度为 2 至 50 个字符。 */
displayName!: string
}
```
```ts
/** 分页查询选项。 */
export interface PaginationOptions {
/** 当前页码，从 1 开始。 */
page: number
/** 每页记录数，允许范围为 1 至 100。 */
pageSize: number
/** 排序字段，只允许服务端白名单中的字段。 */
sortBy?: string
/** 排序方向，未传入时默认降序。 */
sortOrder?: 'asc' | 'desc'
}
```
## 7. 局部变量注释规范
不要求对每个局部变量机械注释。仅在以下情况添加：
- 变量代表复杂业务概念；
- 单位或格式不直观；
- 数据经过特殊转换；
- 变量名不足以表达约束；
- 后续逻辑依赖隐含条件。
推荐：
```ts
// 金额统一使用“分”计算，避免二进制浮点数造成财务误差。
const payableAmountInCents = calculatePayableAmount(order)
```
不推荐：
```ts
// 定义订单
const order = await getOrder()
```
## 8. 复杂逻辑与兼容处理
复杂业务分支、算法、兼容逻辑和异常兜底应在代码块前解释设计原因，而不是逐行复述代码。
```ts
// 支付平台可能重复发送回调。
// 先检查订单状态，避免重复更新余额和重复发送通知。
if (order.paymentStatus === PaymentStatus.Paid) return
```
```ts
// 旧版客户端没有时区字段。
// 暂用 Asia/Shanghai 兼容；旧版客户端全部下线后按任务 MOB-128 删除。
const timezone = request.timezone ?? 'Asia/Shanghai'
```
## 9. 常量和配置项注释
所有业务常量、环境变量映射和重要配置项必须说明含义、单位、来源和默认行为。
```ts
/**
* 单次批量导出的最大记录数。
* 用于限制数据库查询和文件生成的内存占用。
*/
export const MAX_EXPORT_RECORDS = 10_000
```
```ts
/** JWT 运行配置。 */
export interface JwtConfig {
/**
* JWT 签名密钥。
* 来源于服务端环境变量 JWT_SECRET，属于敏感信息，生产环境必须显式配置。
*/
secret: string
/** 访问令牌有效期，单位为秒。 */
accessTokenTtl: number
}
```
## 10. API、数据库和跨模块调用注释
API、事务、消息队列、缓存、AI 服务和第三方服务调用必须说明关键行为。
```ts
/**
* 获取当前登录用户资料。
*
* 接口：GET /api/v1/users/me
* 权限：要求用户已登录
* 缓存：客户端最多缓存 60 秒
*
* @returns 当前用户公开资料
*/
```
```ts
// 用户创建和默认角色绑定必须位于同一事务，
// 防止产生没有任何角色的无效用户数据。
await database.transaction(async (transaction) => {
// 事务内操作
})
```
```ts
/**
* 发布订单已支付事件。
*
* 消费方：
* - 库存模块：确认库存扣减；
* - 通知模块：发送支付成功通知；
* - 分析模块：记录支付指标。
*
* 事件按照 orderId 保证业务幂等，不携带支付凭证和用户秘密。
*/
```
## 11. TODO、FIXME 和临时兼容注释
禁止没有上下文的 TODO/FIXME。
不推荐：
```ts
// TODO: 优化
```
推荐：
```ts
// TODO(MEM-012)：当前导出未包含附件清单；
// 待对象存储清单接口完成后补充，并同步更新恢复测试。
```
临时逻辑必须说明：
- 为什么临时存在；
- 移除条件；
- 关联真实任务编号；
- 影响模块。
```ts
// FIXME(PAY-256)：第三方支付接口暂未返回退款完成时间。
// 当前使用本地回调接收时间；平台升级并完成回归测试后移除此兼容逻辑。
```
## 12. HTML 文档关联规范
每个业务源文件必须关联 `docs-site/` 下的静态 HTML 页面。常用链接：
```text
docs-site/modules/memory.html
docs-site/modules/relationship.html
docs-site/architecture/modules.html
docs-site/architecture/web-ui.html
docs-site/architecture/mobile.html
docs-site/reference/api.html
docs-site/reference/database.html
docs-site/reference/environment.html
```
### 12.1 关联粒度
- 业务模块文件关联 `docs-site/modules/<module>.html`；
- HTTP 和契约关联 `docs-site/reference/api.html` 与 `contracts.html`；
- 数据仓储关联 `docs-site/reference/database.html`；
- 环境配置关联 `docs-site/reference/environment.html`；
- Web 与移动端基础设施关联对应架构页面；
- 注释检查、生成脚本和文档检查关联本规范页面。
### 12.2 同步规则
代码逻辑、字段、接口、目录、权限或副作用变化时，必须同步更新：
1. 源码注释；
2. Markdown 规范；
3. 生成后的 HTML 文档；
4. 测试或验收说明；
5. 模块目录和共享契约。
`pnpm check:docs` 校验源码引用的 HTML 页面存在，`pnpm check:comments` 校验文件头和声明注释结构。
## 13. 注释豁免范围
以下文件可豁免文件头：
- `pnpm-lock.yaml`、`package-lock.json` 等依赖锁文件；
- 自动生成文件；
- 第三方复制文件；
- 编译产物；
- 压缩文件和二进制文件；
- 数据库客户端自动生成代码；
- 不支持注释的标准 JSON；
- 完全由工具维护且有相邻说明文档的配置。
对于 JSON 配置，通过相邻 README 或 `docs/configuration.md` 说明关键字段和环境差异。
自动生成文件在工具允许时添加：
```ts
/**
* 本文件由代码生成器自动生成，请勿手动修改。
* 生成来源：scripts/generate-api-types.ts
* 输入文件：openapi.yaml
*/
```
## 14. 质量验收清单
提交前检查：
1. 文件头是否准确描述职责；
2. 关联文件是否真实存在；
3. 调用方向是否说明清楚；
4. 方法参数、返回值和异常是否与实现一致；
5. 字段单位、格式、可空性和默认值是否准确；
6. 是否存在逐字翻译代码的无效注释；
7. 是否存在过期或矛盾注释；
8. 是否泄露密码、密钥、令牌或真实个人信息；
9. 是否虚构模块、接口、任务编号或业务规则；
10. 注释是否足以让新开发者理解模块边界和调用关系；
11. HTML 文档关联是否有效；
12. 代码变化是否同步生成文档和测试。
## 15. 自动化门禁
```bash
pnpm check:comments
pnpm check:docs
pnpm check:syntax
```
`check:comments` 至少检查：
- 人工源码具有中文文件头；
- 文件头包含用途、模块、关联、职责和 HTML 文档链接；
- 导出声明、类、接口、类型、枚举、业务方法和字段具有 JSDoc；
- 无空洞注释；
- TODO/FIXME 带真实任务编号。
自动检查只能识别结构性问题。评审者仍需确认注释与代码、业务和实际文件关系一致。
## 16. 可直接用于 AI Agent 的精简规则
```text
1. 所有人工编写的源文件开头必须有简体中文文件说明，包含用途、所属模块、关联文件和调用方向、主要职责、关键依赖、副作用、限制以及 HTML 文档链接。
2. 所有类、接口、类型别名、枚举、业务方法、导出函数、Hook、DTO 字段、实体字段、接口字段、类属性、配置项、常量和枚举成员必须有准确中文注释。
3. 方法注释说明用途、参数业务含义、返回值、异常、业务规则、副作用、事务、幂等、缓存和并发要求。
4. 字段注释说明业务含义、格式、单位、范围、可空性、默认值、来源、敏感性和生命周期。
5. 注释解释职责、设计原因和约束，不逐字翻译代码；禁止“定义变量”“执行逻辑”“处理数据”等空洞注释。
6. 局部变量仅在复杂概念、特殊单位、兼容逻辑和隐含条件下添加注释。
7. 复杂逻辑、事务、缓存、队列、AI 和第三方调用必须说明为什么这样处理以及副作用。
8. TODO/FIXME 必须说明问题、移除条件、影响模块和真实任务编号。
9. 修改实现必须同步修改注释、HTML 文档和测试，禁止虚构关联文件或业务规则。
10. 自动生成、第三方、锁文件、编译产物和标准 JSON 可豁免文件头；其配置通过 README 或 docs 说明。
11. 注释使用简体中文，技术标识保持英文。
```
最重要的判断标准是：**注释必须解释职责、约束和设计原因，而不是把代码翻译成中文。**