# 开发规范
## 工作要求
1. 行动前必须先要做计划，行动前必须先要做计划，行动前必须先要做计划。
2. 项目的具体描述在同级目录下：READMD.md 文档中。

## 编码规范
1. 编码前必须先要做计划，编码前必须先要做计划，编码前必须先要做计划。
2. 计划文档放置在当前目录 docs/plan，按照 [yyyy-MM-dd_HH-mm]_[模块名].md 格式命名。
3. 依据计划拆解任务，编码严格遵循计划。
4. 完成编码需要测试所有功能与函数。
5. 测试通过后，创建或更新文档(位于当前目录 docs/modules/ 下)，提交 Git。

## 命名规范
1. 命名须具备描述性，严禁使用拼音、无意义缩写。
2. 类名使用 UpperCamelCase，方法/变量使用 lowerCamelCase，常量使用 UPPER_SNAKE_CASE。
3. 布尔变量/方法前缀须为 is、has 或 can。

## 注释规范
1. 公共类、公共方法必须添加文档注释，说明功能、参数及返回值。
2. 复杂逻辑或算法须在代码块上方添加行内注释解释意图。
3. 代码修改时须同步更新相关注释，严禁注释与代码不一致。
4. 禁止保留废弃代码注释或无用的署名注释。

## 项目结构规范
1. 源码置于 src 目录，测试代码置于 tests 目录。
2. 文档置于 docs 目录，环境配置置于 config 或根目录。
3. 单个文件代码行数不宜超过 500 行，超过时须拆分。

## Git 规范
1. 提交粒度须原子化，每次提交仅解决一个具体问题。
2. Commit Message 格式：<type>(<scope>): <subject>。
3. type: feat (新功能), fix (修复), docs (文档), refactor (重构), test (测试)。
示例：feat(user): add login module。
4. 禁止直接提交至主分支，须从开发分支提交 Pull Request/Merge Request。

## 测试规范
1. 核心业务逻辑须有单元测试覆盖。
2. 测试须遵循 AAA 原则：Arrange (准备), Act (执行), Assert (断言)。
3. 测试用例须覆盖正常流程、边界条件及异常情况。
4. 提交代码前须确保所有测试用例通过。

## 依赖管理规范
1. 禁止私自引入未经评估的依赖库。
2. 依赖版本须锁定，禁止使用模糊版本号 (如 ^, ~, *)。
3. 引入新依赖须在文档中说明用途及理由。

## 禁止事项
1. 禁止未经计划的直接编码。
2. 禁止提交包含敏感信息（密钥、账号密码）的代码。
3. 禁止在循环中执行数据库查询或网络请求。
4. 禁止使用 console.log 或 print 进行调试后遗留的输出语句。
5. 禁止忽略编译器或 Linter 的错误与警告。