From 75c234b0c2260335e63b8cc2b99ff9a0fd07880a Mon Sep 17 00:00:00 2001 From: Wanderingss <1624155937@qq.com> Date: Sun, 4 Oct 2026 02:34:40 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=A1=B9=E7=9B=AE=E5=AE=A1=E6=9F=A5?= =?UTF-8?q?=E6=8A=A5=E5=91=8A=E7=A7=BB=E5=85=A5=20=E9=97=AE=E9=A2=98?= =?UTF-8?q?=E8=AE=B0=E5=BD=95/=EF=BC=8C=E5=88=A0=E9=99=A4=E7=A9=BA?= =?UTF-8?q?=E7=9A=84=20=E5=AE=A1=E6=9F=A5=E8=AE=B0=E5=BD=95/=20=E7=9B=AE?= =?UTF-8?q?=E5=BD=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 让评审报告与 待处理内容.md 的分工更直观： - git mv 项目审查与优化建议报告.md → docs/问题记录/（与 Trap 台账、 错误码传播审计同处"专项审计"目录）；rmdir 空的 docs/审查记录/。 - docs/README.md：§8 标题改为「评审报告 · 环境与部署 · 外部资料」， §8.1 改为「评审报告」，目录树删 审查记录/、补 问题记录/ 说明， 按角色导航改为 §8.1/§8.3，补 2026-10-04 变更记录。 - 根 README.md 目录树同步。 - docs/文档规范.md §1.1 现有目录列表、§6 归属表同步。 - 看门狗设计说明.md / 待处理内容.md 的路径引用重定向。 pre-commit 17/17 Passed。 --- README.md | 5 ++--- docs/README.md | 18 +++++++++--------- docs/子系统设计/看门狗设计说明.md | 4 ++-- docs/待处理内容.md | 6 +++--- docs/文档规范.md | 6 +++--- .../项目审查与优化建议报告.md | 0 6 files changed, 19 insertions(+), 20 deletions(-) rename docs/{审查记录 => 问题记录}/项目审查与优化建议报告.md (100%) diff --git a/README.md b/README.md index 091a43bb..8c7b6754 100644 --- a/README.md +++ b/README.md @@ -167,15 +167,14 @@ STM32F4-Base/ │ └── time_sync_server.py # 时间同步推送服务 ├── docs/ # 项目文档（全量索引见 docs/README.md） │ ├── README.md # 文档索引：目录结构 + 推荐阅读顺序 + 全量清单 -│ ├── 待处理内容.md # 跨文档待办登记簿 +│ ├── 待处理内容.md # 统一待办登记簿 │ ├── 架构设计/ # 项目架构总览 / 存储架构 / 启动顺序 / 配图流程 / 引用关系图 │ ├── 子系统设计/ # 配置 / 网络 / 墙钟 / 日志 / 运行自检记录 设计说明 │ ├── 网络/ # BSD Socket API 使用指南 + 内部函数调用关系 │ ├── 测试说明/ # 测试标准流程、各模块测试指南、串口助手、烧录复位 │ ├── 代码规范/ # C 代码规范、pre-commit / cppcheck 使用说明 │ ├── 内存管理/ # RAM 使用分析与优化方案 + 快照数据（data/） -│ ├── 问题记录/ # 各模块 Trap Records 与专项审计 -│ ├── 审查记录/ # 项目审查报告与审计改进清单 +│ ├── 问题记录/ # 各模块 Trap Records、专项审计与项目评审报告 │ ├── 环境与部署/ # 环境搭建与部署核对清单 │ ├── UI设计/ # LVGL UI：架构 / 菜单页面 / 制作流程 / 字体 / 模拟器 / 自动化测试 + mockups │ ├── 硬件平台/ # 网表分析报告与语义图 diff --git a/docs/README.md b/docs/README.md index 2da5595e..8e23de82 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ # docs/ 文档索引 -> **定位**：本目录是 STM32F4-Base 项目的**工程文档库**——架构设计、子系统设计、测试规范、审查记录与外部资料。 +> **定位**：本目录是 STM32F4-Base 项目的**工程文档库**——架构设计、子系统设计、测试规范、问题记录（含专项审计与评审报告）与外部资料。 > **权威入口**：日常开发以仓库根 `AGENTS.md`（面向 AI/开发者）为第一入口；本文档提供**人类可读的全量索引与推荐阅读顺序**。 > **约定**：目录名不含空格；新增文档必须登记到本索引（见文末「新增文档约定」）。 @@ -19,8 +19,7 @@ docs/ ├── 代码规范/ 编码规范与静态检查门禁 ├── 文档规范.md 本文档体系的规范（命名/链接/门禁/结构） ├── 内存管理/ RAM 预算、分配策略与优化调研 -├── 问题记录/ 模块陷阱台账与专项审计 -├── 审查记录/ 项目审查报告与改进清单 +├── 问题记录/ 模块陷阱台账、专项审计与项目评审报告 ├── 环境与部署/ 环境搭建与部署核对清单 ├── UI设计/ UI 架构、页面设计、字体与模拟器 ├── 硬件平台/ 网表分析报告与语义图 @@ -29,7 +28,7 @@ docs/ ``` > ⚠️ `docs/芯片手册/`（约 120 MB / 1754 张图）为**只读外部输入资料**，与代码演进无关； -> 后续按《项目审查与优化建议报告》D-1 建议拆分独立仓库或降采样（见 `审查记录/项目审查与优化建议报告.md`）。 +> 后续按《项目审查与优化建议报告》D-1 建议拆分独立仓库或降采样（见 `问题记录/项目审查与优化建议报告.md`）。 --- @@ -51,7 +50,7 @@ docs/ - **应用/驱动开发** → §3 架构设计 → §4 子系统设计 → §6 问题记录（**改驱动前必读对应 Trap Records**） - **测试/验证** → §5 测试说明 → §2 环境与部署 - **UI 开发** → §7 UI 设计 → §5 测试说明（串口助手、UI 自动化测试流程） -- **接手/评审** → §8 审查记录 → §5 待处理内容 +- **接手/评审** → §8.1 评审报告 → §8.3 待处理内容（统一待办登记簿） --- @@ -178,13 +177,13 @@ docs/ --- -## 8. 审查记录 · 环境与部署 · 外部资料 +## 8. 评审报告 · 环境与部署 · 外部资料 -### 8.1 审查记录 +### 8.1 评审报告 | 文档 | 内容 | |---|---| -| [`项目审查与优化建议报告.md`](审查记录/项目审查与优化建议报告.md) | 项目全景审查：文档/代码/架构/可靠性问题清单（D-1~D-7、N-xx、Px-xx） | +| [`问题记录/项目审查与优化建议报告.md`](问题记录/项目审查与优化建议报告.md) | 项目全景审查：文档/代码/架构/可靠性问题清单（D-1~D-7、N-xx、Px-xx）——**体系层评审报告，非待办池**（待办见 §8.3 `待处理内容.md`） | ### 8.2 环境与部署 @@ -231,7 +230,7 @@ docs/ | ~~缺一致性门禁~~ | — | ✅ 已落地（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.3。 +> 完整清单与建议见 [`问题记录/项目审查与优化建议报告.md`](问题记录/项目审查与优化建议报告.md) §3.3。 --- @@ -244,3 +243,4 @@ docs/ | 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` | 正式确立文档体系规范（目录命名/编码换行/链接形态/门禁/结构/写作约定）；补入本索引 §6.1b | +| 2026-10-04 | 待办文档合并 + 报告归档 | 4 份待办文档（`待处理内容.md` / `项目审计改进清单.md` / `下一步任务规划.md` / `测试与架构改进建议.md`）合并为**统一待办登记簿** `待处理内容.md`；`项目审查与优化建议报告.md` 移入 `问题记录/`，删除 `审查记录/` 目录；全仓库引用同步 | diff --git a/docs/子系统设计/看门狗设计说明.md b/docs/子系统设计/看门狗设计说明.md index 78417c92..45ac72c3 100644 --- a/docs/子系统设计/看门狗设计说明.md +++ b/docs/子系统设计/看门狗设计说明.md @@ -8,7 +8,7 @@ > V4 关中断死循环每 ~4.9s 稳定复位、V5 30 min 真实负载 120/120 FTP PASS 零复位。 > **日期**：2026-09-29（2026-10-03 台架验收） > **相关文档**： -> [`../审查记录/项目审查与优化建议报告.md`](../审查记录/项目审查与优化建议报告.md)（N-03 缺陷原始登记）、 +> [`../问题记录/项目审查与优化建议报告.md`](../问题记录/项目审查与优化建议报告.md)（N-03 缺陷原始登记）、 > [`../待处理内容.md`](../待处理内容.md)（排期）、 > [`运行与自检记录设计说明.md`](运行与自检记录设计说明.md)（§5.3 上电/重启分类）、 > [`../架构设计/项目启动顺序管理.md`](../架构设计/项目启动顺序管理.md)（就此绪屏障）、 @@ -1083,7 +1083,7 @@ python scripts/check_cubemx_survival.py --write # 重建基线（确认改动 | `App/task/default_task.c:95-204` | bring-up 深链、主循环 50 ms 基准 | | `App/sync/time_sync.c:68/75` | `vTaskDelay(2000)` 与监视窗口冲突 | | `Src/freertos.c:242-250` | `ftpTask` 在屏障上 `osWaitForever` 阻塞 | -| `docs/审查记录/项目审查与优化建议报告.md` §4.1 | N-03a/b/c 缺陷原始登记与建议 | +| `docs/问题记录/项目审查与优化建议报告.md` §4.1 | N-03a/b/c 缺陷原始登记与建议 | ## 附录 B：备选方案取舍记录 diff --git a/docs/待处理内容.md b/docs/待处理内容.md index 0fa18c98..ed468f5e 100644 --- a/docs/待处理内容.md +++ b/docs/待处理内容.md @@ -9,8 +9,8 @@ > 已闭环项的**结论与证据沉淀进对应模块文档/问题记录**，本文件不再重复。 > **消化即销项**：事项修复/关闭后，直接删除对应条目，并同步清理其它文档对本编号的引用。 > -> **不在本文件范围**：`错误码传播审计.md`（E-xx，问题记录/审计报告，非待办池）、 -> `项目审查与优化建议报告.md`（体系层评审报告）、`测试说明/实机测试实施指南.md`（执行流程）。 +> **不在本文件范围**：`问题记录/错误码传播审计.md`（E-xx，审计报告，非待办池）、 +> `问题记录/项目审查与优化建议报告.md`（体系层评审报告）、`测试说明/实机测试实施指南.md`（执行流程）。 > > **创建**：2026-09-22（L3 pending 台架收尾）；**合并重写**：2026-10-04。 @@ -404,5 +404,5 @@ S14 已在 workflow 显式提示"体积门禁未执行"（`::notice::`）并在 - 编号一律**沿用且不回收**（P-x / N-x / S-x / T-x / S1x / A-x）；`错误码传播审计.md` 的 E-xx 独立维护。 - 阶段 B 完成后重写 §1（届时 ADC/RS485 应从未闭环消失）。 - 新增发现按既有惯例分流：能立即修的进 §2 阶段 A/C5；需排期的进 §3 对应编号空间；跨版本观察的进 §3.4。 -- 上游引用关系：`项目审查与优化建议报告.md`（体系层评审）、`错误码传播审计.md`（E-xx）、 +- 上游引用关系：`问题记录/项目审查与优化建议报告.md`（体系层评审）、`问题记录/错误码传播审计.md`（E-xx）、 `测试说明/实机测试实施指南.md`（执行流程）——三者均不在本文件合并范围。 diff --git a/docs/文档规范.md b/docs/文档规范.md index cd48d94c..e5cf1e0a 100644 --- a/docs/文档规范.md +++ b/docs/文档规范.md @@ -14,7 +14,7 @@ |---|---| | **目录名一律不含空格** | 空格迫使脚本/链接/CI 处处加引号，且 URL 编码形态（`UI%20设计`）极易被漏改（D-6，2026-09-25 起强制；全库已无含空格目录） | | **按领域归入子目录** | 顶层不放散落 `.md`；新领域先建无空格子目录，再在 [`README.md`](README.md) 登记 | -| 现有目录 | `架构设计/` `子系统设计/` `网络/` `测试说明/` `代码规范/` `内存管理/` `问题记录/` `审查记录/` `环境与部署/` `UI设计/` `硬件平台/` `芯片手册/` `images/` | +| 现有目录 | `架构设计/` `子系统设计/` `网络/` `测试说明/` `代码规范/` `内存管理/` `问题记录/` `环境与部署/` `UI设计/` `硬件平台/` `芯片手册/` `images/` | ### 1.1b 代码目录的 README.md @@ -229,8 +229,8 @@ | 项目级铁律、构建/烧录/测试命令、平台约束 | `AGENTS.md`（AI 协作上下文，**精简优先**） | | 开发者入门、架构速览、目录导航 | `README.md` | | 详细设计、专项说明、测试指南 | `docs/` 下对应子目录 | -| 跨文档待办登记 | `docs/待处理内容.md` | -| 审查发现与改进方案 | `docs/审查记录/` | +| 跨文档待办登记 | `docs/待处理内容.md`（统一登记簿） | +| 评审报告与专项审计 | `docs/问题记录/` | > **避免重复**：同一事实只在一处详述，其它位置用链接指向。典型如 FreeRTOS 任务表——`Src/freertos.c` 是唯一事实源，`README.md`/`AGENTS.md` 的表由脚本生成，不在别处再抄一份。 diff --git a/docs/审查记录/项目审查与优化建议报告.md b/docs/问题记录/项目审查与优化建议报告.md similarity index 100% rename from docs/审查记录/项目审查与优化建议报告.md rename to docs/问题记录/项目审查与优化建议报告.md