diff --git a/.dsh/roles/README.md b/.dsh/roles/README.md index a190486f..efe0ecda 100644 --- a/.dsh/roles/README.md +++ b/.dsh/roles/README.md @@ -221,6 +221,7 @@ spawn_teammate({ - 角色文件修改后**不需要重启 DSH**,下次委派时自动读取最新版本 - **在 worktree 里新增/改角色文件,persona 不会注入**(2026-11-18 实测):插件按 `spawn_teammate` 那一刻的**工作目录**向上找 `.git` 定项目根(`lib/roles.js` 的 `projectRootFor()`,标记只有 `.git`),而团队成员的角色查找用的是**主树** cwd(诊断日志 `role-inject-diag.log` 记 `role "x" not found (cwd=<主树>)` → `install FAILED`)。所以新增角色的验收顺序是:先在**主树** `.dsh/roles/` 放好文件 → 再起探针成员确认 persona 首行与工具白名单都对 → 最后才谈合并提交。反过来做(只在 worktree 建文件就 spawn)会得到一个「有角色名、无 persona、工具面全开」的成员,且失败只落 diag,调用方看不到任何报错。 - 所有 12 个角色均为双层结构(第一部分通用知识体系 + 第二部分项目专项) +- **测试驱动(TDD)纪律**:写代码/测试的角色(`algo` / `network` / `storage` / `ui` / `mcu` / `test-engineer`)铁律里都要求——**新增或修改功能先写对应的单元测试再写实现,至少同步进行,不许写完再补**;先写测试 = 先把"正确是什么"钉成可复跑判据,再由实现去满足。纯注释/命名/常量调整且不改行为者豁免。这条写在各角色文件里而非只在本文,是因为 teammate 只注入 `@role:` 对应的那个角色文件(见上方 worktree 实测),总纲不进角色文件就等于没下发。 ## `tools` 字段说明 diff --git a/.dsh/roles/algo-specialist.md b/.dsh/roles/algo-specialist.md index ad95230b..7612cc4c 100644 --- a/.dsh/roles/algo-specialist.md +++ b/.dsh/roles/algo-specialist.md @@ -131,6 +131,8 @@ onToolCallBudget: wrap-up - **动手前必须知道的一条硬事实**:`rs485.c` 是全局 HAL UART 回调的**唯一实现处**(`HAL_UARTEx_RxEventCallback` / `HAL_UART_ErrorCallback` / `HAL_UART_TxCpltCallback` 三个),其中屏板链路(USART1,`sb_link_*`)也在同一组回调里转发。在别处再定义一份 = 链接期 multiple definition。开 RS-485 消费者时只能沿用这套转发结构,不许另起一套回调。 - **权威落点**:`docs/产品需求/产品需求设计文档.md` §5.10(状态 / 重启门禁 / 三条约束 / 完成判据)、`docs/产品需求/产品需求设计文档.md` §9 的资产盘点行(17 项对下采集)、`docs/门禁说明/registration-check.md`(uvprojx 白名单缺口)、`docs/架构设计/项目启动顺序管理.md` §1.1 的 `rs485_task` 行。 +10. **测试驱动(TDD):新增/修改算法或保护判据逻辑,先写对应的主机侧单测再写实现,至少同步进行**(不许写完再补)。先写测试 = 先把"正确是什么"钉成可复跑判据,再让实现去满足它——`test/host/` 已有对应套件(`adc_input`、`protection` 等)就把用例加进去,没有则先按 `test-engineer` 约定建骨架。纯注释/命名/常量值调整且不改行为者不在此列。 + ## 工作方式 - 接到任务后,先读相关模块的现有代码和设计文档(`docs/算法/采集与算法层设计说明.md`、`App/algo/README.md`),理解当前状态再动手。 diff --git a/.dsh/roles/mcu-specialist.md b/.dsh/roles/mcu-specialist.md index 4d5238a8..8ac7e3c5 100644 --- a/.dsh/roles/mcu-specialist.md +++ b/.dsh/roles/mcu-specialist.md @@ -138,6 +138,7 @@ BSP 层回答的问题是「让硬件动起来并如实汇报状态」,不回 9. **HAL 时基是 TIM7 不是 SysTick**,`SysTick` 归 FreeRTOS;不要在 FreeRTOS 启动后改 SysTick。 10. **只 Keil MDK-ARM (ARMCC, C99)**。不要用 GCC 特性(`__attribute__` 里的 ARMCC 不认的、`typeof` 等)。 11. **任何代码修改后必须先 `/keil-build` 验证(0 错误 0 警告)**。烧录闭环用 `/serial-boot-test`。 +12. **测试驱动(TDD):新增/修改可脱离寄存器单测的纯逻辑(引脚译码、时序常量计算、位操作封装等),先写对应的主机侧单测再写实现,至少同步进行**(不许写完再补);能剥出纯逻辑的按 §3.3 先剥离再测。纯寄存器时序、CubeMX 生成或硬件回读类无法 host 复现的,先写板级验证步骤再改实现,以 `/keil-build` 0/0 与 `/serial-boot-test` 取证为准。无行为变化的注释/常量调整不在此列。 ## 本项目的引脚与器件事实 diff --git a/.dsh/roles/network-specialist.md b/.dsh/roles/network-specialist.md index 55d6062e..38d591e2 100644 --- a/.dsh/roles/network-specialist.md +++ b/.dsh/roles/network-specialist.md @@ -129,6 +129,8 @@ Wireshark/tcpdump 是必备工具。关注点:握手时序、重传率、窗 8. **自研代码禁用 C 库堆分配**:只用 `pvPortMalloc/vPortFree`。 9. **就绪屏障位必须 `osFlagsNoClear`**:`osEventFlagsWait` 默认消费所等位,`NET_READY` / `STORAGE_READY` 被先消费掉会导致后续消费者永久阻塞。 +10. **测试驱动(TDD):新增/修改 net 协议逻辑或 socket 生命周期行为,先写对应的主机侧单测再写实现,至少同步进行**(不许写完再补)。`test/host/` 已有对应套件(`net_socket`、`net_listener`、`net_pending`、`sntp`、`lftpd` 等)就把用例加进去,没有则先按 `test-engineer` 约定建骨架。fd 失效值这类"假对象域与生产域是否一致"的坑,必须先让 fake 具备复现条件再写实现;无行为变化的注释/常量调整不在此列。 + ## 工作方式 - 接到任务后,先读 `docs/网络/网络自愈架构设计.md`(读清点审计 + 新增读清的三条准入判据见该篇 `docs/网络/网络自愈架构设计.md` §4.10)和 `docs/子系统设计/网络配置说明.md`。 diff --git a/.dsh/roles/storage-specialist.md b/.dsh/roles/storage-specialist.md index bfc8199b..9f58001d 100644 --- a/.dsh/roles/storage-specialist.md +++ b/.dsh/roles/storage-specialist.md @@ -163,6 +163,8 @@ Flash Translation Layer 负责三项核心任务: 8. **自研代码禁用 C 库堆分配**:只用 `pvPortMalloc/vPortFree`。 9. **破坏性测试默认关闭**:`ENABLE_DESTRUCTIVE_TESTS` 开启后跑一轮 GD5F 即让 dhara 多记一个坏块且持久化。开此开关须用户明确指示。 +10. **测试驱动(TDD):新增/修改 FTL、FatFs 适配、日志或卷自愈逻辑,先写对应的主机侧单测再写实现,至少同步进行**(不许写完再补)。`test/host/` 已有对应套件(`fatfs`、`sys_log`、`nand_ftl` 等)就把用例加进去,没有则先按 `test-engineer` 约定建骨架;掉电/坏块类无法在 host 复现的,先写板级用例再改实现。无行为变化的注释/常量调整不在此列。 + ## 工作方式 - 接到任务后,先读 `docs/架构设计/STM32F4-Base存储架构说明.md`(含 §10.1 FatFs 标志位编号表与两条陷阱详解)。 diff --git a/.dsh/roles/test-engineer.md b/.dsh/roles/test-engineer.md index f4e2e2d4..09e62df3 100644 --- a/.dsh/roles/test-engineer.md +++ b/.dsh/roles/test-engineer.md @@ -124,6 +124,7 @@ ASIL-D要求故障注入测试验证安全机制有效性;软件单元之间 6. **字符串字面量必须纯 ASCII**:中文只写注释。 7. **自研代码禁用 C 库堆分配**:测试代码同样适用此规则(模拟器宿主 CRT 堆正常不代表板端安全)。 8. **测试命名用语义短语**:不用字母+数字编号(如 TC-XXX-07),直接用描述性名称。 +9. **测试驱动(TDD)的守门人**:你是其他角色 TDD 纪律的落点——模块专家来加功能时,先与他确认对应用例已写(或同步写),再谈实现验收。**先写测试再实现是本仓铁律**:判据先立,实现才能被证明正确。你自己写测试工具/生成器时同样先写自测(如 `check_*.py --selftest` 的变异断言),确保门禁本身能抓到它要抓的缺陷。 ## 工作方式 diff --git a/.dsh/roles/ui-specialist.md b/.dsh/roles/ui-specialist.md index bbec3df4..245079d3 100644 --- a/.dsh/roles/ui-specialist.md +++ b/.dsh/roles/ui-specialist.md @@ -140,6 +140,8 @@ LVGL Pro CLI 提供完整的 headless 测试链:`lvglpro generate` → `lvglpr 8. **UI 改动回归按第三部分 ui-verify 手册跑 5 步门禁**(模拟器构建、菜单像素回归、内容页黄金参考、Keil 构建、代码规范)。 9. **注释里写作用域别写星号形态**:`Drivers/BSP/UI/**` 里的 `/*` 会被 ARMCC 当第二次注释起点。写全目录或用尖括号 ``。 +10. **测试驱动(TDD):新增/修改菜单树、页面行为或 UI 数据供给逻辑,先写对应回归用例再写实现,至少同步进行**(不许写完再补)。页面/像素变化先登记黄金参考(按第三部分 `ui-verify` 手册),纯逻辑先加 `test/host/` 对应用例;先钉住"正确长什么样/输出什么"再实现。无行为变化的注释/配色常量微调解耦于此列。 + ## 工作方式 - 接到任务后,先读 `docs/UI设计/UI_设计架构.md` 和 `docs/UI设计/LVGL模拟器部署与使用说明.md`。 diff --git a/docs/任务规划/待处理疑问.md b/docs/任务规划/待处理疑问.md index 0467bebc..f7ff78cb 100644 --- a/docs/任务规划/待处理疑问.md +++ b/docs/任务规划/待处理疑问.md @@ -1,7 +1,5 @@ * IEC104 协议,增加了很多 netsocket 函数,这些函数是必须要有的嘛?是通用的网络函数嘛?这些函数不能通过已经有的 netsocket 中的函数得到嘛?增加的函数别的地方也调用嘛?如果别的地方不用,为什么非要单独增加到公共的网络协议栈中呢? -* 对任务分工角色,增加 测试驱动的编程思想,要是增加内容,先写对应的单元测试代码,然后再实现。或者同时进行。 - * 单元测试文件,我见增加了假netsocket,我们有好多网络测试,能不能统一出来大家共用的假网络测试底层,而不是每个模型创建各自的。 * 为了提交代码,IEC 进入了代码规划豁免,仔细查看豁免的内容,能不豁免的就不要豁免