起因:装真 cppcheck 2.21.0 后本钩子暴露 106 条命中,其中 76 条本就不该被扫。 cppcheck 与 coding-standard 两个钩子的注释都自称「范围一致」,实际各漏一块, 而本钩子此前从未真正跑起来(C:\cppcheck\cppcheck.exe 是坏 zipapp,进程根本没起, --error-exitcode 对「没跑起来」不生效),所以没人发现。两轮合计 834 条命中里 802 条是「不该被扫的」,真问题被完全淹没。 一、范围对齐(106 → 30) cppcheck 钩子 exclude 补三条 104 上游前缀:App/iec60870/common/、 App/iec60870/104/business/、App/iec60870/104/IEC104[_.]。三条只豁免上游库 尚未改造的部分,我们自己的小写适配文件(iec104_core/net_mcu/source/comm)仍受检。 不能改写成祖先目录 App/iec60870/,那会把适配层一起豁免。 test-cppcheck 钩子排除 test/host/iec104_netmcu/results(按 check_static_selftest.py 生成的自检变异体是故意写坏的副本,不是被测代码)。 二、剩余 30 条直接改代码清零(未建抑制基线) 逐条核过:cppcheck 判对了,它们违反本仓 docs/代码规范/嵌入式C语言代码规范_V1.0.md §6.1.1「变量应在使用前声明,并尽可能在靠近使用的地方声明」。仓内对「永久免检」 有明确反对立场(coding-standard 的 104 排除注释写着「改完必须删掉这三行,否则等于 自建代码永久免检」),故不建抑制基线,直接改对: - iec104_comm.c:4 处 v > IEC104_COMM_CA_MAX / PORT_MAX 删除。上界 65535 是 uint16_t 类型极限,比较恒为假(compareValueOutOfTypeRangeError);宏本身保留, App/app/ui_data_feed.c 的 UI 范围提示仍要用它表达合法带上界。 - ioboard_bits.c:删 && (i < IOBOARD_DI_COUNT),外层 for 已限定,且它在取下标之后才判。 - iec104_source.c:三处 ifdef 哑变量(a/p/raw、e/i/b/raw/p/element、i/m/g/valid) 把声明搬进各自编译档内,删掉全部 (void)x 抑制句——正是这些抑制句让 cppcheck 认为「读了未赋值变量」(unassignedVariable)。另 remote_lookup / parameter_config 的 i/n/p、g/m 就近声明。 - iec104_net_mcu.c:Listen 的 uint32_t i、Wait 的 listen_slot/client_slot/sock 移进各自分支;sock 加 const。 - net_socket.c:net_pending_bytes 的 p_sock 加 const。 - ui_task.c:ui_task_wave_load_head 的 FRESULT fr 移进 if (ofr == FR_OK) 块。 - ioboard_di.c:ioboard_di_snap_read 的 s1/s2 移进重试循环。 - ui_page_yx.c:pg_refresh 的 dio_row 移进板级开入开出区分支。 三、实证 - cppcheck 钩子:106 → 30 → 0,Passed。 - 反证钩子没被排除条款吞掉:注入 variableScope 探针 → 立即报出 variableScope + unreadVariable 两条;恢复后重新 Passed。 - Keil BUILD_OK 0 errors 0 warnings,Program Size 逐项不变 (Code=365896 RO=48336 RW=2736 ZI=173104)=本轮全是纯排版,零目标码变化。 - test-cppcheck Passed(0 命中)。 - 全量 manual 阶段 52 根钩子全绿、0 失败。 - host 套件:iec104_comm 50/50、ioboard 131/131、iec104_dtu 7 tests OK、 iec104_serv 50/50、net_socket 683/683、sys_clock 111/111、iec104_netmcu 17/17、 net_events 34/34、net_listener 34/34、net_pending 43/43、net_select 22/22、 ui_sink 17/17、lftpd 35/35、lftpd_inet 29/29、time_sync 33/33。 - UI golden:77 个页面 + 待机水位 + rtlive 全通过。 - net-handle:495 文件 PASS 0 违规。 - 裁剪档 IEC104_SOURCE_NO_VALUE_STORE 隔离编译 rc=0 无 error/warning (声明搬进 #else 后必须保证该档仍成立)。 - BOM:ui_page_yx.c / ui_task.c 编辑后 BOM 被剥,已补回,check_bom_drift rc=0。 四、顺带修掉的两处真实漏项 - ram_baseline.py 的 subsystem_of() 前缀表漏 ioboard:App/util/ioboard_di.c 编出的 ioboard_di.o(4 B)一直静默算进「其它」而非「应用」,台账配额表看不见。 - 内存台账回填:a2242b73(IEC104_Net_Listen 修复)是上次回填d2c328e8之后的 代码改动,内存数字从未重测,mem-numbers / mem-budget 两根钩子因此红。 本轮按当前权威构建重新回填(Code=365896,相对d2c328e8的 365924 减 28 B)。 五、文档 docs/代码规范/cppcheck使用说明.md: - §4.2 新增「安装陷阱:cppcheck.exe 可能是假 zipapp」——识别方法、根因、 2.21.0 正确装法(MSI 截断与续传、管理式解包、必须整目录)、为什么不用 pip 版、 教训(Failed 里没有命中/条数/文件名就当工具没跑起来)。 - §4.5 修正「Drivers/BSP/UI/ 不检查」的过期说法——它在本仓是手写 UI 页面代码 (库在 Lib/lvgl/),实测本钩子直接报了 ui_page_yx.c。 - §4.6 新增两根钩子的范围关系表:共享 11 项共同核心,各自另有小块豁免 (cppcheck 多排 test/,coding-standard 多排 Src/ Inc/ nand_ftl),是设计意图 不是漏配;改共同核心必须两边一起改。
docs/ 文档索引
定位:本目录是 STM32F4-Base 项目的工程文档库——架构设计、子系统设计、测试规范、问题记录(含专项审计与评审报告)与外部资料。 权威入口:日常开发以仓库根
AGENTS.md(面向 AI/开发者)为第一入口;本文档提供人类可读的全量索引与推荐阅读顺序。 约定:目录名不含空格;新增文档必须登记到本索引(见文末「新增文档约定」)。
1. 目录结构
docs/
├── README.md 本索引(阅读顺序 + 全量清单)
├── 任务规划/ 全项目顺序 + 硬件缺陷登记簿
├── 产品需求/ 产品需求设计文档(需求基线)+ 参考产品复刻明细(逐项差额)
├── 架构设计/ 全局架构与设计方法论(含 软件架构与运行时规格 / 硬件规格与能力边界:位表与引脚权威)
├── 子系统设计/ 各功能子系统的设计说明
├── iec60870/ IEC 60870-5-104 协议库设计与接口文档(36 篇,导航 iec60870/README.md)
├── 算法/ 傅氏算法与继电保护算法专题
├── 网络/ BSD Socket API 使用与内部实现
├── 测试说明/ 测试流程与规范 · 单元测试 · 板级测试 · 专项验证 · 测试工具 · 测试数据(六个子目录,导航 `测试说明/README.md`)
├── 代码规范/ 编码规范与静态检查门禁
├── 文档规范.md 本文档体系的规范(命名/链接/门禁/结构)
├── 内存管理/ RAM 预算、分配策略与优化调研
├── 问题记录/ 模块陷阱台账、专项审计与项目评审报告
├── 环境与部署/ 环境搭建与部署核对清单
├── CI/ 远程 CI(Gitea Actions)唯一入口 —— **只涉及本机一台 runner,日常开发不必读**
├── UI设计/ UI 架构、页面设计、字体与模拟器
├── 硬件平台/ 网表分析报告与语义图 + ADC 通道映射 + 开入开出实施说明
├── 芯片手册/ 外部芯片数据手册转录(只读资料)
└── images/ 文档技术配图(SVG 产物,由脚本生成)
⚠️
docs/芯片手册/(约 120 MB / 1754 张图)为只读外部输入资料,与代码演进无关; 后续拆分独立仓库或降采样(仓库膨胀观察项,已决策暂不处理)。
2. 推荐阅读顺序
新成员/新接手者按此顺序,可在最短时间内建立全局认知:
| 顺序 | 文档 | 读它能得到什么 |
|---|---|---|
| 1 | 产品需求设计文档.md |
产品定位·用户·场景、优先级总览、功能/非功能需求、接口规范、UI 规格、路线图与验收判据(运行时架构见 软件架构与运行时规格.md、硬件规格见 硬件规格与能力边界.md,复刻逐项差额见 参考产品复刻明细.md) |
| 2 | 项目架构总览.md |
六层分层、启动时序、存储/网络/UI 三栈、目录组织 |
| 3 | 项目启动顺序管理.md |
Event Flags 就绪屏障(取代魔法延时)的任务启动模型 |
| 4 | 项目部署环境要求.md |
开发机/目标板/现场部署的完整环境核对清单 |
| 5 | 项目部署环境要求.md → 构建 |
跑通 /keil-build / /serial-boot-test(见 keil-build / serial-boot-test skill) |
| 6 | 测试开发标准流程.md |
测试分层 静态门禁~保护判据与门禁决策表 |
| 7 | 嵌入式C语言代码规范_V1.0.md |
命名/格式/注释规范(提交门禁强制) |
| 8 | 项目架构总览.md → 按需 |
进入具体子系统设计文档 |
按角色:
- 应用/驱动开发 → §4 架构设计 → §5 子系统设计 → §7 问题记录(改驱动前必读对应 Trap Records)
- 测试/验证 → §6 测试说明 → §9.2 环境与部署
- UI 开发 → §8 UI 设计 → §6 测试说明(串口助手、UI 自动化测试流程)
- 接手/评审 → §9.1 评审报告 → §9.3 任务规划(全项目顺序,见
任务规划/README.md)
3. 产品需求
| 文档 | 内容 |
|---|---|
产品需求设计文档.md |
面向产品的需求基线:背景·目标用户·典型场景、范围与产品级非目标、需求总览(P0/P1/P2)、功能需求(网络/存储/时间/配置/日志/UI/看门狗/LED/ADC/RS-485/测频/保护/定值/SOE/104/屏板链路)、接口规范(RemoDispBus / 对时 / FTP / 配置 / 串口)、非功能需求(可靠性/性能/内存/门禁/双端)、UI 规格、缺口清单与推进顺序、验收判据 |
参考产品复刻明细.md |
1:1 复刻的逐项差额权威:参考源码能力清单(复刻基线)、104 地址空间、定值 249 项、遥测/开入开出/动作事件/元件/录波/记录/规约逐项明细、复刻完成判据、屏板链路复刻任务规划 |
4. 架构设计
| 文档 | 内容 |
|---|---|
项目架构总览.md |
系统全景:六层分层、启动时序、存储·网络·UI 栈、目录组织 |
软件架构与运行时规格.md |
六层分层表 / 任务模型 / 就绪位表 / 启动时序图 / 线程通信机制表 / 工具链与工程约束——位表、机制表、时序图以本档为准(自产品需求档拆出,2026-10-30 再按软/硬拆分) |
硬件规格与能力边界.md |
主控与内存 / V0.1 引脚分配表 / 存储器件 / 硬件版本兼容 / 能力边界 H1~H3——引脚表与能力边界表以本档为准;开入开出的实施细节见 硬件平台/开入开出实施说明.md |
STM32F4-Base存储架构说明.md |
GD5F2GQ5UE SPI NAND 之上的三层存储软件栈(FTL / dhara / FatFs) |
项目启动顺序管理.md |
CMSIS-RTOS v2 Event Flags 就绪屏障(SYS_EVT_NET_READY 等) |
图形绘制流程.md |
文档配图规范:SVG 生成器 / Mermaid 选型与检查清单 |
引用关系图说明.md |
文件级 #include 引用关系图生成(tools/refgraph,产物 images/) |
5. 子系统设计
5.1 功能子系统
| 文档 | 内容 |
|---|---|
配置文件设计.md |
/config.ini 配置引擎:分层、解析、原子持久化 |
网络配置说明.md |
网口设置页:IP/掩码/网关,UI 保存即时生效 |
系统墙钟时间维护说明.md |
sys_clock:RTC 基准、tick 回绕防护、30 天惰性再基准化 |
控制台单写者日志设计.md |
控制台日志单写者模型(避免多任务交错输出) |
运行与自检记录设计.md |
/log/*.log 七类 64B 定长记录、SOE 二进制记录、控制台日志、待机屏与七个记录页 |
看门狗设计说明.md |
IWDG(CubeMX 配置)+ 任务心跳位图:选型与超时推导、掩码与埋点、取证机制、验证记录;已台架闭环(V2/V4/V5)。§11 = 任务级饥饿的诊断方法与 [PROF] 实测基线(诊断沉淀:判读口径、量化归因、三条脆弱点、明确不做的四条) |
ADC采样节拍设计.md |
ADC 采集链路采样节拍(现状说明):TIM3 1 kHz 更新事件同时触发 TPAFE CONVST 与(经 TRGO)STM32 ADC1 + DMA 乒乓缓冲;节拍源为什么是 TIM3、DMA 硬约束、事件驱动消费与就绪门、实现落点、观测计数、性能特征与设计边界 |
| docs/子系统设计/故障录波设计说明.md | 故障录波设计与口径属主:1 kHz 起步与 80 点口径的偏离登记、存原始码值的理由、四段所有权与四条并发陷阱、段文件字节布局、现场单通道回放显示契约、预算与 R6 前置 |
IEC104上行设计说明.md |
IEC 104 上行规约:既有板端范围/点表/链路与历史验证;新增成熟共享核心迁入边界、标准演示集合、独立 RAM 参数、模拟动作和虚拟设备时间;真实 TCP 业务与板端替换状态分别说明,不把构建或旧台架结果当新核心验收 |
IEC104_MCU落地规划.md |
MCU 全功能规划(尚未实施):全点、全参数持久化及原子生效、通信切换、电能与严格兼容文件、网络与完整资源调查、逐项审批及分波次全量验收 |
屏板链路设计.md |
屏板串口链路(主机侧,Drivers/BSP/ScreenLink/)设计:链路与角色、USART1 700 kbaud 配置与中断收发、物理接线(含台架日志口与 PC 顶替屏板)、协议实现口径(CRC 字节序 / 整帧 DMA / 时序)、键值与状态灯映射表、资源与耗时、对外接口表、验证状态与未闭环项、坑账本 |
网络/BSD_Socket_API_使用指南.md |
上层视图:BSD Socket API 公开语义、示例、常见问题 |
网络/BSD_Socket_API_函数调用关系.md |
内部视图:netTask / 消息队列 / 保护判据挂起 / 重试对账的调用关系与设计意图 |
网络/Net层阻塞模型架构设计.md |
等待模型:recv/send 挂起请求架构、数据结构与挂起槽状态机、recv 五路 + send 四路完成语义、模块接口契约(14 函数)、实现落点(20 集成点)、调用方契约、设计边界与性能特征 |
网络/IEC104_Net适配契约.md |
104 板端 Net 后端契约:直译 vendor Close(client) 会毁掉监听的反例、按槽 role 的映射规则、LISTEN 恒定 / CLIENT 每次新建的双句柄模型、代次不变式、单调不复用句柄、NET_NO_OS 编译期边界与已知缺口、证据边界(fake 12/12,CH395F 板端未证) |
网络/网络自愈架构设计.md |
网络自愈架构 + 监听生命周期:现状权威描述——根因三层证据与 A′ 出局、ioLibrary 代码级对照、设计原则(不变量 I1net_listener.c / net_events.c 模块化边界、延后项;审计与实施过程已归档 |
网络/网络句柄失效值契约.md |
fd 失效值契约(0 是合法句柄):220 banner 误导链、三层根因(失效值落合法域 / 数值形态判据 / 主机假 fd 域不同域)+「MISRA 9.1 与 cppcheck 为何抓不到」、契约条款 C1net-handle 的 R1 |
5.2 算法专题
| 文档 | 内容 |
|---|---|
傅氏算法详解.md |
全周波傅氏(单频 DFT)原理与工程实现:正交性、梳状带通、滑动窗、系数表折算有效值;保护/遥测双轨有效值的算法基础 |
采集与算法层设计说明.md |
App/algo/ 的现状设计说明:语义取数与有效性判定、全周傅氏相量采样环/相量/测频、保护判据定值模型与元件框架的契约、关键机制(双区原子切换、乒乓半区、自适应测频窗、定值封存-自检-闭锁)、精度判据 J1~J6 与资源足迹;§13 = 标定折算(码值→工程量、三态可用性、未标定即闭锁、遥测快照、六轮动态验证判据、已定案的前置决策) |
继电保护功能复现规划.md |
保护功能复现规划:把参考系统(CLS100)保护链路映射到本项目(STM32F4)的分层功能/性能/参数清单、平台适配(「双转换器无共同采样触发」等)与分阶段路线图 |
采样有效性校验设计说明.md |
App/algo/adc_health.c 单文件深设计:四类判据(静默 / 丢帧 / 序号倒退 / 错误计数增量)的判据推导与 100 ms 门限依据、电平-锁存-事件三种位语义与位号对齐、闭锁与看门狗兜底的责任划分、观测盲区、主机侧验证分工与现场判读手册(含三张配图生成器) |
采样数据校正全流程.md |
读者入口:按一帧数据的真实流向,把端子→码值→三维折算(k/b/r)→相量/测频/遥测快照→104·UI·保护·录波串成一条线;含整定落盘、多点标定现状(板上无一键标定、拟合跑在 PC 侧 test/host/cal/cal_fit.py、固件只做折算与参数合法带校验,台架手工路径见 docs/测试说明/专项验证/ADC多点标定执行流程.md)、三个判定(VALID/CLIPPED/eng 互不派生);细节归各属主文档 |
5.3 IEC 60870-5-104 协议库文档(docs/iec60870/,36 篇)
入口:iec60870/README.md——按「想干什么」组织的导航(构建、点表、召唤、遥控、参数、文件、升级、历史、录波、日志、排障)。
这批文档随 104 协议库从 IEC60870-Slave/docs/ 迁入本仓文档库(2026-11-18),文中指向源码的链接已改指 App/iec60870/;标「本项目未实现」的 7 篇是能力参考,不代表功能可用。
与项目自有 104 文档的关系:
子系统设计/IEC104上行设计说明.md讲板端怎么接(点表、数据源、Net 后端、验收状态);本节这批讲协议库内部怎么实现。两者不重复:前者是本项目约定与落地状态,后者是协议模块的设计推理。
6. 测试说明
本目录分六个子目录(归层判据与本目录文件清单 →
测试说明/README.md); 下面每个分组与一个子目录一一对应。
流程与规范/(测试开发总流程、门禁决策表、测试文档模板)
| 文档 | 内容 |
|---|---|
测试开发标准流程.md |
测试开发总流程:规划→板端套件→主机工具→门禁→沉淀;门禁决策表 |
自动化测试流程.md |
/serial-boot-test 闭环细节:命令 / 串口标记 / 失败模式 |
测试文档模板规范.md |
测试文档模板与命名规则(TM / TC / DP) |
单元测试/(主机侧纯逻辑单测说明与覆盖率口径)
| 文档 | 内容 |
|---|---|
看门狗单元测试说明.md |
Task Watchdog 判定状态机(位图 / 掩码 / 节流 / tick 回绕),39 用例 |
系统时钟单元测试说明.md |
sys_clock 时间换算 / 星期 Zeller / 30 天惰性再基准化 / RTC 故障降级,100 断言点 |
开机账本单元测试说明.md |
boot_stats 上电次数四态(不可信 / 首次启用 / 延续 / 电池域掉过电)/ SRAM 记录校验与格式版本 / I2C 失败分支 / 复位原因优先级链,21 断言点 |
配置文件单元测试说明.md |
cfg_file INI 解析 / 值编解码 / load-save-poll 契约 / 超长守卫,149 断言点(含抓出的外科手术保存死码 P0) |
ADC输入层单元测试说明.md |
adc_input 语义通道映射 / ADC1 顺序扫描(Rank↔通道判据)/ poll 契约 / HAL 故障路径,70 用例 |
相量层单元测试说明.md |
phasor 全周傅氏系数表 / 幅值·相位 / 谐波抑制与提取 / 频偏 / 采样环 / 双区交换,57 用例 |
卷锁单元测试说明.md |
vol_lock 创建 / 获取 / 释放契约(fail-open 不变量:创建失败仍返回 1 且零阻塞)/ 幂等 / 超时透传,33 断言点 |
时间同步单元测试说明.md |
time_sync v2.0:分片喂狗延时 / 就绪屏障(100 ms 分片·NoClear)/ SNTP 节拍与网络代次交接 / 未出网守门(:8888 退役后的任务载体),33 断言点 |
主机单测覆盖率口径.md |
跨全部 16 套 主机侧纯逻辑单测的覆盖率:scripts/check_test_coverage.py 用法 / 统计面与生成物例外 / 基线增量门禁(只拦回退)/ 为什么本机拿不到分支覆盖 / 九条限制与盲区 / 未挂 pre-commit 的三条理由与待粘 YAML |
板级测试/(上板测试:模块测试指南 + 实机实施流程;动手写测试前先读)
| 文档 | 内容 |
|---|---|
CH395F_Test_Guide.md |
CH395F 以太网控制器(硬件层 Phase 1 |
GD5F2GQ5UE_Test_Guide.md |
GD5F2GQ5UE SPI NAND 存储测试 |
SD2506_Test_Guide.md |
SD2506 RTC 测试 |
FTP_Test_Guide.md |
FTP 服务测试 |
实机测试实施指南.md |
上板(真机)测试执行流程(按顺序:环境预检 → /serial-boot-test+自检判定 → IWDG 注入/长跑 → 堆告警 → GD5F 错误通道 → 网络基线 → 工程卫生;每步含判据/命令/状态);已完成事项证据去向见 §10 |
专项验证/(针对一个缺陷或一次复验的台架专项流程;做完即定稿)
| 文档 | 内容 |
|---|---|
ADC前端注入验证流程.md |
ADC 前端与两片转换器的台架注入验证(已知电压注入验证的执行侧,实测证据 → docs/硬件平台/ADC通道映射说明.md §8.1):两轮——直流轮(注入点清单 / 期望码值表 / 零点·线性·映射·极性·节奏五步,每步自带现场记录表,一块万用表即可)、交流轮(幅值/波形/相位/测频/削顶/谐波六轮执行卡);标定轮已独立成篇 → docs/测试说明/专项验证/ADC多点标定执行流程.md |
ADC多点标定执行流程.md |
UA/IA 多点(5 点)最小二乘标定的执行卡(UN = 零序电压 U0,本台架未接线、本轮不测):开工拍板(保护口径 ≤3meas: 行读数按「每行一个点」填进文档内 CALDATA 长表(5 点 × 3 路)→ test/host/cal/cal_fit.py --from-doc 在 PC 侧批量做最小二乘求解(亦支持 --sem/--x/--y 单路手填;固件里没有拟合代码,设备只做折算与写入参数合法带校验)→ test/host/cal/cal_write.py 经 104 定值段 0x8050docs/算法/采集与算法层设计说明.md §13.13 与 docs/硬件平台/ADC通道映射说明.md §7.2;2026-11-12 实跑结果(两点算法那一轮:UA / IA 已标定、UN 未标 → 保护仍闭锁)登记在 docs/硬件平台/ADC通道映射说明.md §7.3 |
启动日志原子性复验流程.md |
控制台整行独占 / 崩溃遗言原子性这类行级完整性判据的固定动作与口径(docs/子系统设计/控制台单写者日志设计.md 的验收侧:那边讲怎么修,这边讲怎么证明修好了、以及为什么"标记全中"不等于"日志没坏") |
故障录波板级到场轮执行手册.md |
录波剩余台架判据的执行手册(判据属主是 docs/子系统设计/故障录波设计说明.md §10,这里只写"人做什么、说哪句话、会看到什么"):四幕(枚举埋点修复 / 注量对表 / 保护触发对时刻(src=P)含两个用户决定 / bench 自抓占卷)各自标清到场与否,配到场检查清单、现场记录表与收工还原清单 |
链路延迟测试说明.md |
网络链路时延分段定义、判定基线、执行流程 |
模拟器差距清单.md |
PC 模拟器 vs 真机差距登记册(保护判据门禁可信度依据;改动涉及网络/日志/硬件层前必查 §3 决策规则) |
存储维护与容量恢复.md |
全片擦除恢复 dhara 坏块记账 / 容量恢复 |
测试工具/(PC 侧工具用法)
| 文档 | 内容 |
|---|---|
串口助手使用指南.md |
串口助手命令用法 / 工作流 / 排障 |
串口助手设计说明.md |
串口助手契约 / daemon 行为 / 陷阱 |
ST-LINK_CLI_复位使用说明.md |
烧录 / 复位 / 回读校验(ST-LINK_CLI 完整用法) |
测试数据/(一手证据,只增不改 → docs/测试说明/README.md §4)
| 目录 | 内容 |
|---|---|
boot_log_data/README.md |
/serial-boot-test 产出的开机串口日志快照存档(跨构建 [STACK] 栈 / 堆水位对照,39 个文件) |
m2_data/README.md |
链路时延 M2 安静档采集数据(JSON + 串口 [LAT] 片段,含逐帧尾批明细与方法学约束) |
m3_data/ |
链路时延 M3 各档原始 JSON(quiet / stress / pending / 尾批实验;无独立 README,口径见 链路延迟测试说明.md 附表) |
UI 相关测试见
UI设计/UI_自动化测试流程.md。
7. 代码规范 · 文档规范 · 内存管理 · 问题记录
7.1 代码规范(提交门禁相关)
| 文档 | 内容 |
|---|---|
嵌入式C语言代码规范_V1.0.md |
命名/格式/头文件/注释规范(含机械检查项) |
pre-commit使用说明.md |
提交门禁的部署、通用机制与范围口径(逐项详解见下行) |
cppcheck使用说明.md |
cppcheck 配置与告警处置 |
../门禁说明/README.md |
每个提交门禁一篇文档:查什么、拦下过什么真事、限制与盲区、豁免与基线口径 |
7.1b 文档规范(写/改文档前必读)
| 文档 | 内容 |
|---|---|
文档规范.md |
文档体系强制约定:目录/命名(无空格)、编码换行、链接形态(互链用根相对、图片用目录相对)、[计划] 标记、门禁三档、结构要素与常见错误速查 |
7.2 内存管理(新增任务/缓冲/栈前必读)
| 文档 | 内容 |
|---|---|
RAM使用分析与优化方案.md |
内存主文档:占用分析、优化方案、定栈规则 |
内存内容分配策略.md |
各内存区(SRAM/CCM)的分配策略 |
存储栈RAM优化调研.md |
存储栈 RAM 优化调研与结论 |
RAM预算台账.md |
预算台账:子系统配额、CCM 分配、趋势基线与 92% 门禁(内存治理三件套,2026-10-12) |
data/ |
ram_report_*.md / stack_report_*.md 快照数据(由 scripts/ 生成) |
7.3 问题记录(改驱动前必读)
| 文档 | 内容 |
|---|---|
CH395F_Trap_Records.md |
CH395F 以太网控制器陷阱台账 |
GD5F2GQ5UE_Trap_Records.md |
GD5F2GQ5UE SPI NAND 陷阱台账 |
SD2506_Trap_Records.md |
SD2506 RTC 陷阱台账 |
ADC_Trap_Records.md |
ADC1 采样链路陷阱台账(DMA 乒乓缓冲 +2 格相位旋转、RTOS 期校准被节拍打断;2026-10-27) |
采集与数据处理短板评测.md |
对照参考项目评测采集/遥测/录波/开入开出的完成度与缺口,给出补齐顺序(2026-10-23) |
8. UI 设计
| 文档 | 内容 |
|---|---|
UI_设计架构.md |
UI 分层架构、LVGL 移植要点与踩坑(I1 palette 头、dark mono 主题) |
菜单页面设计.md |
菜单树与导航设计 |
内容页架构.md |
内容页组织与渲染 |
UI_界面制作流程.md |
界面制作 P0→P4 流程与 Gate 判据 |
UI_中文字体生成与配置.md |
中文字库生成、子集化与配置 |
UI_自动化测试流程.md |
UI 模拟器像素回归(ui-verify 五步) |
LVGL模拟器部署与使用说明.md |
PC 端 LVGL 模拟器部署与使用 |
RemoDispBus协议与接收设计说明.md |
远端显示总线协议与接收设计 |
页面补齐规划.md |
内容页现状:43 节点 / 30 叶 / 已绑 27,逐页形态与数据来源,未绑三叶的原因 |
UI_数据供给设计.md |
App→UI 数据供给架构权威:三快照帧契约(rt/par/info)+ 注入执行侧(定值写/维护/遥测整定/通讯/录波/记录/SOE)、并发模型、测试策略 |
UI_时间响应分析.md |
UI 时间账的唯一权威:一次界面变化分五段各花多少、屏内 LVGL 绘制(含脏区短路机制)、两个出口(屏板串口 60.1 ms 物理常数 / 远端推流阻塞缺陷)、按键全链路耗时、测量缺口、数字性质三标签(真值 / 历史极值 / 推算);§5 = 「61.3 ms 是 LVGL 渲染地板」两处误归因的裁定 |
页面扩充详细方案.md |
27 个空叶子 + 3 页回炉的逐页方案:行表、数据源、组件、分批与预算(2026-10-23) |
mockups/ |
各页面参考图与说明 |
9. 评审报告 · 环境与部署 · 外部资料
9.1 评审报告
体系层评审报告《项目审查与优化建议报告》(原在
问题记录/)已于 2026-10-25 删除—— 大部分内容已闭环,留着的只有历史快照与重复清单。结论的去处: 未闭环的设计约束 → 各模块文档「已知限制/重开条件」节;内存与 Flash 结论(含整簇暂缓的重开条件) →内存管理/RAM使用分析与优化方案.md§2.5 / §2.6.4 / §4; UI 侧硬约束 →UI设计/UI_设计架构.md§1.4; 六个自有编号族(属主文档已删的那批)→scripts/archive/id_gate/编号治理历史.md§4.5(只能删号留事实,别再引用那些号)。
9.2 环境与部署
| 文档 | 内容 |
|---|---|
项目部署环境要求.md |
开发机软件环境、目标板资源预算、现场部署与验收步骤 |
并行任务工作树方案.md |
多任务并行开发机制(单一模型):DSH 插件创建工作树,task-worktree 补共享环境、构建/台架锁、bench-gate 台架验收门禁与 merge 编排式合并;含目录联接、冲突规则与容量建议 |
CI/README.md |
远程 CI(Gitea Actions)唯一入口:服务端开关 / runner 部署与保活 / workflow / 排障。只涉及本机一台 runner win-stm32-ci,其他机器与项目都不涉及;日常改代码用本地门禁 scripts/ci_local.py,不必读这里 |
9.3 台账与外部资料
| 位置 | 内容 |
|---|---|
任务规划/ |
两个文件:README.md = 全项目推进顺序(唯一权威);登记簿.md = V0.1 硬件缺陷 → V0.2 改版要求。其余待办跟着所属模块走(各文档「已知限制 / 重开条件」节):采集数据可信度 → docs/算法/采集与算法层设计说明.md §13、台阶图 → docs/硬件平台/ADC通道映射说明.md §9、RS-485 → docs/产品需求/产品需求设计文档.md §5.10 |
硬件平台/ |
网表详细分析报告与语义图(V0.0 / V0.1);ADC通道映射说明.md——V0.1 十七路 ADC 语义/网名/通道号权威映射表(固件取数、UI 显示、自检注入以此为准),含 §7 链路四段口径、§8 注入实测记录与 §9 数据可信五级台阶/波次退出判据;开入开出实施说明.md——74HC165 开入(8 路)与开出(9 路对外可控 + KO_24V 继电器供电自动使能)的接线、时序原理、软件分层与接口、上板验证步骤与已知限制 |
芯片手册/ |
外部芯片数据手册转录(CH395F / GD5F2GQ5UE / SD2506 / TPAFE5160 / RTL8305NBI 等) |
images/ |
文档技术配图(.svg 产物,由 tools/arch_diagram/、tools/refgraph/ 生成) |
10. 新增文档约定
- 目录归属:按上表选目录;新子领域先建无空格目录名(如
xxx设计/),并在此索引登记。 - 命名:主题词 + 类型后缀(
xxx设计说明.md/xxx_Test_Guide.md/xxx_Trap_Records.md)。 - 登记:新增文档必须在本文档对应章节补一行;否则视为未完成。
- 链接:文档间引用统一用仓库根相对路径(
docs/xxx/yyy.md),不使用../相对链接。 - 配图:走
架构设计/图形绘制流程.md(draw-diagramskill),产物统一放images/,脚本与.svg一并提交。 - 门禁:文档提交同样过 pre-commit(乱码 / 行尾空白 / gitlint + 文档链接存在性
doc-links/ 任务表一致性task-table,见文档规范.md§4 与代码规范/pre-commit使用说明.md)。
目录/文件名一律不含空格(2026-09-25 起强制):空格会迫使脚本、链接、CI 处处加引号, 且 URL 编码形态(
UI%20设计)易被漏改。现全库已无含空格目录。
11. 已知文档问题(待清理)
来源:原审查报告两条已销项(正文已移入
文档规范.md与 pre-commit 门禁)。 原报告三条已处理完毕(2026-09-25):全库链接存在性检查通过(66 文档 0 失效)、任务表与Src/freertos.c一致、文档规范已建立。下表保留仍需跟踪的项。
| 问题 | 位置 | 说明 |
|---|---|---|
UI_界面制作流程.md、UI_自动化测试流程.md → tools/ui_mock/ |
✅ 已改指(2026-10-14 核实):两份 UI 文档正文已无该路径(仅存变更记录里的历史提及);golden 回归落在 simulator/tests/(四脚本) |
|
内存管理/RAM使用分析与优化方案.md → scripts/ram_baseline.tsv |
✅ 已建(2026-10-12,「缩堆迁 CCM 后半(暂缓)」的前半):ram_baseline.py + ram_baseline.tsv + RAM预算台账.md + mem-budget 钩子 |
|
UI 设计/ |
✅ 已修复(2026-09-25):改名为 UI设计/,全仓库 67 处引用同步;命名约定见 文档规范.md §1 |
|
| — | ✅ 已落地(2026-09-25/26,文档门禁三档齐):scripts/check_doc_links.py(存在性)+ scripts/gen_task_table.py(数值)+ scripts/check_mem_numbers.py(体积),接入 pre-commit doc-links / task-table / mem-numbers 钩子 |
|
docs/文档规范.md 未创建 |
— | ✅ 已创建(2026-09-25):文档规范.md |
未闭环的文档类问题只剩仓库膨胀(仓库膨胀观察项,已决策暂不处理)。