wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 30 Pull Requests Actions Packages Projects 2 Releases Wiki Activity
Files
0f0d002afcd4d62dcc2d7794c2c13716ec14893b
STM32F4-Base/docs/README.md
T
wandering1 0f0d002afc docs(ADC): 采样节拍设计说明只留现状，历史决策与台架记录移出 
删除（已确定的决策与过程记录，无现状信息量）
- §2 方案选型（方案 A 推荐 / 方案 B 备选与结论）
- §9 变更记录整表（9 行"已实现 / 已验收 / 已落地 / 复核修正"叙事）
- §7.1、§10.3、§11.5 三张台架实测对照表 + 反向验证记录 + boot_log 证据行
- 用户决策与过程编号（Task #32 P1-5 方案 a、B1、P0-1/P0-2、v2.0/v2.2/v2.7/v2.8、
  "规划未预见""原规划写错了"更正叙事）
- §4 代码改造清单（改造已完成）与 §8 / §10.5 的后续规划口吻

保留并补齐现状
- 链路总览（新增 TIM3 同源 Mermaid）· 实现落点表 · TIM3 配置与"为什么是 TIM3"
  （F4 触发清单是硬约束）· ADC1 + DMA 四条硬约束与半区无竞态推导 · 上电自校准
  · TPAFE 侧契约与原子快照 · 就绪门与节拍缺失 fail-safe · 单周期时序
  · 心跳计数逐个判读（含相位伪影为何阈值取 2）· 性能与资源特征
  · 设计边界与已知代价（N-18 无同刻性、滞后一拍、TPAFE 未 DMA 化的前提未定、
  调频能力现状）· 设计铁律
- 468 -> 344 行

顺带修掉文档自相矛盾
- 原 §3 / §4 仍在教人配 TIM6（§11 已改 TIM3）-> 全文统一 TIM3
- 上位需求引用写成 继电保护功能复现规划.md §3.2，实际 L1-1 在 §3.1

连带引用同步（7 文件 8 处）
- App/algo/adc_input.c -> §8；App/task/adc_task.c -> §6；Src/main.c -> §3.3；
  Src/freertos.c -> §9 与 §10（顺带纠正已失效的"ADC 2 ms 忙等"表述，DMA 化后
  单拍取数已零忙等）
- 看门狗设计说明 §6 与 §9 / §4.4；ADC通道映射说明 §4 与 §6；
  继电保护功能复现规划 §3.2
- 其中 2 处活断链 doc-links --all 抓不到（整行含"已消""已实现"状态词被豁免），
  另写脚本按「文档名 + 章节号」全库扫出后修复

门禁
- doc-links --all（非 SDL2 问题 0，可判定 57% -> 58%）与 --sections-strict 通过
- no-mojibake / trailing-whitespace / end-of-file-fixer / id-check 通过；
  task-table / mem-numbers 一致；@build 0 错误 0 警告
- 改动文件均无 BOM、无 CR、U+FFFD = 0；CubeMX 文件的注释改动都落在 USER CODE 区
2026-10-21 11:39:52 +08:00

291 lines
28 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 张图）为**只读外部输入资料**，与代码演进无关；
> 后续按《项目审查与优化建议报告》D-1 建议拆分独立仓库或降采样（见 `问题记录/项目审查与优化建议报告.md`）。
---
## 2. 推荐阅读顺序
新成员/新接手者按此顺序，可在最短时间内建立全局认知：
| 顺序 | 文档 | 读它能得到什么 |
|:---:|---|---|
| 1 | [`产品需求设计文档.md`](产品需求/产品需求设计文档.md) | 产品定位、功能/非功能需求、接口规范、UI 规格、路线图与验收判据 |
| 2 | [`项目架构总览.md`](架构设计/项目架构总览.md) | 六层分层、启动时序、存储/网络/UI 三栈、目录组织 |
| 3 | [`项目启动顺序管理.md`](架构设计/项目启动顺序管理.md) | Event Flags 就绪屏障（取代魔法延时）的任务启动模型 |
| 4 | [`项目部署环境要求.md`](环境与部署/项目部署环境要求.md) | 开发机/目标板/现场部署的完整环境核对清单 |
| 5 | [`项目部署环境要求.md`](环境与部署/项目部署环境要求.md) → 构建 | 跑通 `@build` / `@test`（见根 `AGENTS.md`） |
| 6 | [`测试开发标准流程.md`](测试说明/测试开发标准流程.md) | 测试分层 L0~L3 与门禁决策表 |
| 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) | **面向产品的需求基线**：产品定位与形态、六层架构与任务模型、V0.1 硬件规格、功能需求（网络/存储/时间/配置/日志/UI/看门狗/LED + 待实现的 ADC/RS-485）、接口规范（RemoDispBus / 对时 / FTP / 配置 / 串口）、非功能需求（可靠性/性能/内存/门禁/双端）、UI 规格、待实现项与路线图、验收判据 |
---
## 4. 架构设计
| 文档 | 内容 |
|---|---|
| [`项目架构总览.md`](架构设计/项目架构总览.md) | 系统全景：六层分层、启动时序、存储·网络·UI 栈、目录组织 |
| [`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]` 实测基线**（Task #32 沉淀：判读口径、量化归因、三条脆弱点、明确不做的四条） |
| [`ADC采样节拍设计说明.md`](子系统设计/ADC采样节拍设计说明.md) | **ADC 采集链路采样节拍（现状说明）**：TIM3 1 kHz 更新事件同时触发 TPAFE CONVST 与（经 TRGO）STM32 ADC1 + DMA 乒乓缓冲；节拍源为什么是 TIM3、DMA 硬约束、事件驱动消费与就绪门、实现落点、观测计数、性能特征与设计边界 |
| [`IEC104上行设计说明.md`](子系统设计/IEC104上行设计说明.md) | **B4 上行规约**：IEC 60870-5-104 被控站（TCP 2404）范围/点表（V0.1 有效子集）/链路流程（k/w/t1~t3、总召、COV、遥控两段式、定值）/netTask 接入决策/预算与测试方案；协议核心纯逻辑 + L0.5 全栈单测 |
| [`网络/BSD_Socket_API_使用指南.md`](网络/BSD_Socket_API_使用指南.md) | **上层视图**：BSD Socket API 公开语义、示例、常见问题 |
| [`网络/BSD_Socket_API_函数调用关系.md`](网络/BSD_Socket_API_函数调用关系.md) | **内部视图**：netTask / 消息队列 / L3 挂起 / 重试对账的调用关系与设计意图 |
| [`网络/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) | **保护功能复现规划**：把参考系统（CLS100）保护链路映射到本项目（STM32F4）的分层功能/性能/参数清单、平台适配（N-18 等）与分阶段路线图 |
---
## 6. 测试说明
**总流程与规范**
| 文档 | 内容 |
|---|---|
| [`测试开发标准流程.md`](测试说明/测试开发标准流程.md) | 测试开发总流程：规划→板端套件→主机工具→门禁→沉淀；门禁决策表 |
| [`自动化测试流程.md`](测试说明/自动化测试流程.md) | `@test` 闭环细节：命令 / 串口标记 / 失败模式 |
| [`测试文档模板规范.md`](测试说明/测试文档模板规范.md) | 测试文档模板与命名规则（TM / TC / DP） |
| [`链路延迟测试说明.md`](测试说明/链路延迟测试说明.md) | 网络链路时延分段定义、判定基线、执行流程 |
| [`模拟器差距清单.md`](测试说明/模拟器差距清单.md) | **PC 模拟器 vs 真机差距登记册**（L3 门禁可信度依据；改动涉及网络/日志/硬件层前必查 §3 决策规则） |
| [`实机测试实施指南.md`](测试说明/实机测试实施指南.md) | **上板（真机）测试执行流程**（按顺序：环境预检 → `@test`+自检判定 → IWDG 注入/长跑 → 堆告警 → GD5F 错误通道 → 网络基线 → 工程卫生；每步含判据/命令/状态）；已完成事项证据去向见 §10 |
**主机侧单元测试（L0.5）**
| 文档 | 内容 |
|---|---|
| [`看门狗单元测试说明.md`](测试说明/看门狗单元测试说明.md) | Task Watchdog 判定状态机（位图 / 掩码 / 节流 / tick 回绕），39 用例 |
| [`系统时钟单元测试说明.md`](测试说明/系统时钟单元测试说明.md) | sys_clock 时间换算 / 星期 Zeller / 30 天惰性再基准化 / RTC 故障降级，100 断言点 |
| [`配置文件单元测试说明.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 分片喂狗延时 / 监听退避 / 时间包重组 / 任务主循环（**N-17 的全部逻辑贡献者**），80 断言点 |
**模块测试指南**（动手写测试前先读）
| 文档 | 内容 |
|---|---|
| [`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) | 串口助手命令用法 / 工作流 / 排障 |
| [`串口助手设计说明.md`](测试说明/串口助手设计说明.md) | 串口助手契约 / daemon 行为 / 陷阱 |
| [`ST-LINK_CLI_复位使用说明.md`](测试说明/ST-LINK_CLI_复位使用说明.md) | 烧录 / 复位 / 回读校验（`ST-LINK_CLI` 完整用法） |
| [`存储维护与容量恢复.md`](测试说明/存储维护与容量恢复.md) | 全片擦除恢复 dhara 坏块记账 / 容量恢复 |
| [`m2_data/README.md`](测试说明/m2_data/README.md) · `m3_data/` | 链路时延测试采集数据（JSON 原始记录） |
> 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 配置与告警处置 |
### 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% 门禁（N-27 三件套，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 陷阱台账 |
---
## 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) | 远端显示总线协议与接收设计 |
| `mockups/` | 各页面参考图与说明 |
---
## 9. 评审报告 · 环境与部署 · 外部资料
### 9.1 评审报告
| 文档 | 内容 |
|---|---|
| [`问题记录/项目审查与优化建议报告.md`](问题记录/项目审查与优化建议报告.md) | 项目全景审查：文档/代码/架构/可靠性问题清单（未闭环项：D-1、N-xx、Px-xx；**已修复项按「修复即销项」删除**，去处见其变更记录）——**体系层评审报告，非待办池**（待办见 `任务规划/README.md`） |
### 9.2 环境与部署
| 文档 | 内容 |
|---|---|
| [`项目部署环境要求.md`](环境与部署/项目部署环境要求.md) | 开发机软件环境、目标板资源预算、现场部署与验收步骤 |
| [`并行任务工作树方案.md`](环境与部署/并行任务工作树方案.md) | **多任务并行开发机制**：`git worktree` 隔离、目录与共享/独占分配（junction 规则）、`task-worktree`（`@task`）SKILL 命令面、单写者文档与合并残留审计、台架锁；**已落地并端到端实测**（见其 §11） |
| [`CI/README.md`](CI/README.md) | **远程 CI（Gitea Actions）唯一入口**：服务端开关 / runner 部署与保活 / workflow / 排障。**只涉及本机一台 runner `win-stm32-ci`，其他机器与项目都不涉及**；日常改代码用本地门禁 `scripts/ci_local.py`，不必读这里 |
### 9.3 台账与外部资料
| 位置 | 内容 |
|---|---|
| [`任务规划/`](任务规划/README.md) | **统一待办登记簿（文件夹）**——`README.md` = 排序权威（波次 W1~W7）+ 编号空间 + 维护约定；`W1-采集保护收尾.md` = 当前波次任务卡（里程碑 × 并行道 × 五字段）；`登记簿.md` = N/S/T-x 长期观察；`排期详述.md` / `暂缓-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)）。
> **目录/文件名一律不含空格**（D-6，2026-09-25 起强制）：空格会迫使脚本、链接、CI 处处加引号，
> 且 URL 编码形态（`UI%20设计`）易被漏改。现全库已无含空格目录。
---
## 11. 已知文档问题（待清理）
> 来源：《项目审查与优化建议报告》D-3/D-7（两条已销项，正文已移入 [`文档规范.md`](文档规范.md) 与 pre-commit 门禁）。
> **D-3 / D-6 / D-7 已处理完毕**（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，N-27 前半）：`ram_baseline.py` + `ram_baseline.tsv` + [`RAM预算台账.md`](内存管理/RAM预算台账.md) + `mem-budget` 钩子 |
| ~~目录名含空格~~ | ~~`UI 设计/`~~ | ✅ 已修复（2026-09-25，D-6）：改名为 `UI设计/`，全仓库 67 处引用同步；命名约定见 [`文档规范.md`](文档规范.md) §1 |
| ~~缺一致性门禁~~ | — | ✅ 已落地（2026-09-25/26，D-7 三档齐）：`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) |
> 未闭环的文档类问题见 [`问题记录/项目审查与优化建议报告.md`](问题记录/项目审查与优化建议报告.md) §3.1（体量）与 §3.3/§3.4（**仅剩 D-1 仓库膨胀**，登记簿 N-29 已决策暂不处理）。
---
## 12. 变更记录
| 日期 | 变更 | 说明 |
|---|---|---|
| 2026-10-14 | 网络文档合并 | 《网络Socket监听生命周期设计说明.md》（B10 根治，587 行）并入 [`网络/网络自愈架构设计.md`](网络/网络自愈架构设计.md)：原理与规范层论证 → §1.1~§1.4、FUN_PARA bit3 契约 → §4.9、代码级事实清点 → §9、决策记录 → §10、`net_listener.c` 模块化边界 → §11，原「引用与归档约定」顺延为 §12；过程类内容（分阶段勾选清单、台架验收记录）不迁、留 git 历史；原文档删除。全库引用同步 13 处（`net_listener.c`/`.h` 注释、Net层阻塞模型、BSD_Socket_API 两篇、陷阱记录 B10、编号规范 §4.2/§5.2/§7.2）；本索引 §5.1 补登记 |
| 2026-10-14 | E14"丢中断"复核与归因更正 | 48 轮直读 SINT 矩阵复核历史"丢中断"说法：**芯片侧事件丢失 = 0**（"丢失"= drain 读清消费 3/48 + 门控竞态 2/48 + 主机同步 1/48，幽灵态 0/48 未复现）；根除性修复 = listen/relisten 路径排事件挪至 LISTEN 命令**之前**（吞新会话 CONNECT 的生产侧自伤窗）；全局读收口（全局寄存器唯一读者=`net_poll`，I7 护栏）；全库 17 文件约 40 处"丢中断"归因更正为"事件未收到/读清消费竞态"，`docs/网络/网络自愈架构设计.md` §5.2 新增 E14 锚点；台架保留复核探针（drain-int/SINT 补读×3/超时归类）；同日 E15 幽灵态归因复核（官网+手册实锤：0x04+旧端口 = 芯片**如实报告**旧连接拆链进行中——bit3=1 保留现场为自家配置、拆链窗与 §5.17 重传默认值吻合、WCH 官方博客确认断连即重连被拒且官方方案 = 关闭完成后重开，即 settle 等待） |
| 2026-10-13 | 网络自愈架构文档瘦身与改名 | 合并文档 `网络/N34-自愈审计.md`（2062 行审计全记录）瘦身为**终版设计描述**（281 行：不变量 I1~I8 / 架构与机制详解 / 参数与 E 锚点速查 / 红线 / 延后项），并经 `rename_ref.py` 改名 [`网络/网络自愈架构设计.md`](网络/网络自愈架构设计.md)（全库 16 文件 30 处引用同步）；审计过程（T1~T4、E0~E13）归档 git 历史，考古命令见该文档「引用与归档约定」 |
| 2026-10-13 | 网络自愈审计归档 | 原 `docs/网络/N34-自愈审计/` 目录 7 份文档（根因总览 / net 层盘点 / 驱动层审计 / 主流对照 / 汇总裁决 / 实施方案 / 实验方案）**合并为单文档 [`网络/网络自愈架构设计.md`](网络/网络自愈架构设计.md)**，原目录删除；全库引用同步（`docs/` 4 篇 + 驱动/网络代码注释 + 配图生成器与 SVG）。本索引 §5.1 补登记 |
| 2026-10-12 | 新增环境与部署 | 新建 `docs/环境与部署/并行任务工作树方案.md`（**多任务并行开发机制规格**：`git worktree` 隔离、目录与共享/独占分配、`task-worktree` / `@task` skill 设计、单写者文档与合并残留审计、台架锁；**已落地并端到端实测**）；本索引 §9.2 补登记 |
| 2026-10-12 | 远程 CI 文档独立成目录 | 新建 `docs/CI/`：原散在 4 处的远程 CI 内容（`环境与部署/CI配置指南.md` 477 行 + `环境与部署/Gitea_Runner部署指南.md` 917 行 + `测试开发标准流程.md` §9 + `AGENTS.md` 提交门禁节 4 条，共约 2000 行）**合并为 `CI/远程CI完整指南.md` 一篇**，`CI/README.md` 作唯一入口；`AGENTS.md` 压成一行指针、测试流程 §9 只留覆盖边界与本地等价。动因：远程 CI **只跑在本机一台 runner**，与日常开发规范混在一起每次会话都被读，造成困惑 |
| 2026-10-11 | 功能 | N-19 FTP 鉴权：`/config.ini` 新增 `[ftp]` 段（`user` / `pwd_hash` = SHA-256(user‖password) / `write`）+ 恒定时间比较 + 连续 5 次失败锁 60 s + 未登录命令门；出厂默认 admin/admin，默认口令在用有启动告警。新增 `App/util/sha256.*`、`Drivers/BSP/NETCFG/ftp_cfg.*`、`Drivers/BSP/NET/lftpd/lftpd_auth.*`；主机侧单测 `test/host/sha256/`（13 例）+ `test/host/ftp_auth/`（36 例），pre-commit 钩子 26→28；台架脚本 `test/host/ftp_auth_bench.py`。文档同步：`docs/子系统设计/网络配置说明.md`、`docs/架构设计/STM32F4-Base存储架构说明.md`、`docs/代码规范/pre-commit使用说明.md`、`docs/产品需求/产品需求设计文档.md` |
| 2026-10-11 | 文档调整 | `AGENTS编写指南.md` 新建后**同日删除**（要点已沉淀入 `AGENTS.md` 宏观重构与本索引变更记录，指南类内容不单独成文）；撤销 §1 目录树与 §7.1b 登记；同日 `AGENTS.md` 完成宏观重构（补项目概况/目录地图、平台约束分组、边界块） |
| 2026-10-10 | 新增子系统设计 | 新建 `docs/子系统设计/ADC采样节拍设计说明.md`（ADC 采集链路 1 kHz 硬件定时器触发的 CubeMX 配置规格与代码改造清单，B1 遗留项规划）；本索引 §5.1 补登记 |
| 2026-10-10 | 新增算法专题 | 新建 `docs/算法/继电保护功能复现规划.md`（保护链路复现总规划）；本索引 §1 目录树补 `算法/`、§5 拆为 5.1 功能子系统 / 5.2 算法专题并登记 `算法/` 两篇文档 |
| 2026-10-05 | 新增产品需求文档 | 新建 `docs/产品需求/产品需求设计文档.md`（面向产品的需求基线）；本索引新增 §3 产品需求、§2 推荐阅读顺序置顶、§1 目录树补 `产品需求/`；后续章节号顺延（本文 §4 … 本文 §12） |
| 2026-09-25 | 目录重组 + 索引建立 | 顶层 16 篇散落 md 归入 5 个新目录（`架构设计/` `子系统设计/` `网络/` `审查记录/` `环境与部署/`）；全仓库 90 处引用同步；新建本索引（D-5） |
| 2026-09-25 | D-6 目录去空格 | `docs/UI 设计/` → `docs/UI设计/`；全仓库 67 处引用同步（含 URL 编码形态 `UI%20设计`）；命名约定写入 §10 |
| 2026-09-25 | D-7 文档-代码一致性门禁 | 新建 `scripts/check_doc_links.py`（链接存在性，含行内代码豁免/就近状态词/`[计划]` 标记）、`scripts/gen_task_table.py`（任务表由 `Src/freertos.c` 生成/校验，锚点 `TASK_TABLE:BEGIN/END`）；接入 pre-commit `doc-links`/`task-table` 钩子；全库 66 文档 0 失效 |
| 2026-09-26 | D-7 体积档落地 | 新建 `scripts/check_mem_numbers.py`（内存/Flash 数字以 `.map` 为事实源，锚点 `MEM_SNAPSHOT:BEGIN/END` + 陈旧散句数字扫描）；接入 pre-commit `mem-numbers` 钩子；上线即抓出 6 处真实失真（RW_IRAM1 82,048→87,040、ROM 249,432→262,660 等） |
| 2026-09-25 | 新建 `文档规范.md` | 正式确立文档体系规范（目录命名/编码换行/链接形态/门禁/结构/写作约定）；补入本索引 §7.1b |
| 2026-10-04 | 待办文档合并 + 报告归档 | 4 份待办文档（`待处理内容.md` / `项目审计改进清单.md` / `下一步任务规划.md` / `测试与架构改进建议.md`）合并为**统一待办登记簿** `待处理内容.md`；`项目审查与优化建议报告.md` 移入 `问题记录/`，删除 `审查记录/` 目录；全仓库引用同步 |
Reference in New Issue View Git Blame Copy Permalink