# 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` 移入 `问题记录/`，删除 `审查记录/` 目录；全仓库引用同步 |