78 lines
3.9 KiB
Markdown
78 lines
3.9 KiB
Markdown
|
# 代码与提交规范 (通用规则)
|
|||
|
|
|
|||
|
|
> 本文件包含适用于所有项目的通用编码规范
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 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
|