ShaoHua
4fe0b5a963
本次提交完成了项目核心基础架构升级： 1. 新增动态API中间件与权限控制系统，支持匿名/鉴权接口分离 2. 搭建云同步服务体系，包含认证、任务同步、安全策略等核心模块 3. 实现语音控制全链路，从STT/意图解析到命令执行 4. 新增任务类型、附件实体与相关仓储接口 5. 重构前端配置与代理规则，统一后端端口为5057 6. 新增多平台测试项目与CI脚本优化 7. 完善项目文档与代码注释规范 移除了旧版迁移文件与冗余代理配置，调整项目结构适配跨平台部署需求。
88 lines
3.2 KiB
Markdown
88 lines
3.2 KiB
Markdown
# 代码实现与测试先行规范（必须遵守）
|
||
|
||
> 全局规则。规定何时必须写测试 + 怎么写（ATDD：验收测试驱动开发）。与 [04-研发工单全流程规范.md](./04-研发工单全流程规范.md) 配套：04 管工单拆分，本规范管实现与验收。
|
||
|
||
---
|
||
|
||
## 一、触发条件（什么时候必须写测试）
|
||
|
||
用户表述满足以下任一条件时，**必须**执行测试先行：
|
||
|
||
| 触发条件 | 示例 |
|
||
|---|---|
|
||
| 明确指出 bug（"修正"/"修复"/"不应该"/"404"） | "登录按钮点不了""/sync 404""数据丢了" |
|
||
| 要求新增功能 | "加一个导出按钮""新增 XX 端点" |
|
||
| 要求修改现有行为 | "把优先级改成默认高""去掉确认弹窗" |
|
||
|
||
**豁免**（无需测试先行，但改动后必须跑已有测试）：
|
||
|
||
| 场景 | 示例 |
|
||
|---|---|
|
||
| 纯配置 | `appsettings.json` 默认值、连接字符串 |
|
||
| 纯格式化/注释 | ESLint 自动修复、XML doc 补充 |
|
||
| 依赖升级无 API 变更 | NuGet/npm 补丁版本 |
|
||
| 文档/规则更新 | 新增 `.trae/rules/` 文件 |
|
||
|
||
> 判定原则：改动出错用户能感知 → 不可豁免。
|
||
|
||
---
|
||
|
||
## 二、强制流程
|
||
|
||
1. **提炼验收点**：从用户描述提取 Given-When-Then 验收场景（主:分支:异常 ≈ 1:2:2）
|
||
2. **RED**：写验收测试，实跑确认失败（失败原因 = 被测功能缺失，非 setup 错误）
|
||
3. **GREEN**：写最小量代码使测试通过
|
||
4. **REFACTOR**：重构优化，重跑测试仍 GREEN
|
||
|
||
**不得跳过任何步骤。**
|
||
|
||
## 三、验收测试用例规范
|
||
|
||
格式（Given-When-Then）：
|
||
|
||
```
|
||
Given [前置条件]
|
||
When [操作]
|
||
Then [预期结果]
|
||
```
|
||
|
||
示例：`Given 本地 3 个未完成待办 / When POST /api/task 创建"写周报" / Then 返回 201 且共 4 条`
|
||
|
||
要求：
|
||
- 命名体现场景：`CreateTask_EmptyTitle_Returns400`
|
||
- 一个测试只验证一个行为点
|
||
- 断言可量化
|
||
- 至少覆盖集成测试层（不满足于纯单元测试）
|
||
|
||
## 四、工单完成判定（全部满足才标记"已完成"）
|
||
|
||
1. 所有验收测试通过
|
||
2. 原有测试无回归
|
||
3. [04-即时状态记忆.md](../项目/04-即时状态记忆.md) 或 `00-工单总览.md` 待验证表标注"已验证"
|
||
4. 按 [03-文档同步规范.md](./03-文档同步规范.md) 同步文档
|
||
|
||
## 五、Git Checkpoint 提交（推荐）
|
||
|
||
| 阶段 | 提交信息 |
|
||
|---|---|
|
||
| RED | `test(workitem): 为 <工单> 添加失败的验收测试` |
|
||
| GREEN | `feat(workitem): 实现 <工单> 使验收测试通过` |
|
||
| REFACTOR | `refactor(workitem): 重构 <模块> 保持测试通过` |
|
||
|
||
流程完成前不得 squash。提交信息禁用歧义"任务"二字。
|
||
|
||
## 六、检查清单
|
||
|
||
- [ ] 触发条件满足？豁免类是否确认无行为变更？
|
||
- [ ] 提炼了 Given-When-Then 验收场景？
|
||
- [ ] RED 实跑确认失败，失败原因 = 功能缺失？
|
||
- [ ] GREEN 最小代码通过测试？
|
||
- [ ] REFACTOR 后测试仍 GREEN？
|
||
- [ ] 场景覆盖主/分支/异常？
|
||
- [ ] 原有测试无回归？
|
||
- [ ] 工单完成四条件全部满足？
|
||
|
||
---
|
||
|
||
**关联**：[04-研发工单全流程规范.md](./04-研发工单全流程规范.md)、[03-文档同步规范.md](./03-文档同步规范.md)、[05-并行窗口冲突规约.md](./05-并行窗口冲突规约.md)
|