wandering1
3965eb3f28
把 AGENTS 铁律第 2 条从"人工逐文件比 HEAD"变成提交硬闸：HEAD 有 EF BB BF 而工作区没有 → FAIL。 2026-10-25 一天之内道E 在 task-15 里连踩 4 次、道B 批 1 踩过 1 次，此前全靠人记得做审计兜底—— 人工审计只防得住记得做的人，这正是它该变成门禁的理由（票 = task-20）。 scripts/check_bom_drift.py（纯标准库） - 判定只有一条：HEAD 前 3 字节是 BOM 而工作区不是 → 列出文件与补救动作，不含二义措辞。 - 两条刻意不报（票面要求的边界，--selftest 逐条自证）：① HEAD 里根本没有的新文件无 BOM 不误报； ② HEAD 无 BOM 而工作区加了 BOM 也不报——那是另一个方向的改动，可能是有意的（把文件纳入名单）， 报红只会逼人 --no-verify，而"养成绕门禁的习惯"比漏检一次贵得多。 - 一条刻意不做：不自动补 BOM。正确修复是在文件最前面加 3 个字节；脚本整文件重写会按系统默认编码 重打中文，把可修的丢 BOM 变成不可修的 U+FFFD（AGENTS 铁律第 1 条那条更大的坑）。补救文案里把 这句完整写出来了——报错信息的作用是让踩的人当场做对动作，不是让他知道有人不高兴。 - 名单三处互指：AGENTS 铁律名单 / 本钩子 files 正则 / 脚本内 BOM_LIST，每次运行核一次；单独改任何 一处都会在别人的提交里被拦下。名单散在三处而无人同步，等于没有名单。 - --selftest 在临时 git 仓库里跑 4 条判定（含上述两条边界 + 主用例 + 名单外文件不参与），全过。 setview-check（Lead 指令：并入 task-20 同窗机械化） - 核 Drivers/BSP/UI/ui_w_setview.c 的四张视图表与 App/algo/prot_set 枚举序、 g_prot_set_meta 上下限是否同一份口径：id 恰好覆盖 0..39 各一次 / 数值行 min-max 等于 meta 换算 / kind 与 is_ctl 一致 / 单位纯 ASCII / 小数位查表与行表一致。机械化的理由不是"多一道保险"：BSP 侧看不到 App 头， 行表里的 id 是裸数字 + 行尾注名，这条对齐在编译期**物理上无法自证**；而页面上只有当前可见 的 8 行会被像素断言看到，错位要翻到第 2、3 页才可能被人发现——那时它已被黄金参考钉死了。 - 跨分支先后写成注释：脚本文件随 task-15 分支合入主干；在此之前 files 永不命中 → 钩子自然 skip （skip 不是失败），合并后自动生效，不需要任何人再动这条配置。 AGENTS.md（票面授权：只加一句机械化标注；下面实际动了两处计数，一并申报） - 铁律第 2 条末尾加"已机械化：bom-guard 钩子"+ 三处互指一句。 - 钩子计数 46 → 48 两处同步（不同步就是让 AGENTS 说谎）；并在文档索引行标出"bom-guard / setview-check 两篇待补"，把欠的详解篇目挂在明面上，不留沉默债。 验证 - 本笔**未用 --no-verify**：全量 pre-commit --all-files 46 项 Passed、0 Failed（含两条新钩子）。 - 端到端实测（不止 --selftest 自证）：真把 Drivers/BSP/UI/ui_w_records.c 的 BOM 剥掉并 stage → bom-guard rc=1 并打印补救动作；还原后该文件与 HEAD 逐字节相同，工作树干净。 - 顺带发现并行开发方案的一条空白（本笔未修，写域之外）：全新工作树没有 .map，mem-numbers 会因 "找不到 .map 真实源" FAIL，跑一次 @build 才绿。门禁隐含的"本树必须先构建过"前提在 docs/环境与部署/并行任务工作树方案.md 里没写；已回报 Lead 定夺归属。 - 自报一条：本笔第一次提交被 gitlint 拦下——正文有一行 92 > 80，**我量出来了却仍然按了提交**。 记在这里是给下一篇门禁详解留素材：这条门禁拦下过的人里也包括写门禁的人自己，而「拦下过 什么真事」那一栏不该只挑别人的事写。
188 lines
32 KiB
Markdown
188 lines
32 KiB
Markdown
# STM32F4-Base
|
||
|
||
**工业级嵌入式 DTU 平台固件**：STM32F407ZGTx @168MHz，集成以太网（CH395F）、SPI NAND 存储（GD5F）、电气量采集（TPAFE5160 + 片内 ADC）、RS-485、FTP 文件服务，自带远程显示（UI 推流）、墙钟对时、看门狗自恢复、运行/自检记录——既是可独立部署的现场设备，也是**可复用的平台底座**（保护测控等后续产品在此底座上补齐）。产品基线 → `docs/产品需求/产品需求设计文档.md` §2.1。
|
||
|
||
**仅 Keil MDK-ARM v5 (ARMCC, C99) 工具链**；FreeRTOS V10.3.1 / CMSIS-RTOS2；192KB SRAM / 1MB Flash。
|
||
|
||
**任何代码修改后必须先 `@build` 验证（0 错误 0 警告）再提交；硬件闭环用 `@test`。**
|
||
|
||
> 本文件 = agent 入口：宏观概况 + 每次都在场的铁律在这里，细节在 `docs/` 与 skills（文末索引）。同一事实只在一处详述（`docs/文档规范.md` 同此要求）。
|
||
|
||
## 项目概况
|
||
|
||
**现状一句话**：平台能力（网络 / 存储 / 时间 / UI / 日志 / 看门狗 / FTP / 配置）**已实现并台架验收**；采集主线已闭环到业务消费者（L1→L2 相量→L3 保护判据 protectTask→104 遥信，B5）；**RS-485 采集尚未接线**（B2 按用户决策冻结，见 `docs/任务规划/暂缓-RS485.md`）——当前最大功能缺口，接线节奏受 E-59 门禁约束（见「平台约束」）。
|
||
|
||
**数据主线**（能力视角；分层图与跨层依赖表 → `docs/架构设计/项目架构总览.md`）：
|
||
|
||
- **采集**：TPAFE5160（计量级 8 路，并行总线）+ 片内 ADC1（9 路，DMA）→ TIM3 1 kHz 节拍 + 原子快照 → adcTask → L1 有效性校验 → L2 相量 → L3 保护（protectTask 20 ms 判据节拍，B5）→ 104 遥信上送
|
||
- **存储**：GD5F SPI NAND → dhara FTL → FatFs → `/log` 运行与自检记录、`/config.ini` 配置、FTP 根目录
|
||
- **网络**：CH395F → netTask 串行 socket 栈 → FTP(21) / 对时(8888) / RemoDispBus 远程显示(7003) / IEC 60870-5-104 上行(2404)
|
||
- **人机**：LVGL 160×160 单色菜单（uiTask），**与 PC 模拟器同一份 UI 源码**，远端可看图 + 注键
|
||
|
||
**目录地图**（只列顶层——稳定边界；细结构自己 `ls`，别背路径）：
|
||
|
||
| 目录 | 职责 | 可改性 |
|
||
|---|---|---|
|
||
| `Src/` `Inc/` | CubeMX 生成（外设初始化 / 中断向量 / `freertos.c` 任务表） | **只写 `USER CODE` 区** |
|
||
| `App/` | 应用层：`app/` 启动与就绪事件 · `task/` 任务编排 · `algo/` 采集与算法 L1~L3 · `cfg/` 配置引擎 · `log/` 日志 · `fs/` 卷锁 · `sync/` 对时 · `util/` 工具 | 手写 |
|
||
| `Drivers/BSP/` | 手写芯片驱动与服务：`TPAFE5160` `CH395F` `NET`(socket 栈+lftpd) `NETCFG` `GD5F2GQ5UE` `SD2506` `RS485` `UI`(LVGL 界面) | 手写 |
|
||
| `Drivers/STM32F4xx_HAL_Driver/` `Drivers/CMSIS/` `Middlewares/` | ST HAL / CMSIS / FreeRTOS | 第三方，只读 |
|
||
| `Lib/` | 第三方库：`lvgl` `FatFs` `dhara` + `lv_conf.h`（MCU 端） | 只读（本地补丁须有文档登记，如 LVGL I1 补丁） |
|
||
| `MDK-ARM/` | Keil 工程（`.uvprojx`、scatter、下载脚本） | 工程配置手改；UV4 抖动不入库 |
|
||
| `simulator/` | LVGL PC 模拟器（CMake + SDL2），与固件同标准受检 | 手写 → **`lvgl-simulator` skill** |
|
||
| `test/` | `board/` 板级套件 · `host/` 主机侧单测（提交门禁实跑） | 手写 |
|
||
| `scripts/` `tools/` | 门禁与报告脚本（`check_*` / `gen_*` / `ci_local.py`）· 配图/字体/引用图生成器 | 手写 |
|
||
| `docs/` | 全量设计 / 测试 / 规范文档（人类索引 `docs/README.md`） | 手写，`doc-links` 门禁 |
|
||
| `.dsh/skills/` `.gitea/` `.serialtest/` | agent skills（子域知识入口）· CI 工作流 · 串口/烧录配置 | 手写 |
|
||
|
||
**分层边界**：上层只依赖相邻下层（业务 → UI/基础服务 → 中间件 → BSP 驱动 → HAL/RTOS → 硬件，**单向**）；新算法模块进 `App/algo/`，勿塞 `App/task/`（任务只做消费/编排）；新 `.c` 必须双端注册（**`new-source-file` skill**）。
|
||
|
||
## 架构要点
|
||
|
||
`Src/main.c`（CubeMX 初始化）→ `app_main_init` → `osKernelStart` → 9 任务（`osKernelStart` 之前全是内核启动前代码：禁调任何内核 API，见「平台约束」）
|
||
|
||
- `app_main_init`（时间子系统优先，使后续日志带时间戳）：`sd2506_init` → `sys_clock_init` → `rs485_init` → `gd5f2gq5ue_init` → `tpafe5160_init` → `adc_input_init`（L1 采集层）→ SD2506 诊断 → **启动 TIM3 1 kHz 采样节拍**
|
||
- **就绪屏障**（`App/app/sys_events.h` Event Flags，取代魔法延时）：`SYS_EVT_NET_READY` / `STORAGE_READY` / `FTP_READY` / `TIMESYNC_READY`；消费者用 `osEventFlagsWait` 阻塞等待（就绪位 `osFlagsNoClear`）
|
||
- netTask：`net_stack_bring_up`（配置已由 defaultTask 在屏障前加载，本任务只读 RAM 副本）→ 置 NET_READY → 循环 `net_poll` + `net_process_messages`；消费 `SYS_EVT_NET_RECONFIG` → 按网络代次号重建监听（新 IP 免重启生效）
|
||
- defaultTask：`f_mount` forced（无卷自动 `f_mkfs`；挂载后卷健康探针，FAT 区陈旧时自愈重格式化）→ 加载网络配置 → STORAGE_READY → LED 闪烁；同时是 syslog（`/log/run.log`·`selftest.log`，定长 64B 记录）的**唯一写者**与**配置引擎属主**（netTask/uiTask 不得直接触碰配置引擎）
|
||
- adcTask：**纯消费者**——每拍 `adc_input_poll()`（TPAFE 原子快照 + 消费一帧 STM32 ADC1 DMA 双缓冲），只取数不做保护运算；**节拍与唤醒同源**（TIM3 ISR 内触发 CONVST + 同一更新事件经 TRGO 触发 ADC1，并调 `adc_tick_irq_notify()` 置位，任务 `osThreadFlagsWait` 等唤醒）。⚠ ISR 侧**只能**走 `adc_tick_irq_notify()`（内含"消费者就绪"门，TIM3 比调度器早 ≈100 ms 启动）；手写于 `Src/freertos.c` 的 `USER CODE` 区，纳入 IWDG `required_mask`（`TASK_WD_ADC`）
|
||
- **采集与算法层（L1/L2/L3）落在 `App/algo/`**：`adc_input`/`adc_health` = L1，`sample_ring`/`phasor` = L2，`freq` = L2.5 测频（B8，自适应窗），`prot_set`/`prot_elm` = L3。板端消费者 = **protectTask**（B5，2026-10-12）：20 ms 节拍 `prot_elm_run()` + L5-4 采样故障闭锁 + L5-1 定值校验和巡检；跨上下文复归（104 YK11）经 `prot_elm_request_reset()` 落请求。纳入 IWDG `required_mask`（`TASK_WD_PROTECT`，产品 `0x1F7`）。→ `docs/算法/采集与算法层设计说明.md`（设计与判据）、`App/algo/README.md`（目录索引）
|
||
- 全景 → `docs/架构设计/项目架构总览.md`；启动时序与内核前模式 → `docs/架构设计/项目启动顺序管理.md`
|
||
|
||
<!-- TASK_TABLE:BEGIN generated by scripts/gen_task_table.py -->
|
||
| Task | 栈 (words) | 优先级 |
|
||
|---|---|---|
|
||
| defaultTask | 1280 | Normal |
|
||
| netTask | 960 | Normal |
|
||
| ftpTask | 1024 | Normal |
|
||
| testTask | 2048 | BelowNormal |
|
||
| uiTask | 4096 | BelowNormal |
|
||
| timeSyncTask | 640 | Normal |
|
||
| adcTask | 640 | AboveNormal |
|
||
| iec104Task | 640 | Normal |
|
||
| protectTask | 512 | Normal |
|
||
<!-- TASK_TABLE:END -->
|
||
|
||
（实际值以 `Src/freertos.c` 为准，本表由 `scripts/gen_task_table.py` 生成、`task-table` 钩子校验；testTask 仅在启用测试套件时创建。FreeRTOS 堆已迁 CCM，任务栈不占 SRAM；**每次抬栈的实测最坏链与余量台账** → `docs/内存管理/RAM使用分析与优化方案.md` §2.3（任务栈配置与实测峰值）与 §4.0.6（静态最坏链与判定）、`docs/内存管理/内存内容分配策略.md` §6（容量台账））
|
||
|
||
## 铁律：源码编辑与编码
|
||
|
||
- 改代码**只用 Edit 工具**（精确子串替换 / replaceAll）；**绝不用 `Get-Content`/`Set-Content`/`cmd` 重写含中文的文件**——整文件重写按系统默认编码重解码 → `U+FFFD` 乱码且不可逆
|
||
- **Edit 会静默剥掉文件原有的 UTF-8 BOM**：带 BOM 的文件（`Drivers/BSP/UI/*`、`App/task/ui_task.c`、`App/cfg/cfg_file.c`、`Lib/lv_conf.h`）被 Edit 后丢 BOM → ARMCC 改按 CP936 解码 → 中文字面量报 `#870-D: invalid multibyte character sequence`（**只有重编译该文件才暴露，历史"0 警告"不代表安全**）。改完须核对 BOM 并按原样补回（只前缀 3 字节 `EF BB BF`，勿整文件重写）。**已机械化：`bom-guard` 钩子**（`scripts/check_bom_drift.py`：HEAD 有 BOM 而工作区没有即拦；上面这份名单与钩子 `files` 正则、脚本内 `BOM_LIST` **三处互指**，脚本每次跑都核一次，单独改一处会在别人的提交里被拦下）
|
||
- **字符串字面量必须纯 ASCII**：无 BOM 文件里奇数个汉字会吞掉结束引号（偶数侥幸通过）→ 中文只写注释
|
||
- 怀疑乱码先统计 `EF BF BD` 字节数（勿信终端/Read 渲染）；**不要急著 `git checkout`**（会丢弃全部未提交工作）——用 Edit 只修坏行
|
||
- 行尾由 `.gitattributes` 写死（`* text=auto eol=lf`；`*.bat`/`*.cmd` 强制 CRLF）：**不依赖 `core.autocrlf`、不要把工作区文件改回 CRLF** → 权威口径 `docs/文档规范.md` §2
|
||
- 代码规范 V1.0：小写下划线命名（`g_`/`s_`/`p_`/`a_` 前缀）、头文件保护宏 `XXX_H`（禁 `__` 前缀）、常量在右、文件头模块注释块 → `docs/代码规范/`
|
||
|
||
## 构建与验证
|
||
|
||
- **门禁时机（用户裁定 2026-10-13）**：`@build` / `scripts/ci_local.py` / `check_doc_links.py` **只在准备提交时跑**（用户让 commit 后统一跑一遍），**不是每次中间改动后都跑**——多步改动期间直接改即可，验证集中在提交门禁；`@test` 硬件闭环仍按任务需要跑
|
||
- `@build` = `& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py`（仓库根执行）。退出码 **0=PASS / 1=构建失败 / 2=环境错误（UV4/工程/档案）/ 3=用法 / 4=build 锁被占用**；日志 `MDK-ARM/build_log.txt`；换机必设 `DTU_KEIL_UV4` → 细节 **`keil-build` skill** + `docs/环境与部署/本地工具路径环境变量方案.md`
|
||
- `@test` = `& '.venv\Scripts\python.exe' .dsh\skills\serial-boot-test\scripts\run_boot_test.py`：开串口+清日志 → 烧录（**固件身份戳**保证烧进去的就是这份构建、**回读校验**）→ wait-idle → 采日志 → 标记校验（含启动锚点计数）。退出码 **0=PASS / 1=FAIL / 2=采集或烧录错误 / 3=用法**；戳提取规则、锚点计数判据与按模块定制标记见 `docs/测试说明/自动化测试流程.md`
|
||
- Forbidden 标记含 `[ERR]`：**四个 Fault 的崩溃日志都以 `[ERR]` 开头 → 出现 Fault 即本次不通过**（刻意）
|
||
- **烧录必须 `-Rst -Run`**（`stlink-flash` skill 的 `flash`）：裸 `-P` 会报 `Programming Complete`，但目标核处于死循环/异常时写入并不落地（"反复重下载、芯片一直是旧镜像、二分法失效"的根因）。**烧后必须回读校验**（`stlink_flash.py cmp` = `-CmpFile`，`No difference found` 才算真正写入）；⚠ `-CmpFile` 连接时会**复位目标** → 必须排在**采日志之后** → `docs/测试说明/ST-LINK_CLI_复位使用说明.md`
|
||
- ⚠️ 旧绝对路径 `D:\Code\DTU 程序\...` 出现即失效（仓库已搬迁），一律改用仓库相对路径
|
||
|
||
## Python 环境
|
||
|
||
- 统一入口 `& '.venv\Scripts\python.exe'`（3.12，fontTools/Pillow 已装）；PATH 上的 `python` 是 msys64 的，**不要用它**跑依赖第三方库的脚本；纯标准库脚本任意 python3 均可
|
||
- 重建/换机：`<本机任一 python ≥3.10> -m venv .venv` + `pip install -r requirements.txt`（含 `pre-commit`；`DTU_PRECOMMIT_PYTHON` 可指向别的装了 pre-commit 的解释器）；`requirements.txt` 必须**纯 ASCII**（Windows 下 pip 按 GBK 代码页解码）
|
||
|
||
## 提交门禁（pre-commit）
|
||
|
||
- 任一失败即拦截，共 **48 个钩子**（新增 `bom-guard` / `setview-check` 两条，2026-10-25 道E task-20，详解篇目待补；**每种门禁一篇详解（查什么 / 拦下过什么真事 / 限制与盲区 / 基线口径）→ `docs/门禁说明/README.md` 索引**；通用机制与整体口径 → `docs/代码规范/pre-commit使用说明.md`）：通用 5 + `gitlint` + `cppcheck` / `test-cppcheck` + `no-mojibake` + `coding-standard` + 文档三件套 `doc-links` / `task-table` / `mem-numbers` + `id-check`（**编号门禁**，`docs/编号规范.md` §8 八项校验；**已关闸为【增量拦截】**：只拦 `scripts/id_known_backlog.json` 台账之外的新错误级问题，存量按指纹豁免、台账只减不增；另有一根恒生效的线——可判定比例跌破 `id_registry.json` 基线即失败）+ `lv-conf-sync`（两份 `lv_conf.h` 特性子集一致）+ `cubemx-survival` + 主机侧单测 22 个（`-unit-test` 后缀，2026-10-25 增补 adc-cal / prot-dim / vol-idle-sync / ui-data / meas / run-par 六个）+ `test-coverage`（**覆盖率总闸**：跑全部 39 套并守基线回退；缺 mscoverage 组件时按用户裁定 **FAIL**、不 skip，2026-10-24）+ `test-suite-switch` + `registration-check`（双端注册反向校验 + UI 页面描述符表接线，N-23/U4）+ `mem-budget`（RAM 92% 预算门禁，N-27）+ `font-charset`（UI 字符集差集检查，防缺字白框，U4）+ `ui-golden`（UI 像素回归，菜单 8 状态 + 内容页 11 页黄金参考，U4）+ `layer-deps`（**分层方向**：`Drivers/BSP/**` 不得 include `App/**` 的头；存量 3 条基线只减不增（2026-10-25 记录 reader 注入削掉 UI 记录 3 条边，6→3），报告 S-1）+ `bsp-err`（**BSP 错误码与超时命名约定**：公开 API 不得拿 `HAL_StatusTypeDef`/`bool` 当错误通道、`*_TIMEOUT` 宏不得取负值、非 void 须写「返回值：」、**返回错误码的函数不得裸丢弃返回值**（须接住或显式 `(void)`；实测编译器与 cppcheck 都不报这类，只有这条会响）；约定正文 `Drivers/BSP/bsp_err.h`，存量基线只减不增（2026-10-23 首清点 19 条 → 已还 18；`consume-result` 上线又暴露 37 条存量丢弃 → **现 38 条**），报告 S-5）
|
||
- **范围 = 项目代码**：第三方（`Lib/`、`Middlewares/`、CMSIS、HAL、`lftpd`、`dhara`、`MDK-ARM`）排除；`cppcheck`/`coding-standard` 另排除 `test/`，规范检查再排除 CubeMX 生成的 `Src/`/`Inc/`。**`simulator/` 已纳入全部钩子**（2026-10-11）——生成物只靠 `.gitignore` 挡，**不在 `exclude` 里写目录名**（教训见 `docs/代码规范/pre-commit使用说明.md` §5.5）
|
||
- ⚠ **pre-commit 4.x 已移除 `always: true`**（实测对 `local` 钩子只告警 `Unexpected key(s)` 并跳过）→ 想"总是跑"的钩子**必须让 `files:` 覆盖到所有会触发它的文件**，没有兜底开关
|
||
- **改写型钩子（`trailing-whitespace` + `end-of-file-fixer`）豁免 CubeMX/Keil 生成文件**（配置里 YAML 锚点 `&cubemx-generated`）；⚠ **只读检查不受影响**：`cppcheck` / 乱码 / `cubemx-survival` / `task-table` / `mem-numbers` 仍覆盖 `Src/`、`Inc/`
|
||
- 提交信息：标题 ≤100 字符、**正文每行 ≤80**（`.gitlint` + gitlint 默认）→ 长说明一律用**短标题 + `git commit -F <UTF-8 无 BOM 文件>` 多行正文**（中文长标题极易超限，且 `-m` 会被终端代码页转码破坏）
|
||
- **CI**（`.gitea/workflows/ci.yml`）只跑 L0 静态门禁 + L0.5 主机侧单测，**刻意不跑 `@build`**（需 Keil 授权）、不含 L1/L2/L3（需真机）。**远程 CI 的全部资料（服务端开关 / runner 部署与保活 / workflow / 排障 / 实测坑）集中在 [`docs/CI/README.md`](docs/CI/README.md)，不放本节**——它**只跑在本机一台 runner `win-stm32-ci` 上**，其他机器与项目都不涉及。日常改代码的等价自查是 `& '.venv\Scripts\python.exe' scripts/ci_local.py`（L0 + L0b + L0.5）——**runner 不在线也不影响本地门禁，不能因"已配 CI"放宽本地要求**
|
||
|
||
## 平台约束
|
||
|
||
**CubeMX 与 Fault**
|
||
|
||
- `Inc/`/`Src/` 是 CubeMX 生成文件（带 `USER CODE BEGIN/END` 标记）：自定义代码**只写标记区之间**；`Drivers/BSP/` 为纯手工代码
|
||
- **重生成会覆盖标记区之外的一切**（`.ioc` 的 `KeepUserCode=true` **只**保护 USER CODE 区；实测两次重生成各覆盖 4~5 处定制，其中两处**不报编译错**、只在真出故障时暴露）。防丢失按三层优先级 **L1 写进 `.ioc` → L2 搬进 USER CODE 区 → L3 审计兜底**；**每次重生成后立刻跑 `python scripts/check_cubemx_survival.py`**（已挂 `cubemx-survival` 钩子）。方法论与全部实测坑（自造标记区会被模板换代抹掉、宏改名 `#define f f_Gen` 让位、FreeRTOS 钩子必须写进 `USER CODE BEGIN 4/5` 区…）→ `docs/子系统设计/看门狗设计说明.md` §10
|
||
- **ARMCC `__asm` 只有一种合法形态**：整函数 `__asm void f(void) { ... }`；GCC 内联语法报 `#18`、块内联把寄存器名当 C 标识符报 `#20`、**取不到 C 的数据符号**（`A1516E: Bad symbol`）→ 三条坑与可用写法 `docs/子系统设计/看门狗设计说明.md` §10.4
|
||
- **4 个 Cortex-M4 Fault 全部采集现场**（手工 `__asm` Handler 取 MSP/PSP → `B` 到 per-fault C 入口 `fault_entry_{hard,mem,bus,usage}` → `hard_fault_report` 打 `[ERR] <TAG> …` 后 `NVIC_SystemReset()`）；**MemManage/BusFault/UsageFault 默认禁用**，不使能就被升级成 HardFault、日志看不出根因 → `fault_handler_enable()` 必须在 `app_main_init()` **第一行**；**`SHCSR` 的使能位无法在 CubeMX 配置**（模板只生成优先级）→ 看门狗设计说明 §10
|
||
|
||
**RTOS 与内存**
|
||
|
||
- **`osKernelStart` 之前禁止任何 FreeRTOS/CMSIS-RTOS 创建类 API**（`osMessageQueueNew` 等会杀死启动，2026-09-20 实证根因）→ 内核前标准模式（纯寄存器/HAL 轮询 + **无锁静态缓冲** + 内核启动后**惰性创建**真队列）见 `docs/架构设计/项目启动顺序管理.md`
|
||
- **就绪屏障位必须 `osFlagsNoClear`**：`osEventFlagsWait` **默认消费**所等位，就绪位被先消费掉 → `ftpTask` 的 `WaitAll` 永不成立 → **FTP 21 端口静默不监听**（无日志无报错）。命令位（`SYS_EVT_CFG_SAVE`/`NET_RECONFIG`）保持消费型
|
||
- **自研代码禁用 C 库堆分配**（`malloc/calloc/realloc/strdup/free`）：**2026-10-23 起由提交门禁机器拦截**（`coding-standard` 的 CODE-RULE-20，唯一豁免 = 平台分配后端的宿主侧实现，见 `docs/门禁说明/coding-standard.md` §7）：MicroLIB 的 C 堆由 `startup_stm32f407xx.s` 的 `Heap_Size EQU 0x200` 限定为 **512 B**，KB 级分配必然返回 NULL，而**模拟器（宿主 CRT 堆）完全正常、照不出来** → 只用 `pvPortMalloc/vPortFree`，或把分配收进平台后端 → `docs/内存管理/RAM使用分析与优化方案.md`
|
||
- **内存预算紧张**：新增任何任务/缓冲/栈前先核算 RAM 余量；改栈或加大局部变量**前后各跑一次** `scripts/stack_report.py`（静态最坏链 + 串口 `[STACK]` 水位）与 `scripts/ram_report.py`（.map 静态占用）；**总量红线已机械化**：`mem-budget` 钩子拦 RW_IRAM1/RW_CCM >92%，子系统配额 / CCM 台账 / 趋势见 `docs/内存管理/RAM预算台账.md`（**每次 `@build` 后跑 `scripts/ram_baseline.py --update`**）→ `docs/内存管理/`
|
||
- FreeRTOS V10.3.1（CMSIS-RTOS V2）；HAL 时基 = **TIM7**（非 SysTick），tick = 1ms；NVIC 4 位优先级分组，**外设中断优先级 ≥ 5**
|
||
|
||
**采集链（ADC / RS-485）**
|
||
|
||
- **ADC 取数只用 `tpafe5160_snapshot()`（临界区原子快照）**：旧的 `get_buf()`/`data_ready()`/`clear_ready()` 已从驱动**删除**（两步之间被抢占会拷回两帧混合数据；`s_ready` 三写者竞态）。消费者侧一律经 `adc_input_poll()` / `adc_input_raw()` **按语义**取数（不写死下标）→ `docs/子系统设计/ADC采样节拍设计说明.md`、`App/algo/README.md`
|
||
- **F4 上 ADC1 的硬件触发源与 DMA 流是硬约束**：① ADC1 的外部触发清单**没有 TIM6/TIM7 TRGO**（F4 上它们只接 DAC）→ 同时驱动两片转换器必须用 **TIM3**（PSC 83 / ARR 999 → 1 kHz + TRGO_UPDATE）；② ADC1 在 DMA2 **只挂 Stream0 或 Stream4** → 选 **Stream4** 才不挤走 SPI1/USART1 RX，且**换流会被重置为优先级 0**（违反"外设中断 ≥5"）→ 改流后必须回 NVIC 核对 `Src/dma.c`；③ `DMAContinuousRequests` **必须 ENABLE**（关掉 = 一轮 9 通道只发一次请求，静默丢 8 路）；④ DMA 目的缓冲必须在 SRAM（DMA2 不可达 CCM）→ `docs/硬件平台/ADC通道映射说明.md`
|
||
- **STM32F4 ADC 上电必须自校准**：CubeMX **不生成**这一步，本仓裁剪版 HAL 没有 `HAL_ADCEx_Calibration_Start`、裁剪版 CMSIS 头没有 `ADC_CR2_CAL` → 按 RM0090 §13.3.6 手写 `adc1_calibrate()`（`Src/adc.c` 的 `USER CODE BEGIN 1` 区）+ `MX_ADC1_Init()` 末尾调用；缺它**不报任何错**，只是读数带失调
|
||
- **接 ADC / RS-485 消费者前的强制门禁（E-59）**：先确认驱动契约已修（TPAFE E-44/E-45/E-58 ✅；RS485 E-36/E-37 ✅ 但 **E-50 单缓冲包撕裂、E-49 TX 超时拉 DE 未修 ❌** → `rs485_task` 仍被挡）+ 建任务前后各跑一次 `stack_report.py`
|
||
|
||
**存储与网络外设**
|
||
|
||
- **FatFs（`Lib/FatFs` 移植版）两条台架实证陷阱**：① 追加写必须 `FA_WRITE|FA_OPEN_APPEND`——该移植 `FA_OPEN_APPEND` **不含 `FA_WRITE`**，不带写位打开的文件 `f_write` 恒返 `FR_DENIED`；且 `f_write` 簇分配失败时返回 `FR_OK`+短写（无错误码）→ **判失败必须校验写回字节数**。② `FF_USE_LFN=0` → **只支持严格 8.3 短名**（不得以点开头），`.fschk` 恒返 `FR_INVALID_NAME`；自愈类逻辑**严禁**把名字/参数类错误码归入卷损坏触发集 → 完整口径与标志位编号表 `docs/架构设计/STM32F4-Base存储架构说明.md` §10.1
|
||
- **CH395F SPI：每次事务须 `ch395f_spi_begin()/end()` 包裹；分频系数必须为 8**（PCB 约束，勿"优化"）
|
||
|
||
**日志与工具链**
|
||
|
||
- **`DBG_*` 每条日志约 90 B Flash + 216 B 栈**（每个调用点内联行缓冲 + 时间戳缓冲）→ 日志不是免费的，已覆盖的步骤别加重复锚点，只在原先静默返回的黑洞处补；**深调用链模块在 `#include "dbg_log.h"` 之前 `#define DBG_LINE_BUF_MAX 128U`**（取值必须 ≥ 该模块最长日志行，否则该行被截断）
|
||
- **`MDK-ARM/*.uvprojx` 每次 `@build` 后被 UV4 自动改写，改动一律不入库**（XML 归一化 + `PackID` 降到本机 DFP 版本）；判据与例外（真的增删源文件才提交）→ **`keil-build` skill**
|
||
|
||
## 硬件引脚
|
||
|
||
- **完整引脚表（含 SD2506 I2C1、SWD、调试口）→ `docs/产品需求/产品需求设计文档.md` §4.2**（权威，V0.1 口径；勿在本文重复抄表）
|
||
- ⚠ **网名 `AINn` ≠ 板级 `ADCn` ≠ 转换器通道号**（17 路里 13 路置换）→ 取数**必须查** `docs/硬件平台/ADC通道映射说明.md`（TPAFE `buf[2]=IA`/`buf[5]=UN`/`buf[6]=UA`；网名 ADC17=PC4 用 `ADC_CHANNEL_14`，**不是** `ADC_CHANNEL_12`）
|
||
- ⚠ **8 路电气量被分给两片转换器是 V0.1 硬件缺陷，不是有意分配**（跨转换器无共同采样触发 → 无同一时刻性、相位不确定）→ V0.1 上**禁止**跨转换器做相位/功率/功率因数/矢量运算；**V0.2 须把 8 路全接 TPAFE**（登记簿 N-18）
|
||
|
||
## 模块约定
|
||
|
||
- **CH395F 单连接 socket**：监听与数据通道复用同一 Socket（CONNECT 后转数据通道，DISCONNECT/TIMEOUT 后重开 → LISTEN）；所有 CH395F 中断在 `net_poll()` 内经 `GET_GLOB_INT_STATUS` 集中读取并清除，**不得**在 ISR 或其他地方单独处理。⚠ 全局寄存器**整体读即清、芯片无按位清除手段**，而 net_poll 只在全局位为 1 时才读该 Socket 的 SINT → "顺手全量清一遍"等于把别的在用 Socket 的门焊死（B3 实证）。**现存读清点全量审计 + 新增一处读清的三条准入判据 → `docs/网络/网络自愈架构设计.md` §4.10**
|
||
- 所有 `net_*` socket 操作经 `netMsgQueue` 在 netTask 串行执行；非 netTask 任务直接调 `net_*` API，勿直接碰 CH395F 驱动
|
||
- **`net_*` 公开 API 的错误码经"任务通知值"回传**：`net_msg_t` 是**按值拷入队列**的，netTask 改的是自己那份副本，调用方永远看不到 → 错误码搭 `xTaskNotify()` 通知值回来。**勿给 `net_msg_t` 加"回传用"字段**（调用方只会读到栈垃圾）
|
||
- **单连接 socket 的断开语义**：EOF 时 net 层已 `auto_relisten`，应用层**不得**在 EOF 时 `net_close` 该 fd（会连监听一起毁掉 → 端口"连接被拒"）；仅当数据 fd ≠ 监听 fd（模拟器多连接后端）时才关
|
||
- 网口配置：`/config.ini` [network] 段（工厂默认 192.168.1.100/24、gw .1；MAC 全零 = 芯片内置；UI 保存立即生效；**旧档 `/cfg/netcfg.bin` 迁移已于 2026-10-10 删除**，旧档存在则被忽略）；同文件 **[ftp] 段 = FTP 鉴权**（`user` / `pwd_hash` = SHA-256(user‖password) / `write`，出厂默认 admin/admin，默认口令在用有启动告警；连续 5 次失败锁 60 s）→ `docs/子系统设计/网络配置说明.md`
|
||
- **新 .c 文件必须手动注册到两处**才能双端编译：`MDK-ARM/STM32F407-Demo.uvprojx` + `simulator/CMakeLists.txt`（用 `new-source-file` skill）；⚠ **新文件落在还没有的新目录，还要把该目录加进 `uvprojx` 的 `<IncludePath>`**——否则报错落在**消费者 TU** 上（`cannot open source input file`），极易误判
|
||
- 测试构建：`test/board/test_config.h` 的 `TEST_SUITE_CH395F/STORAGE/GD5F/RTC` **互斥**（一次只能一个，`#error`）；全部注释 = 产品构建，**受 `test-suite-switch` 钩子门禁**；`ENABLE_DESTRUCTIVE_TESTS` **默认关闭**（关闭时套件只读模式，可随时在在用设备上跑）——⚠ 跑一轮破坏性 GD5F 即让 dhara 多记一个坏块且该计数持久化，普通恢复清不掉 → `docs/测试说明/存储维护与容量恢复.md`；板级套件运行用 **`board-test-suite` skill**
|
||
- **改驱动前先读对应 `docs/问题记录/*_Trap_Records.md`**（CH395F / GD5F2GQ5UE / SD2506）；各模块测试指南见 `docs/测试说明/`
|
||
- **改 UI / 绘制缓冲前读两条实证坑**（I1 palette 头越界、白底白字整屏纯白）→ `docs/UI设计/UI_设计架构.md` §1.4 第 8/9 条，**`ui-verify` skill** 亦载
|
||
|
||
## 文档与图形
|
||
|
||
- **登记簿类文档「完成即销项」**：`docs/任务规划/README.md` 这类待办登记簿，事项修复/关闭后**直接从表中删除该行**（不保留"已消化"行）——结论与证据应已沉淀进对应模块文档/问题记录。销项时必须：① 先核对目标文档确已含完整记录 ② 同步清理其他文档对该编号的引用 ③ 改完跑 `check_doc_links.py --all` + pre-commit。**新条目标识（用户裁定 2026-10-14）**：`#` 列填**语义短语**（如 `沉降窗 800ms 上限只留痕`），**不再新增字母+数字编号**——"编号不回收"只写规则却不留痕迹就不可执行（销项删行后仓库无痕迹，实测 `N-31` 于 2026-10-14 被复用撞号），语义标识自带唯一性；存量编号冻结沿用、**已随销项消失的号永久作废** → `docs/任务规划/README.md` §0
|
||
- 图形走 **`draw-diagram` skill**：精确布局图用 `tools/arch_diagram/gen_*.py` 生成器（产物放 `docs/images/`，脚本与 .svg 一并提交）；拓扑图用 Mermaid；**勿手绘 ASCII 框图**。文件引用关系图走 `tools/refgraph`（`& 'tools\refgraph\gen_refgraph.bat'`）
|
||
- **改名 / 挪目录一律走 `scripts/rename_ref.py`（先 dry-run，确认后 `--apply`）**：`git mv` + 自动改写全库引用（反引号引用 / Markdown 链接 / 图片 `../` 层级换算 / `#include` / `uvprojx` `<FilePath>` / `CMakeLists.txt`），落盘后自动跑 `check_doc_links --all` 复核——手工扫引用既慢又漏（一次改名历史上波及 10~30 文件）。引用章节用「`路径.md` §N.M」**紧邻写法**（`doc-links` 校验编号是否还在：紧邻/裸名/前缀/别名/自引用**全部拦提交**（钩子带 `--sections-strict`）；每次跑打印「可判定比例」，`--section-todo` 出待改清单，昵称歧义就登记 `scripts/section_aliases.json` 或写清楚）→ `docs/文档规范.md` §3.5 / §3.6。**编号改名走 `scripts/rename_ids.py`**（映射表驱动、**显式 scope**、干跑默认、自动写 `scripts/id_aliases.json` 的 scoped 旧号→新号条目；`[示例]`/`[计划]` 行与变更记录表不改写；**绝不全局查找替换**——同一裸形字面量可能同时属多个族，全局替换等于造新撞号，实测 `S3` 三义）
|
||
- 文档写作规范（编码/BOM/链接/表格/一致性钩子）→ `docs/文档规范.md`；全量索引与推荐阅读顺序 → `docs/README.md`
|
||
|
||
## 边界（Ask first / Never）
|
||
|
||
**Ask first**（须用户明确指示才做，均不是任何任务的隐含步骤）：`git commit` / `git push`（构建与测试通过后停下等指令）· 开 `ENABLE_DESTRUCTIVE_TESTS` 跑破坏性套件（持久代价 → 模块约定）· CubeMX 重生成（→ `cubemx-regen` skill）· 登记簿删行销项（→ 文档与图形）· 建任务/抬栈/加大缓冲（先跑预算脚本 → 平台约束）
|
||
|
||
**Never**（任何任务）：用 `Get-Content`/`Set-Content`/`cmd` 重写含中文文件、用 `git checkout`/`reset --hard` 丢弃未提交工作（→ 铁律）· 在 `USER CODE` 区之外写定制代码、自研代码写 C 库堆分配（→ 平台约束）· 非 defaultTask 直接触碰配置引擎、非 netTask 直接碰 CH395F 驱动（→ 模块约定）· 提交 UV4 抖动的 `*.uvprojx`、提交 `.mnemon/`（记忆工具本地状态，已 `.gitignore`）
|
||
|
||
## 按主题查哪份文档
|
||
|
||
| 主题 | 去处 |
|
||
|---|---|
|
||
| 全量索引 / 推荐阅读顺序 | `docs/README.md` |
|
||
| 架构全景 / 启动时序与内核前模式 | `docs/架构设计/项目架构总览.md`、`docs/架构设计/项目启动顺序管理.md` |
|
||
| 产品需求基线（做到什么程度） | `docs/产品需求/产品需求设计文档.md` |
|
||
| 看门狗 + CubeMX 重生成存活方法论 + ARMCC `__asm` | `docs/子系统设计/看门狗设计说明.md` §10 |
|
||
| ADC 采样节拍 / 通道映射 / V0.1 硬件缺陷 | `docs/子系统设计/ADC采样节拍设计说明.md`、`docs/硬件平台/ADC通道映射说明.md` |
|
||
| 存储栈（FatFs / dhara / lftpd / 两条 FatFs 陷阱） | `docs/架构设计/STM32F4-Base存储架构说明.md` |
|
||
| RAM / 栈预算 / 容量台账 | `docs/内存管理/RAM使用分析与优化方案.md`、`内存内容分配策略.md` |
|
||
| **每个提交门禁一篇详解**（查什么 / 拦下过什么真事 / 限制与盲区 / 基线口径） | `docs/门禁说明/README.md`（48 个钩子 → 23 篇索引；bom-guard / setview-check 两篇待补） |
|
||
| 实体编号怎么写 / 前缀总表 / `id-check` 八项校验 | `docs/编号规范.md`（§4 总表、§8 门禁与实测基线） |
|
||
| 提交门禁通用机制（阶段 / stash 陷阱 / 触发面 / 增量拦截三段式） | `docs/代码规范/pre-commit使用说明.md` §2 |
|
||
| 代码规范 V1.0 / cppcheck 口径 | `docs/代码规范/嵌入式C语言代码规范_V1.0.md`、`cppcheck使用说明.md` |
|
||
| 自动化测试 / 实机测试 / 板级套件 | `docs/测试说明/自动化测试流程.md`、`实机测试实施指南.md`、`board-test-suite` skill |
|
||
| 烧录与复位语义 | `docs/测试说明/ST-LINK_CLI_复位使用说明.md` |
|
||
| 串口助手 | **`serial-assistant` skill**（命令/判据/陷阱，用到自动加载）、`docs/测试说明/串口助手使用指南.md`、`串口助手设计说明.md` |
|
||
| UI 架构 / 模拟器 / UI 自动化回归 | **`lvgl-simulator` skill**（构建/自检/报错速查，用到自动加载）、`docs/UI设计/UI_设计架构.md`、`LVGL模拟器部署与使用说明.md`、`UI_自动化测试流程.md`；UI 改动回归走 **`ui-verify` skill** |
|
||
| 待办与审计发现登记簿 | `docs/任务规划/README.md` |
|
||
| 多任务并行开发（开空间 / 合并回收 / 台架与构建排队） | **`task-worktree` skill**（`@task`，用到自动加载）、`docs/环境与部署/并行任务工作树方案.md` |
|
||
| 换机 / 工具路径环境变量 | `docs/环境与部署/` |
|
||
| 远程 CI（Gitea Actions，**只跑本机一台 runner**） | [`docs/CI/README.md`](docs/CI/README.md) |
|