wurenzhi
136c2fa579
- 新增文档模板和导航结构 - 实现服务器基础API路由和控制器 - 添加扩展插件配置和前端框架 - 引入多租户和权限管理模块 - 集成日志和数据库配置 - 添加核心业务模型和类型定义
3.9 KiB
3.9 KiB
代码与提交规范 (通用规则)
本文件包含适用于所有项目的通用编码规范
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