STM32F4-Base/docs

docs/ 文档索引

定位：本目录是 STM32F4-Base 项目的工程文档库——架构设计、子系统设计、测试规范、问题记录（含专项审计与评审报告）与外部资料。 权威入口：日常开发以仓库根 AGENTS.md（面向 AI/开发者）为第一入口；本文档提供人类可读的全量索引与推荐阅读顺序。 约定：目录名不含空格；新增文档必须登记到本索引（见文末「新增文档约定」）。

---

1. 目录结构

docs/
├── README.md                 本索引（阅读顺序 + 全量清单）
├── 任务规划/                 统一待办（README 单一入口 + 6 个职责文件）
├── 产品需求/                 产品需求设计文档（面向产品的需求基线）
├── 架构设计/                 全局架构与设计方法论
├── 子系统设计/               各功能子系统的设计说明
├── 算法/                     傅氏算法与继电保护算法专题
├── 网络/                     BSD Socket API 使用与内部实现
├── 测试说明/                 测试流程、模块测试指南、工具说明
├── 代码规范/                 编码规范与静态检查门禁
├── 文档规范.md               本文档体系的规范（命名/链接/门禁/结构）
├── 内存管理/                 RAM 预算、分配策略与优化调研
├── 问题记录/                 模块陷阱台账、专项审计与项目评审报告
├── 环境与部署/               环境搭建与部署核对清单
├── CI/                       远程 CI（Gitea Actions）唯一入口 —— **只涉及本机一台 runner，日常开发不必读**
├── UI设计/                  UI 架构、页面设计、字体与模拟器
├── 硬件平台/                 网表分析报告与语义图
├── 芯片手册/                 外部芯片数据手册转录（只读资料）
└── images/                   文档技术配图（SVG 产物，由脚本生成）

⚠️ docs/芯片手册/（约 120 MB / 1754 张图）为只读外部输入资料，与代码演进无关； 后续拆分独立仓库或降采样（登记簿条目「仓库体积膨胀观察」，已决策暂不处理）。

---

2. 推荐阅读顺序

新成员/新接手者按此顺序，可在最短时间内建立全局认知：

顺序	文档	读它能得到什么
1	产品需求设计文档.md	产品定位、功能/非功能需求、接口规范、UI 规格、路线图与验收判据
2	项目架构总览.md	六层分层、启动时序、存储/网络/UI 三栈、目录组织
3	项目启动顺序管理.md	Event Flags 就绪屏障（取代魔法延时）的任务启动模型
4	项目部署环境要求.md	开发机/目标板/现场部署的完整环境核对清单
5	项目部署环境要求.md → 构建	跑通 @build / @test（见根 AGENTS.md）
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	面向产品的需求基线：产品定位与形态、六层架构与任务模型、V0.1 硬件规格、功能需求（网络/存储/时间/配置/日志/UI/看门狗/LED + 待实现的 ADC/RS-485）、接口规范（RemoDispBus / 对时 / FTP / 配置 / 串口）、非功能需求（可靠性/性能/内存/门禁/双端）、UI 规格、待实现项与路线图、验收判据

---

4. 架构设计

文档	内容
项目架构总览.md	系统全景：六层分层、启动时序、存储·网络·UI 栈、目录组织
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 配置引擎：分层、解析、原子持久化（旧 NCFG 档已废弃）
网络配置说明.md	网口设置页：IP/掩码/网关，UI 保存即时生效
系统墙钟时间维护说明.md	sys_clock：RTC 基准、tick 回绕防护、30 天惰性再基准化
控制台单写者日志设计说明.md	控制台日志单写者模型（避免多任务交错输出）
运行与自检记录设计说明.md	/log/run.log·selftest.log 定长记录与待机显示
看门狗设计说明.md	IWDG（CubeMX 配置）+ 任务心跳位图：选型与超时推导、掩码与埋点、取证机制、验证记录；已台架闭环（V2/V4/V5）。§11 = 任务级饥饿的诊断方法与 [PROF] 实测基线（诊断沉淀：判读口径、量化归因、三条脆弱点、明确不做的四条）
ADC采样节拍设计说明.md	ADC 采集链路采样节拍（现状说明）：TIM3 1 kHz 更新事件同时触发 TPAFE CONVST 与（经 TRGO）STM32 ADC1 + DMA 乒乓缓冲；节拍源为什么是 TIM3、DMA 硬约束、事件驱动消费与就绪门、实现落点、观测计数、性能特征与设计边界
IEC104上行设计说明.md	B4 上行规约：IEC 60870-5-104 被控站（TCP 2404）范围/点表（V0.1 有效子集）/链路流程（k/w/t1~t3、总召、COV、遥控两段式、定值）/netTask 接入决策/预算与测试方案；协议核心纯逻辑 + 主机侧纯逻辑单测全栈单测
网络/BSD_Socket_API_使用指南.md	上层视图：BSD Socket API 公开语义、示例、常见问题
网络/BSD_Socket_API_函数调用关系.md	内部视图：netTask / 消息队列 / 保护判据挂起 / 重试对账的调用关系与设计意图
网络/Net层阻塞模型架构设计.md	等待模型：recv/send 挂起请求架构、数据结构与挂起槽状态机、recv 五路 + send 四路完成语义、模块接口契约（14 函数）、实现落点（20 集成点）、调用方契约、设计边界与性能特征
网络/网络自愈架构设计.md	网络自愈架构 + 监听生命周期：现状权威描述——根因三层证据与 A′ 出局、ioLibrary 代码级对照、设计原则（不变量 I1I8）、分层职责与三 tick、reconciler 形态①⑤ + M3 门、驱动原语、读即清信源审计、FUN_PARA bit3 契约、recv 语义、KeepAlive、参数表与 E 锚点速查、红线、编号发现速查、代码级事实清点、决策记录、net_listener.c / net_events.c 模块化边界、延后项；审计与实施过程已归档

---

5.2 算法专题

文档	内容
傅氏算法详解.md	全周波傅氏（单频 DFT）原理与工程实现：正交性、梳状带通、滑动窗、系数表折算有效值；保护/遥测双轨有效值的算法基础
采集与算法层设计说明.md	App/algo/ 的现状设计说明：语义取数与有效性判定、全周傅氏相量采样环/相量/测频、保护判据定值模型与元件框架的契约、关键机制（双区原子切换、乒乓半区、自适应测频窗、定值封存-自检-闭锁）、精度判据 J1~J6 与资源足迹
继电保护功能复现规划.md	保护功能复现规划：把参考系统（CLS100）保护链路映射到本项目（STM32F4）的分层功能/性能/参数清单、平台适配（「双转换器无共同采样触发」等）与分阶段路线图
采样有效性校验设计说明.md	App/algo/adc_health.c 单文件深设计：四类判据（静默 / 丢帧 / 序号倒退 / 错误计数增量）的判据推导与 100 ms 门限依据、电平-锁存-事件三种位语义与位号对齐、闭锁与看门狗兜底的责任划分、观测盲区、主机侧验证分工与现场判读手册（含三张配图生成器）

---

6. 测试说明

总流程与规范

文档	内容
测试开发标准流程.md	测试开发总流程：规划→板端套件→主机工具→门禁→沉淀；门禁决策表
自动化测试流程.md	@test 闭环细节：命令 / 串口标记 / 失败模式
测试文档模板规范.md	测试文档模板与命名规则（TM / TC / DP）
链路延迟测试说明.md	网络链路时延分段定义、判定基线、执行流程
模拟器差距清单.md	PC 模拟器 vs 真机差距登记册（保护判据门禁可信度依据；改动涉及网络/日志/硬件层前必查 §3 决策规则）
实机测试实施指南.md	上板（真机）测试执行流程（按顺序：环境预检 → @test+自检判定 → IWDG 注入/长跑 → 堆告警 → GD5F 错误通道 → 网络基线 → 工程卫生；每步含判据/命令/状态）；已完成事项证据去向见 §10
ADC前端注入验证流程.md	ADC 前端与两片转换器的台架注入验证（已知电压注入验证的执行侧，实测证据 → docs/硬件平台/ADC通道映射说明.md §8.1）：注入点清单 / 期望码值表 / 零点·线性·映射·极性·节奏五步（每步自带现场记录表，边做边填）；不需示波器与信号源，一块万用表即可

主机侧单元测试（主机侧纯逻辑单测）

文档	内容
看门狗单元测试说明.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 分片喂狗延时 / 监听退避 / 时间包重组 / 任务主循环（探针窗口心跳缺口的全部逻辑贡献者），80 断言点
主机单测覆盖率口径.md	跨全部 16 套 主机侧纯逻辑单测的覆盖率：scripts/check_test_coverage.py 用法 / 统计面与生成物例外 / 基线增量门禁（只拦回退）/ 为什么本机拿不到分支覆盖 / 九条限制与盲区 / 未挂 pre-commit 的三条理由与待粘 YAML

模块测试指南（动手写测试前先读）

文档	内容
CH395F_Test_Guide.md	CH395F 以太网控制器（硬件层 Phase 15 / NET 层 Phase 611）
GD5F2GQ5UE_Test_Guide.md	GD5F2GQ5UE SPI NAND 存储测试
SD2506_Test_Guide.md	SD2506 RTC 测试
FTP_Test_Guide.md	FTP 服务测试

工具与运维

文档	内容
串口助手使用指南.md	串口助手命令用法 / 工作流 / 排障
串口助手设计说明.md	串口助手契约 / daemon 行为 / 陷阱
ST-LINK_CLI_复位使用说明.md	烧录 / 复位 / 回读校验（ST-LINK_CLI 完整用法）
存储维护与容量恢复.md	全片擦除恢复 dhara 坏块记账 / 容量恢复
m2_data/README.md · m3_data/	链路时延测试采集数据（JSON 原始记录）

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% 门禁（登记簿条目「缩堆迁 CCM 后半（暂缓）」，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	27 个空叶子页面的归并、前置能力（数据快照层/数值编辑）与分批顺序（2026-10-23）
UI_数据供给设计说明.md	页面实时数据的高内聚低耦合方案：快照推送（rt/par 双通道）、写路径、记录 reader 注入（2026-10-23）
页面扩充详细方案.md	27 个空叶子 + 3 页回炉的逐页方案：行表、数据源、组件、分批与预算（2026-10-23）
mockups/	各页面参考图与说明

---

9. 评审报告 · 环境与部署 · 外部资料

9.1 评审报告

体系层评审报告《项目审查与优化建议报告》（原在 问题记录/）已于 2026-10-25 删除—— 大部分内容已闭环，留着的只有历史快照与重复清单。结论的去处： 未闭环项 → 任务规划/登记簿.md；内存与 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	多任务并行开发机制：git worktree 隔离、目录与共享/独占分配（junction 规则）、task-worktree（@task）SKILL 命令面、单写者文档与合并残留审计、台架锁；已落地并端到端实测（见其 §11）
CI/README.md	远程 CI（Gitea Actions）唯一入口：服务端开关 / runner 部署与保活 / workflow / 排障。只涉及本机一台 runner win-stm32-ci，其他机器与项目都不涉及；日常改代码用本地门禁 scripts/ci_local.py，不必读这里

9.3 台账与外部资料

位置	内容
任务规划/	统一待办入口（6 个文件）：README.md = 现在做什么与全项目顺序；UI补齐.md = 当前唯一执行清单；登记簿.md = 后续任务、外部窗口与长期观察；数据可信.md = 两项阻塞任务及代码引用的设计约束；暂缓-RS485.md、屏板链路.md = 两个专项（测试与架构专项.md 已删除 2026-10-28，未闭环约束并入 暂缓-RS485.md）。完成即删，重复内容只保留一个归属
硬件平台/	网表详细分析报告与语义图（V0.0 / V0.1）；ADC通道映射说明.md——V0.1 十七路 ADC 语义/网名/通道号权威映射表（固件取数、UI 显示、自检注入以此为准）
芯片手册/	外部芯片数据手册转录（CH395F / GD5F2GQ5UE / SD2506 / TPAFE5160 / RTL8305NBI 等）
images/	文档技术配图（.svg 产物，由 tools/arch_diagram/、tools/refgraph/ 生成）

---

10. 新增文档约定

1. 目录归属：按上表选目录；新子领域先建无空格目录名（如 xxx设计/），并在此索引登记。
2. 命名：主题词 + 类型后缀（xxx设计说明.md / xxx_Test_Guide.md / xxx_Trap_Records.md）。
3. 登记：新增文档必须在本文档对应章节补一行；否则视为未完成。
4. 链接：文档间引用统一用仓库根相对路径（docs/xxx/yyy.md），不使用 ../ 相对链接。
5. 配图：走 架构设计/图形绘制流程.md（draw-diagram skill），产物统一放 images/，脚本与 .svg 一并提交。
6. 门禁：文档提交同样过 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

未闭环的文档类问题只剩仓库膨胀（登记簿条目「仓库体积膨胀观察」，已决策暂不处理）。

---

12. 变更记录

（本文件不再记流水账：改了什么是正文说了算，改动过程查 git log。）