wandering1
2525c2d948
用户裁定两条：① 剩余裸写端口的地方加「工厂默认」限定词，不改固件行为； ② 生效语义按需求口径「保存即生效」定，现实现（端口下次重 bind 才生效）是 要改的一侧 → 建任务登记，本笔不动代码行为。 限定词（24 处 / 17 文件）：AGENTS 数据主线、App/protocol/README、根 README 文档索引、Src/freertos.c 三处任务注释、docs/README、项目启动顺序管理、存储 架构说明、软件架构与运行时规格（2）、RAM 使用分析、产品需求设计文档（5）、 项目架构总览（3）、test/host/README、iec104_master 流程注释、IEC104 上行设 计说明、继电保护功能复现规划。配图两张同批重跑：gen_arch_svg.py 与 gen_memory_svg.py（脚本与产物同一笔）。 两处陈旧计数（都做过双源核证）： - 测试开发标准流程 像素层「60 内容页」→ 内容页黄金参考 66 张（64 页）； 双源 = simulator/tests/ref/shot_*.bin 实数 66 与 check_content_pages.py 的 PAGES 66 条（含两个 _p2）。 - .pre-commit-config.yaml 的 uinav-selftest 注释「18 张黄金参考」→ 写成 「接线当时 18 张、现 66 张」：git log -S 定到 6a904c1b（2026-10-25），那 天 ref 目录确实 18 张，写时为真，但它描述的是钩子现有行为，属当前态。 口径修正与登记： - 页面扩充详细方案「通讯设置 = 无配置模型（端口与 CA 都是 #define）」→ 标 「当时」，并写明现已在 /config.ini 的 [comm] 段可配、UI 通讯设置页可改。 - 产品需求 §通讯配置：删掉「改后需重启生效」这句把两件事混为一谈的话，改成 需求要求「保存即生效」+ 现实现（公共地址重启、端口下次重 bind）+ 指向登记簿。 - docs/任务规划/登记簿.md §1 新增「104 端口改后立刻重 bind」：含隐性耦合 —— .serialtest/config.json 的必检锚点写死 listening on 2404，端口一改串口 回归必假失败；改行为时要么锚点只查 listening on，要么由脚本注入端口。 复扫（旧形态归零判据）剩 20 处未带限定词，逐条定性为刻意不改：默认值定义处、 出厂模板与断言、usage 与 argparse default、UI 黄金参考显示值、台架主站地址 （同数不同义）、串口锚点、叙事句、引用关系图坐标。逐条理由见一次性台账。 门禁：check_doc_links --sections-strict 对 16 篇改动 .md 逐个 rc=0； check_mermaid --all 31 文件 62 围栏新发 0；check_nested_comment --all 449 文件新发 0；check_bom_drift --all 99 个名单内文件无漂移； check_generated_fresh PASS（25 生成器 / 21 一致 / 4 只减不增基线）；字节体检 无新增 BOM / CR / U+FFFD / 行尾空格（三连空行与 HEAD 逐项相同 = 存量）。 /keil-build 0 错 0 警，Program Size Code=246720 RO=29836 RW=2052 ZI=149708 与凭证同码：本笔只碰注释与配图文字，无固件行为变更。
301 lines
29 KiB
Markdown
301 lines
29 KiB
Markdown
# docs/ 文档索引
|
||
|
||
> **定位**：本目录是 STM32F4-Base 项目的**工程文档库**——架构设计、子系统设计、测试规范、问题记录（含专项审计与评审报告）与外部资料。
|
||
> **权威入口**：日常开发以仓库根 `AGENTS.md`（面向 AI/开发者）为第一入口；本文档提供**人类可读的全量索引与推荐阅读顺序**。
|
||
> **约定**：目录名不含空格；新增文档必须登记到本索引（见文末「新增文档约定」）。
|
||
|
||
---
|
||
|
||
## 1. 目录结构
|
||
|
||
```
|
||
docs/
|
||
├── README.md 本索引（阅读顺序 + 全量清单）
|
||
├── 任务规划/ 统一待办（README 单一入口 + 6 个职责文件）
|
||
├── 产品需求/ 产品需求设计文档（需求基线）+ 参考产品复刻明细（逐项差额）
|
||
├── 架构设计/ 全局架构与设计方法论（含 软件架构与运行时规格 / 硬件规格与能力边界：位表与引脚权威）
|
||
├── 子系统设计/ 各功能子系统的设计说明
|
||
├── 算法/ 傅氏算法与继电保护算法专题
|
||
├── 网络/ BSD Socket API 使用与内部实现
|
||
├── 测试说明/ 测试流程与规范 · 单元测试 · 板级测试 · 专项验证 · 测试工具 · 测试数据（六个子目录，导航 `测试说明/README.md`）
|
||
├── 代码规范/ 编码规范与静态检查门禁
|
||
├── 文档规范.md 本文档体系的规范（命名/链接/门禁/结构）
|
||
├── 内存管理/ RAM 预算、分配策略与优化调研
|
||
├── 问题记录/ 模块陷阱台账、专项审计与项目评审报告
|
||
├── 环境与部署/ 环境搭建与部署核对清单
|
||
├── CI/ 远程 CI（Gitea Actions）唯一入口 —— **只涉及本机一台 runner，日常开发不必读**
|
||
├── UI设计/ UI 架构、页面设计、字体与模拟器
|
||
├── 硬件平台/ 网表分析报告与语义图
|
||
├── 芯片手册/ 外部芯片数据手册转录（只读资料）
|
||
└── images/ 文档技术配图（SVG 产物，由脚本生成）
|
||
```
|
||
|
||
> ⚠️ `docs/芯片手册/`（约 120 MB / 1754 张图）为**只读外部输入资料**，与代码演进无关；
|
||
> 后续拆分独立仓库或降采样（登记簿条目「仓库体积膨胀观察」，已决策暂不处理）。
|
||
|
||
---
|
||
|
||
## 2. 推荐阅读顺序
|
||
|
||
新成员/新接手者按此顺序，可在最短时间内建立全局认知：
|
||
|
||
| 顺序 | 文档 | 读它能得到什么 |
|
||
|:---:|---|---|
|
||
| 1 | [`产品需求设计文档.md`](产品需求/产品需求设计文档.md) | 产品定位·用户·场景、优先级总览、功能/非功能需求、接口规范、UI 规格、路线图与验收判据（运行时架构见 [`软件架构与运行时规格.md`](架构设计/软件架构与运行时规格.md)、硬件规格见 [`硬件规格与能力边界.md`](架构设计/硬件规格与能力边界.md)，复刻逐项差额见 [`参考产品复刻明细.md`](产品需求/参考产品复刻明细.md)） |
|
||
| 2 | [`项目架构总览.md`](架构设计/项目架构总览.md) | 六层分层、启动时序、存储/网络/UI 三栈、目录组织 |
|
||
| 3 | [`项目启动顺序管理.md`](架构设计/项目启动顺序管理.md) | Event Flags 就绪屏障（取代魔法延时）的任务启动模型 |
|
||
| 4 | [`项目部署环境要求.md`](环境与部署/项目部署环境要求.md) | 开发机/目标板/现场部署的完整环境核对清单 |
|
||
| 5 | [`项目部署环境要求.md`](环境与部署/项目部署环境要求.md) → 构建 | 跑通 `/keil-build` / `/serial-boot-test`（见根 `AGENTS.md`） |
|
||
| 6 | [`测试开发标准流程.md`](测试说明/流程与规范/测试开发标准流程.md) | 测试分层 静态门禁~保护判据与门禁决策表 |
|
||
| 7 | [`嵌入式C语言代码规范_V1.0.md`](代码规范/嵌入式C语言代码规范_V1.0.md) | 命名/格式/注释规范（提交门禁强制） |
|
||
| 8 | [`项目架构总览.md`](架构设计/项目架构总览.md) → 按需 | 进入具体子系统设计文档 |
|
||
|
||
**按角色**：
|
||
- **应用/驱动开发** → §4 架构设计 → §5 子系统设计 → §7 问题记录（**改驱动前必读对应 Trap Records**）
|
||
- **测试/验证** → §6 测试说明 → §9.2 环境与部署
|
||
- **UI 开发** → §8 UI 设计 → §6 测试说明（串口助手、UI 自动化测试流程）
|
||
- **接手/评审** → §9.1 评审报告 → §9.3 任务规划（统一待办登记簿，见 `任务规划/README.md`）
|
||
|
||
---
|
||
|
||
## 3. 产品需求
|
||
|
||
| 文档 | 内容 |
|
||
|---|---|
|
||
| [`产品需求设计文档.md`](产品需求/产品需求设计文档.md) | **面向产品的需求基线**：背景·目标用户·典型场景、范围与产品级非目标、需求总览（P0/P1/P2）、功能需求（网络/存储/时间/配置/日志/UI/看门狗/LED/ADC/RS-485/测频/保护/定值/SOE/104/屏板链路）、接口规范（RemoDispBus / 对时 / FTP / 配置 / 串口）、非功能需求（可靠性/性能/内存/门禁/双端）、UI 规格、缺口清单与推进顺序、验收判据 |
|
||
| [`参考产品复刻明细.md`](产品需求/参考产品复刻明细.md) | **1:1 复刻的逐项差额权威**：参考源码能力清单（复刻基线）、104 地址空间、定值 249 项、遥测/开入开出/动作事件/元件/录波/记录/规约逐项明细、复刻完成判据、屏板链路复刻任务规划 |
|
||
|
||
---
|
||
|
||
## 4. 架构设计
|
||
|
||
| 文档 | 内容 |
|
||
|---|---|
|
||
| [`项目架构总览.md`](架构设计/项目架构总览.md) | 系统全景：六层分层、启动时序、存储·网络·UI 栈、目录组织 |
|
||
| [`软件架构与运行时规格.md`](架构设计/软件架构与运行时规格.md) | 六层分层表 / 任务模型 / 就绪位表 / 启动时序图 / 线程通信机制表 / 工具链与工程约束——**位表、机制表、时序图以本档为准**（自产品需求档拆出，2026-10-30 再按软/硬拆分） |
|
||
| [`硬件规格与能力边界.md`](架构设计/硬件规格与能力边界.md) | 主控与内存 / V0.1 引脚分配表 / 存储器件 / 硬件版本兼容 / 能力边界 H1~H5 与量纲口径——**引脚表与能力边界表以本档为准** |
|
||
| [`STM32F4-Base存储架构说明.md`](架构设计/STM32F4-Base存储架构说明.md) | GD5F2GQ5UE SPI NAND 之上的三层存储软件栈（FTL / dhara / FatFs） |
|
||
| [`项目启动顺序管理.md`](架构设计/项目启动顺序管理.md) | CMSIS-RTOS v2 Event Flags 就绪屏障（`SYS_EVT_NET_READY` 等） |
|
||
| [`图形绘制流程.md`](架构设计/图形绘制流程.md) | 文档配图规范：SVG 生成器 / Mermaid 选型与检查清单 |
|
||
| [`引用关系图说明.md`](架构设计/引用关系图说明.md) | 文件级 `#include` 引用关系图生成（`tools/refgraph`，产物 `images/`） |
|
||
|
||
---
|
||
|
||
## 5. 子系统设计
|
||
|
||
### 5.1 功能子系统
|
||
|
||
| 文档 | 内容 |
|
||
|---|---|
|
||
| [`配置文件设计说明.md`](子系统设计/配置文件设计说明.md) | `/config.ini` 配置引擎：分层、解析、原子持久化（旧 NCFG 档已废弃） |
|
||
| [`网络配置说明.md`](子系统设计/网络配置说明.md) | 网口设置页：IP/掩码/网关，UI 保存即时生效 |
|
||
| [`系统墙钟时间维护说明.md`](子系统设计/系统墙钟时间维护说明.md) | `sys_clock`：RTC 基准、tick 回绕防护、30 天惰性再基准化 |
|
||
| [`控制台单写者日志设计说明.md`](子系统设计/控制台单写者日志设计说明.md) | 控制台日志单写者模型（避免多任务交错输出） |
|
||
| [`运行与自检记录设计说明.md`](子系统设计/运行与自检记录设计说明.md) | `/log/run.log`·`selftest.log` 定长记录与待机显示 |
|
||
| [`看门狗设计说明.md`](子系统设计/看门狗设计说明.md) | IWDG（CubeMX 配置）+ 任务心跳位图：选型与超时推导、掩码与埋点、取证机制、验证记录；已台架闭环（V2/V4/V5）。**§11 = 任务级饥饿的诊断方法与 `[PROF]` 实测基线**（诊断沉淀：判读口径、量化归因、三条脆弱点、明确不做的四条） |
|
||
| [`ADC采样节拍设计说明.md`](子系统设计/ADC采样节拍设计说明.md) | **ADC 采集链路采样节拍（现状说明）**：TIM3 1 kHz 更新事件同时触发 TPAFE CONVST 与（经 TRGO）STM32 ADC1 + DMA 乒乓缓冲；节拍源为什么是 TIM3、DMA 硬约束、事件驱动消费与就绪门、实现落点、观测计数、性能特征与设计边界 |
|
||
| [docs/子系统设计/故障录波设计说明.md](子系统设计/故障录波设计说明.md) | **故障录波设计与口径属主**：1 kHz 起步与 80 点口径的偏离登记、存原始码值的理由、四段所有权与四条并发陷阱、段文件字节布局、现场单通道回放显示契约、预算与 R6 前置 |
|
||
| [`IEC104上行设计说明.md`](子系统设计/IEC104上行设计说明.md) | **B4 上行规约**：IEC 60870-5-104 被控站（TCP 工厂默认 2404）范围/点表（V0.1 有效子集）/链路流程（k/w/t1~t3、总召、COV、遥控两段式、定值）/netTask 接入决策/预算与测试方案；协议核心纯逻辑 + 主机侧纯逻辑单测全栈单测 |
|
||
| [`屏板链路设计说明.md`](子系统设计/屏板链路设计说明.md) | **屏板串口链路（主机侧，`Drivers/BSP/ScreenLink/`）设计**：链路与角色、USART1 700 kbaud 配置与中断收发、物理接线（含台架日志口与 PC 顶替屏板）、协议实现口径（CRC 字节序 / 整帧 DMA / 时序）、键值与状态灯映射表、资源与耗时、对外接口表、验证状态与未闭环项、坑账本 |
|
||
| [`网络/BSD_Socket_API_使用指南.md`](网络/BSD_Socket_API_使用指南.md) | **上层视图**：BSD Socket API 公开语义、示例、常见问题 |
|
||
| [`网络/BSD_Socket_API_函数调用关系.md`](网络/BSD_Socket_API_函数调用关系.md) | **内部视图**：netTask / 消息队列 / 保护判据挂起 / 重试对账的调用关系与设计意图 |
|
||
| [`网络/Net层阻塞模型架构设计.md`](网络/Net层阻塞模型架构设计.md) | **等待模型**：recv/send 挂起请求架构、数据结构与挂起槽状态机、recv 五路 + send 四路完成语义、模块接口契约（14 函数）、实现落点（20 集成点）、调用方契约、设计边界与性能特征 |
|
||
| [`网络/网络自愈架构设计.md`](网络/网络自愈架构设计.md) | **网络自愈架构 + 监听生命周期**：现状权威描述——根因三层证据与 A′ 出局、ioLibrary 代码级对照、设计原则（不变量 I1~I8）、分层职责与三 tick、reconciler 形态①~⑤ + M3 门、驱动原语、读即清信源审计、FUN_PARA bit3 契约、recv 语义、KeepAlive、参数表与 E 锚点速查、红线、编号发现速查、代码级事实清点、决策记录、`net_listener.c` / `net_events.c` 模块化边界、延后项；审计与实施过程已归档 |
|
||
|
||
---
|
||
|
||
### 5.2 算法专题
|
||
|
||
| 文档 | 内容 |
|
||
|---|---|
|
||
| [`傅氏算法详解.md`](算法/傅氏算法详解.md) | 全周波傅氏（单频 DFT）原理与工程实现：正交性、梳状带通、滑动窗、系数表折算有效值；保护/遥测双轨有效值的算法基础 |
|
||
| [`采集与算法层设计说明.md`](算法/采集与算法层设计说明.md) | **`App/algo/` 的现状设计说明**：语义取数与有效性判定、全周傅氏相量采样环/相量/测频、保护判据定值模型与元件框架的契约、关键机制（双区原子切换、乒乓半区、自适应测频窗、定值封存-自检-闭锁）、精度判据 J1~J6 与资源足迹 |
|
||
| [`继电保护功能复现规划.md`](算法/继电保护功能复现规划.md) | **保护功能复现规划**：把参考系统（CLS100）保护链路映射到本项目（STM32F4）的分层功能/性能/参数清单、平台适配（「双转换器无共同采样触发」等）与分阶段路线图 |
|
||
| [`采样有效性校验设计说明.md`](算法/采样有效性校验设计说明.md) | **`App/algo/adc_health.c` 单文件深设计**：四类判据（静默 / 丢帧 / 序号倒退 / 错误计数增量）的判据推导与 100 ms 门限依据、电平-锁存-事件三种位语义与位号对齐、闭锁与看门狗兜底的责任划分、观测盲区、主机侧验证分工与现场判读手册（含三张配图生成器） |
|
||
|
||
---
|
||
|
||
## 6. 测试说明
|
||
|
||
> 本目录分六个子目录（**归层判据与本目录文件清单 → [`测试说明/README.md`](测试说明/README.md)**）；
|
||
> 下面每个分组与一个子目录一一对应。
|
||
|
||
**流程与规范/**（测试开发总流程、门禁决策表、测试文档模板）
|
||
|
||
| 文档 | 内容 |
|
||
|---|---|
|
||
| [`测试开发标准流程.md`](测试说明/流程与规范/测试开发标准流程.md) | 测试开发总流程：规划→板端套件→主机工具→门禁→沉淀；门禁决策表 |
|
||
| [`自动化测试流程.md`](测试说明/流程与规范/自动化测试流程.md) | `/serial-boot-test` 闭环细节：命令 / 串口标记 / 失败模式 |
|
||
| [`测试文档模板规范.md`](测试说明/流程与规范/测试文档模板规范.md) | 测试文档模板与命名规则（TM / TC / DP） |
|
||
|
||
**单元测试/**（主机侧纯逻辑单测说明与覆盖率口径）
|
||
|
||
| 文档 | 内容 |
|
||
|---|---|
|
||
| [`看门狗单元测试说明.md`](测试说明/单元测试/看门狗单元测试说明.md) | Task Watchdog 判定状态机（位图 / 掩码 / 节流 / tick 回绕），39 用例 |
|
||
| [`系统时钟单元测试说明.md`](测试说明/单元测试/系统时钟单元测试说明.md) | sys_clock 时间换算 / 星期 Zeller / 30 天惰性再基准化 / RTC 故障降级，100 断言点 |
|
||
| [`开机账本单元测试说明.md`](测试说明/单元测试/开机账本单元测试说明.md) | boot_stats 上电次数四态（不可信 / 首次启用 / 延续 / 电池域掉过电）/ SRAM 记录校验与格式版本 / I2C 失败分支 / 复位原因优先级链，21 断言点 |
|
||
| [`配置文件单元测试说明.md`](测试说明/单元测试/配置文件单元测试说明.md) | cfg_file INI 解析 / 值编解码 / load-save-poll 契约 / 超长守卫，149 断言点（含抓出的外科手术保存死码 P0） |
|
||
| [`ADC输入层单元测试说明.md`](测试说明/单元测试/ADC输入层单元测试说明.md) | adc_input 语义通道映射 / ADC1 顺序扫描（**Rank↔通道判据**）/ poll 契约 / HAL 故障路径，70 用例 |
|
||
| [`相量层单元测试说明.md`](测试说明/单元测试/相量层单元测试说明.md) | phasor 全周傅氏系数表 / 幅值·相位 / 谐波抑制与提取 / 频偏 / 采样环 / 双区交换，57 用例 |
|
||
| [`卷锁单元测试说明.md`](测试说明/单元测试/卷锁单元测试说明.md) | vol_lock 创建 / 获取 / 释放契约（**fail-open 不变量**：创建失败仍返回 1 且零阻塞）/ 幂等 / 超时透传，33 断言点 |
|
||
| [`时间同步单元测试说明.md`](测试说明/单元测试/时间同步单元测试说明.md) | time_sync 分片喂狗延时 / 监听退避 / 时间包重组 / 任务主循环（探针窗口心跳缺口的全部逻辑贡献者），80 断言点 |
|
||
| [`主机单测覆盖率口径.md`](测试说明/单元测试/主机单测覆盖率口径.md) | **跨全部 16 套 主机侧纯逻辑单测的覆盖率**：`scripts/check_test_coverage.py` 用法 / 统计面与生成物例外 / 基线增量门禁（只拦回退）/ **为什么本机拿不到分支覆盖** / 九条限制与盲区 / 未挂 pre-commit 的三条理由与待粘 YAML |
|
||
|
||
**板级测试/**（上板测试：模块测试指南 + 实机实施流程；动手写测试前先读）
|
||
|
||
| 文档 | 内容 |
|
||
|---|---|
|
||
| [`CH395F_Test_Guide.md`](测试说明/板级测试/CH395F_Test_Guide.md) | CH395F 以太网控制器（硬件层 Phase 1~5 / NET 层 Phase 6~11） |
|
||
| [`GD5F2GQ5UE_Test_Guide.md`](测试说明/板级测试/GD5F2GQ5UE_Test_Guide.md) | GD5F2GQ5UE SPI NAND 存储测试 |
|
||
| [`SD2506_Test_Guide.md`](测试说明/板级测试/SD2506_Test_Guide.md) | SD2506 RTC 测试 |
|
||
| [`FTP_Test_Guide.md`](测试说明/板级测试/FTP_Test_Guide.md) | FTP 服务测试 |
|
||
| [`实机测试实施指南.md`](测试说明/板级测试/实机测试实施指南.md) | **上板（真机）测试执行流程**（按顺序：环境预检 → `/serial-boot-test`+自检判定 → IWDG 注入/长跑 → 堆告警 → GD5F 错误通道 → 网络基线 → 工程卫生；每步含判据/命令/状态）；已完成事项证据去向见 §10 |
|
||
|
||
**专项验证/**（针对一个缺陷或一次复验的台架专项流程；做完即定稿）
|
||
|
||
| 文档 | 内容 |
|
||
|---|---|
|
||
| [`ADC前端注入验证流程.md`](测试说明/专项验证/ADC前端注入验证流程.md) | **ADC 前端与两片转换器的台架注入验证**（已知电压注入验证的执行侧，实测证据 → `docs/硬件平台/ADC通道映射说明.md` §8.1）：注入点清单 / 期望码值表 / 零点·线性·映射·极性·节奏五步（每步自带现场记录表，边做边填）；**不需示波器与信号源**，一块万用表即可 |
|
||
| [`启动日志原子性复验流程.md`](测试说明/专项验证/启动日志原子性复验流程.md) | **控制台整行独占 / 崩溃遗言原子性**这类**行级完整性**判据的固定动作与口径（`docs/子系统设计/控制台单写者日志设计说明.md` 的验收侧：那边讲怎么修，这边讲怎么证明修好了、以及为什么"标记全中"不等于"日志没坏"） |
|
||
| [`链路延迟测试说明.md`](测试说明/专项验证/链路延迟测试说明.md) | 网络链路时延分段定义、判定基线、执行流程 |
|
||
| [`模拟器差距清单.md`](测试说明/专项验证/模拟器差距清单.md) | **PC 模拟器 vs 真机差距登记册**（保护判据门禁可信度依据；改动涉及网络/日志/硬件层前必查 §3 决策规则） |
|
||
| [`存储维护与容量恢复.md`](测试说明/专项验证/存储维护与容量恢复.md) | 全片擦除恢复 dhara 坏块记账 / 容量恢复 |
|
||
|
||
**测试工具/**（PC 侧工具用法）
|
||
|
||
| 文档 | 内容 |
|
||
|---|---|
|
||
| [`串口助手使用指南.md`](测试说明/测试工具/串口助手使用指南.md) | 串口助手命令用法 / 工作流 / 排障 |
|
||
| [`串口助手设计说明.md`](测试说明/测试工具/串口助手设计说明.md) | 串口助手契约 / daemon 行为 / 陷阱 |
|
||
| [`ST-LINK_CLI_复位使用说明.md`](测试说明/测试工具/ST-LINK_CLI_复位使用说明.md) | 烧录 / 复位 / 回读校验（`ST-LINK_CLI` 完整用法） |
|
||
|
||
**测试数据/**（一手证据，**只增不改** → `docs/测试说明/README.md` §4）
|
||
|
||
| 目录 | 内容 |
|
||
|---|---|
|
||
| [`boot_log_data/README.md`](测试说明/测试数据/boot_log_data/README.md) | `/serial-boot-test` 产出的**开机串口日志快照**存档（跨构建 `[STACK]` 栈 / 堆水位对照，39 个文件） |
|
||
| [`m2_data/README.md`](测试说明/测试数据/m2_data/README.md) | 链路时延 M2 安静档采集数据（JSON + 串口 `[LAT]` 片段，含逐帧尾批明细与方法学约束） |
|
||
| `m3_data/` | 链路时延 M3 各档原始 JSON（quiet / stress / pending / 尾批实验；无独立 README，口径见 [`链路延迟测试说明.md`](测试说明/专项验证/链路延迟测试说明.md) 附表） |
|
||
|
||
> UI 相关测试见 [`UI设计/UI_自动化测试流程.md`](UI设计/UI_自动化测试流程.md)。
|
||
|
||
---
|
||
|
||
## 7. 代码规范 · 文档规范 · 内存管理 · 问题记录
|
||
|
||
### 7.1 代码规范（提交门禁相关）
|
||
|
||
| 文档 | 内容 |
|
||
|---|---|
|
||
| [`嵌入式C语言代码规范_V1.0.md`](代码规范/嵌入式C语言代码规范_V1.0.md) | 命名/格式/头文件/注释规范（含机械检查项） |
|
||
| [`pre-commit使用说明.md`](代码规范/pre-commit使用说明.md) | 提交门禁的部署、通用机制与范围口径（逐项详解见下行） |
|
||
| [`cppcheck使用说明.md`](代码规范/cppcheck使用说明.md) | cppcheck 配置与告警处置 |
|
||
| [`../门禁说明/README.md`](门禁说明/README.md) | **每个提交门禁一篇文档**：查什么、拦下过什么真事、**限制与盲区**、豁免与基线口径 |
|
||
|
||
### 7.1b 文档规范（写/改文档前必读）
|
||
|
||
| 文档 | 内容 |
|
||
|---|---|
|
||
| [`文档规范.md`](文档规范.md) | **文档体系强制约定**：目录/命名（无空格）、编码换行、链接形态（互链用根相对、图片用目录相对）、`[计划]` 标记、门禁三档、结构要素与常见错误速查 |
|
||
|
||
### 7.2 内存管理（**新增任务/缓冲/栈前必读**）
|
||
|
||
| 文档 | 内容 |
|
||
|---|---|
|
||
| [`RAM使用分析与优化方案.md`](内存管理/RAM使用分析与优化方案.md) | **内存主文档**：占用分析、优化方案、定栈规则 |
|
||
| [`内存内容分配策略.md`](内存管理/内存内容分配策略.md) | 各内存区（SRAM/CCM）的分配策略 |
|
||
| [`存储栈RAM优化调研.md`](内存管理/存储栈RAM优化调研.md) | 存储栈 RAM 优化调研与结论 |
|
||
| [`RAM预算台账.md`](内存管理/RAM预算台账.md) | **预算台账**：子系统配额、CCM 分配、趋势基线与 92% 门禁（登记簿条目「缩堆迁 CCM 后半（暂缓）」，2026-10-12） |
|
||
| `data/` | `ram_report_*.md` / `stack_report_*.md` 快照数据（由 `scripts/` 生成） |
|
||
|
||
### 7.3 问题记录（**改驱动前必读**）
|
||
|
||
| 文档 | 内容 |
|
||
|---|---|
|
||
| [`CH395F_Trap_Records.md`](问题记录/CH395F_Trap_Records.md) | CH395F 以太网控制器陷阱台账 |
|
||
| [`GD5F2GQ5UE_Trap_Records.md`](问题记录/GD5F2GQ5UE_Trap_Records.md) | GD5F2GQ5UE SPI NAND 陷阱台账 |
|
||
| [`SD2506_Trap_Records.md`](问题记录/SD2506_Trap_Records.md) | SD2506 RTC 陷阱台账 |
|
||
| [`ADC_Trap_Records.md`](问题记录/ADC_Trap_Records.md) | ADC1 采样链路陷阱台账（DMA 乒乓缓冲 +2 格相位旋转、RTOS 期校准被节拍打断；2026-10-27） |
|
||
| [`采集与数据处理短板评测.md`](问题记录/采集与数据处理短板评测.md) | 对照参考项目评测采集/遥测/录波/开入开出的完成度与缺口，给出补齐顺序（2026-10-23） |
|
||
|
||
---
|
||
|
||
## 8. UI 设计
|
||
|
||
| 文档 | 内容 |
|
||
|---|---|
|
||
| [`UI_设计架构.md`](UI设计/UI_设计架构.md) | UI 分层架构、LVGL 移植要点与踩坑（I1 palette 头、dark mono 主题） |
|
||
| [`菜单页面设计.md`](UI设计/菜单页面设计.md) | 菜单树与导航设计 |
|
||
| [`内容页架构.md`](UI设计/内容页架构.md) | 内容页组织与渲染 |
|
||
| [`UI_界面制作流程.md`](UI设计/UI_界面制作流程.md) | 界面制作 P0→P4 流程与 Gate 判据 |
|
||
| [`UI_中文字体生成与配置.md`](UI设计/UI_中文字体生成与配置.md) | 中文字库生成、子集化与配置 |
|
||
| [`UI_自动化测试流程.md`](UI设计/UI_自动化测试流程.md) | UI 模拟器像素回归（ui-verify 五步） |
|
||
| [`LVGL模拟器部署与使用说明.md`](UI设计/LVGL模拟器部署与使用说明.md) | PC 端 LVGL 模拟器部署与使用 |
|
||
| [`RemoDispBus协议与接收设计说明.md`](UI设计/RemoDispBus协议与接收设计说明.md) | 远端显示总线协议与接收设计 |
|
||
| [`页面补齐规划.md`](UI设计/页面补齐规划.md) | 27 个空叶子页面的归并、前置能力（数据快照层/数值编辑）与分批顺序（2026-10-23） |
|
||
| [`UI_数据供给设计说明.md`](UI设计/UI_数据供给设计说明.md) | 页面实时数据的高内聚低耦合方案：快照推送（rt/par 双通道）、写路径、记录 reader 注入（2026-10-23） |
|
||
| [`页面扩充详细方案.md`](UI设计/页面扩充详细方案.md) | 27 个空叶子 + 3 页回炉的逐页方案：行表、数据源、组件、分批与预算（2026-10-23） |
|
||
| `mockups/` | 各页面参考图与说明 |
|
||
|
||
---
|
||
|
||
## 9. 评审报告 · 环境与部署 · 外部资料
|
||
|
||
### 9.1 评审报告
|
||
|
||
> 体系层评审报告《项目审查与优化建议报告》（原在 `问题记录/`）已于 **2026-10-25 删除**——
|
||
> 大部分内容已闭环，留着的只有历史快照与重复清单。结论的去处：
|
||
> 未闭环项 → [`任务规划/登记簿.md`](任务规划/登记簿.md)；内存与 Flash 结论（含整簇暂缓的**重开条件**）
|
||
> → [`内存管理/RAM使用分析与优化方案.md`](内存管理/RAM使用分析与优化方案.md) §2.5 / §2.6.4 / §4；
|
||
> UI 侧硬约束 → [`UI设计/UI_设计架构.md`](UI设计/UI_设计架构.md) §1.4；
|
||
> 六个自有编号族（属主文档已删的那批）→ `scripts/archive/id_gate/编号治理历史.md` §4.5（只能删号留事实，别再引用那些号）。
|
||
### 9.2 环境与部署
|
||
|
||
| 文档 | 内容 |
|
||
|---|---|
|
||
| [`项目部署环境要求.md`](环境与部署/项目部署环境要求.md) | 开发机软件环境、目标板资源预算、现场部署与验收步骤 |
|
||
| [`并行任务工作树方案.md`](环境与部署/并行任务工作树方案.md) | **多任务并行开发机制**：`git worktree` 隔离、目录与共享/独占分配（junction 规则）、`task-worktree` SKILL 命令面（`@task` 仅为文档别名，显式调用 `/task-worktree`）、单写者文档与合并残留审计、台架锁；**已落地并端到端实测**（见其 §11） |
|
||
| [`CI/README.md`](CI/README.md) | **远程 CI（Gitea Actions）唯一入口**：服务端开关 / runner 部署与保活 / workflow / 排障。**只涉及本机一台 runner `win-stm32-ci`，其他机器与项目都不涉及**；日常改代码用本地门禁 `scripts/ci_local.py`，不必读这里 |
|
||
|
||
### 9.3 台账与外部资料
|
||
|
||
| 位置 | 内容 |
|
||
|---|---|
|
||
| [`任务规划/`](任务规划/README.md) | **统一待办入口（6 个文件）**：`README.md` = 现在做什么与全项目顺序；`UI补齐.md` = 当前唯一执行清单；`登记簿.md` = 后续任务、外部窗口与长期观察；`故障录波.md` = 录波的卡片与判据（1 kHz · 8 路原始码值 · 单通道回放）；`数据可信.md` = 采集数据可信度的五级台阶与任务卡（含手边可做的动态波形验证）+ 被代码引用的设计约束；`暂缓-RS485.md` = 暂缓专项（`测试与架构专项.md` 已删除 2026-10-28，未闭环约束并入 `暂缓-RS485.md`；`屏板链路.md` 已完成，转为 `子系统设计/屏板链路设计说明.md` 后删除）。完成即删，重复内容只保留一个归属 |
|
||
| `硬件平台/` | 网表详细分析报告与语义图（V0.0 / V0.1）；**[`ADC通道映射说明.md`](硬件平台/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`](架构设计/图形绘制流程.md)（`draw-diagram` skill），产物统一放 `images/`，脚本与 `.svg` 一并提交。
|
||
6. **门禁**：文档提交同样过 pre-commit（乱码 / 行尾空白 / gitlint + **文档链接存在性 `doc-links` / 任务表一致性 `task-table`**，见 [`文档规范.md`](文档规范.md) §4 与 [`代码规范/pre-commit使用说明.md`](代码规范/pre-commit使用说明.md)）。
|
||
|
||
> **目录/文件名一律不含空格**（2026-09-25 起强制）：空格会迫使脚本、链接、CI 处处加引号，
|
||
> 且 URL 编码形态（`UI%20设计`）易被漏改。现全库已无含空格目录。
|
||
|
||
---
|
||
|
||
## 11. 已知文档问题（待清理）
|
||
|
||
> 来源：原审查报告两条已销项（正文已移入 [`文档规范.md`](文档规范.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`](内存管理/RAM预算台账.md) + `mem-budget` 钩子 |
|
||
| ~~目录名含空格~~ | ~~`UI 设计/`~~ | ✅ 已修复（2026-09-25）：改名为 `UI设计/`，全仓库 67 处引用同步；命名约定见 [`文档规范.md`](文档规范.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`](文档规范.md) |
|
||
|
||
> 未闭环的文档类问题**只剩仓库膨胀**（登记簿条目「仓库体积膨胀观察」，已决策暂不处理）。
|