编码规范（通用）

目标：把"代码可维护、团队一致、AI 输出稳定"落到可执行规则。

1. 代码风格

• 风格: 遵循 StandardJS（无分号、2 空格、单引号）。
• 中文优先: 代码注释、文档备注、JSDoc 默认使用中文（除非你明确要求英文）。

1.1 JSDoc/TSDoc 注释规范（强制要求）

• 必须注释: 所有公开的函数、方法、类、接口必须使用 JSDoc/TSDoc 风格的中文注释
• 注释位置: 注释必须放在被注释代码的紧前面，使用 /** 开始（两个星号）
• 基本格式:

  /**
   * 函数的简短描述（一句话说明功能）
   *
   * @param {类型} 参数名 - 参数说明
   * @returns {类型} 返回值说明
   */

• 必需标签:
  • @param: 所有参数必须说明类型和用途
  • @returns: 必须说明返回值类型和含义
  • @throws: 可能抛出的异常必须说明
• 推荐标签:
  • @example: 提供使用示例
  • @typedef: 定义复杂类型
  • @template: 泛型类型说明

2. 结构与可维护性

• 单一职责: 每个函数/模块只做一件事；函数超过 50 行建议拆分。
• 可读性优先: 命名清晰，避免过度炫技导致维护成本上升。

3. TypeScript 规范

• 类型安全: 禁止滥用 any。
• 接口显式: Props、Emits、API 响应必须显式定义类型。

4. UI/UX 规范

• 禁用原生 select: 严禁使用浏览器原生 <select> 标签；必须封装自定义 Select（移动端支持 Bottom Sheet 底部抽屉等交互）。

5. 路径与环境

• 前端路径: 优先使用别名路径（例如 @/）。
• Python 路径（如需）: 强制使用 pathlib。

6. 任务初始化（AI 核心行为）

• 真理来源: 任务启动时，必须优先扫描项目根目录下的 .plan、.review 和 .rule 文件夹。若存在，其内容优先级高于通用指令，必须严格遵循其中的开发要求与审核基准。

7. 样式与预处理器 (Sass)

• 现代语法: 严禁使用已废弃的 @import；强制使用 @use 进行模块化引入。
• 全局注入: 共享的变量、Mixins 必须通过 Vite 的 additionalData 进行全局注入，严禁在组件内手动重复引入变量文件。
• 色彩处理: 使用 sass:color 模块（如 color.adjust）替代旧的 darken/lighten 函数。

8. 安全写入规范 (Safety Writing)

• 原子化写入: 严禁通过 Shell 直接写入包含 Vue 模板、特殊符号的长文本代码，以免引起转义错误。
• 工具优先: 涉及文件创建/修改，必须优先调用 write_file 或 replace 专用工具。