---
name: 代码注释
description: 为文件与函数生成规范注释：补全 L3 文件头与 JSDoc（含参数、返回值、异常、@since 时间）。当需要补全/规范注释或对接文档系统时调用。
---

# 代码注释规范与模板

本 Skill 用于在现有代码中系统性地补充与规范注释，覆盖文件级 L3 头部与函数/方法的 JSDoc，确保与项目规则一致并包含时间信息。

## 适用范围
- TS/JS 源码文件（.ts/.js/.d.ts）
- Vue 组件脚本（<script setup lang="ts"> 或普通 `<script lang="ts">`）
- API 模块、工具函数、Pinia Store、路由/指令等文件

## 总体要求
- 所有函数、箭头函数、类方法必须有 JSDoc，并包含：
  - @param（逐个参数说明）
  - @returns（返回值类型与语义）
  - @throws（可能抛出的异常类型/场景）
  - @since（创建/最近修改时间，使用当前本地时间，格式：YYYY-MM-DD HH:mm:ss）
- 变量需有说明性注释（单行 // 或上方块注释），解释用途或约束。
- 文件需包含 L3 头部注释，保持与实际代码一致，且补充时间信息。
- 严格遵循工作区规则：可选链/空值合并、类型显式声明、ElMessage/ElMessageBox 不手动 import。

## 文件头（L3）模板
将以下块置于每个源文件顶部，并按实际情况填写。请在最后一行追加当前时间。

```
/**
 * [INPUT]: 依赖 {哪些模块/文件} 的 {什么功能}
 * [OUTPUT]: 对外提供 {函数/组件/类型/变量}
 * [POS]: {属于哪个模块} 的 {角色}，{与其他文件的关系}
 * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
 * [TIME]: {YYYY-MM-DD HH:mm:ss}
 */
```

## 函数 JSDoc 模板（TypeScript）
在新增或修改函数时，统一使用如下样式，并据实完善说明。时间为当前本地时间。

```ts
/**
 * 计算订单价格（含折扣与税费）。
 * @param {number} subtotal - 小计金额，必须为非负数。
 * @param {number} discountRate - 折扣比例，范围 0~1。
 * @param {number} taxRate - 税率，范围 0~1。
 * @returns {number} 最终应付金额，向下取两位小数。
 * @throws {TypeError} 当参数为 NaN 或不在有效范围时抛出。
 * @since 2026-03-09 00:00:00
 */
export const calcTotal = (subtotal: number, discountRate: number, taxRate: number): number => {
    // 小计金额（非负）
    const base: number = Math.max(0, subtotal);
    // 折扣后金额
    const afterDiscount: number = base * (1 - Math.min(Math.max(discountRate, 0), 1));
    // 含税金额
    const withTax: number = afterDiscount * (1 + Math.min(Math.max(taxRate, 0), 1));
    // 两位小数
    return Math.floor(withTax * 100) / 100;
};
```

## Vue 组件方法 JSDoc 示例
```ts
/**
 * 提交表单，包含前置校验与错误捕获。
 * @param {HTMLFormElement | null} formEl - 表单实例引用。
 * @returns {Promise<void>} 无返回值，成功后触发提示。
 * @throws {Error} 提交失败时抛出原始错误。
 * @since 2026-03-09 00:00:00
 */
const submitForm = async (formEl: HTMLFormElement | null): Promise<void> => {
    if (!formEl) throw new Error('表单不存在');
    try {
        // ... 业务提交逻辑
        ElMessage.success('提交成功');
    } catch (err) {
        ElMessage.error('提交失败');
        throw err as Error;
    }
};
```

## 变量注释规范
- 使用清晰命名并补充注释解释用途、单位、取值范围或约束。
- 建议将关键变量的注释置于上一行；简单变量可使用行尾注释。

```ts
// 列表加载状态：用于禁用按钮与展示骨架屏
const loading: boolean = false;

const PAGE_SIZE_DEFAULT = 20; // 默认分页大小
```

## 执行步骤（生成策略）
1. 打开文件：若缺失 L3 头部则添加；若存在则对齐实际依赖与输出并补充 [TIME]。
2. 检查所有导出函数与内部复杂函数：
   - 无 JSDoc → 按模板创建并填写；
   - 已有 JSDoc → 校正缺失项（参数/返回/异常/时间）。
3. Vue 文件仅在 `<script>` 内处理函数注释，避免污染模板与样式段落。
4. 遵循 TypeScript 显式类型与异常处理最佳实践，新增 `@throws` 对应的 try-catch 或参数校验。
5. 变量逐一补充注释，优先关注导出常量、复杂对象、关键状态。

## 校验清单
- [ ] 文件顶端存在 L3 头部且包含 [TIME] 当前时间
- [ ] 所有函数/方法具备完整 JSDoc（@param/@returns/@throws/@since）
- [ ] 重要变量均有注释说明
- [ ] 不新增 `any`，类型定义明确
- [ ] 未手动导入 ElMessage/ElMessageBox

## 说明
- 时间字段统一使用本地时间“YYYY-MM-DD HH:mm:ss”，生成时以当前时刻为准。
- 若文件属于模块或被多处引用，需在 L3 中准确填写 POS 与 INPUT/OUTPUT，保持与 CLAUDE.md 同步。