# 代码与提交规范 (通用规则)

> 本文件包含适用于所有项目的通用编码规范

---

## 1. 基础规范

- **使用 TypeScript**；禁止 any（必要场景以 TODO 标注并跟进）
- **文件命名**：小写短横线；TypeScript 类型与接口使用大驼峰
- **分支命名**：feature/, fix/, docs/, chore/；提交信息以动词开头，中文或英文均可
- **变更前**：必须通过构建与基础校验脚本：npm run check
- **注释要求**：中文注释，紧贴代码语句，描述意图而非过程；禁止冗长段落

---

## 2. Lint 与格式化

- **ESLint**：插件启用 ESLint（React+TS）；后端暂不强制 ESLint
- **代码风格**：统一缩进 2 空格；UTF-8；换行 LF；末尾换行
- **编辑器**：建议在本地启用编辑器保存时格式化（遵循 .editorconfig）

---

## 3. TypeScript 约束

- **Strict 模式**：extension/ tsconfig：strict 开启；paths 使用 @/*
- **类型安全**：server/ tsconfig：保持严格类型；避免 any 与隐式 any

---

## 4. API 约定

- **响应结构**：所有响应统一结构：{ success: boolean, data?: any, error?: string }
- **错误处理**：错误码与信息需清晰、可定位；4xx 为入参错误，5xx 为服务异常
- **CORS**：白名单通过环境变量 ALLOWED_ORIGINS 配置
- **速率限制**：通过 RATE_LIMIT_REQUESTS 与 RATE_LIMIT_WINDOW_MS 配置

---

## 5. 安全与保密

- **密钥管理**：严禁提交任何密钥或私密配置；环境变量由 .env 管理并忽略提交

---

## 6. 提交前校验

- **严禁全量构建**：为节省服务器/本机开销，日常开发流程中**严禁运行** `npm run build`
- **强制自我审计**：开发者（AI）必须在交付代码前，通过 `Read` 与 `GetDiagnostics` 进行逻辑自查与类型校验
- **逻辑自查标准**：代码必须细致到“部署即运行”，业务链路必须闭环（如：新增字段必须在 API 响应中体现，且在 Service 中有对应处理）
- **禁止跨 AI 审计**：每个窗口仅负责自身代码的业务完整性，无需等待其他 AI 审计，直接交付

---

## 7. Todo 列表执行规范

- **任务同步**：必须通过 `TodoWrite` 工具同步任务进度；每次对话开始时应优先规划或更新任务列表
- **任务管理**：在任务列表中所有 `pending` 或 `in_progress` 的任务未处理完成或未记录明确阻塞原因前，严禁主动终止对话回合或将控制权交还给用户
- **阻塞处理**：如果任务被阻塞（Blocked），AI 必须在 Todo 或看板中清晰列举出当前遇到的“自我问题”，并遵循 **RCA 强制模板**：
  - `[CATEGORY]`：(Context Missing / Logic Conflict / API Hallucination / Env Issue)
  - `[ROOT_CAUSE]`：(具体原因，如：.env 缺少某 Key)
  - `[MITIGATION]`：(修复建议或 Fallback 路径，如：手动在 .env 补充该 Key 或使用模拟数据)
- **流程闭环**：必须遵循“规划 -> 执行 -> 验证 -> 归档”的完整闭环，单次执行应尽可能覆盖多个关联任务以提高效率
- **任务描述**：必须使用中文，并清晰定义“核心/架构/业务/UI”等模块属性

---

## 8. AI 可读性优先原则

- **标准命名**：禁止任何语义不明的缩写。变量名与函数名必须具备强描述性，以最大化 IDE 自动补全的预测准确度
- **JSDoc 驱动**：在实现逻辑前，必须编写详尽的 JSDoc（含 `@param`, `@returns`, `@throws`）。这不仅是文档，更是为 Autocomplete 提供精准的上下文先验知识
- **小函数原则**：单个函数逻辑控制在 30 行以内。函数越短，Autocomplete 的补全信心指数越高，从而减少人工手动输入的 Dollar Usage 成本
- **函数命名**：必须表达业务意图（禁止缩写语义漂移），同类逻辑必须复用统一 Service

---

*本文件为通用编码规范，项目特定规则请参考 project-specific-rules.md*\n