docs(cfg): 配置设计档重写为现状版,删除旧二进制档叙述

原「配置文件设计说明.md」是 2026-09 的规划文档(P1~P8 实施计划、D1~D15
决策表、差距调研、模块清单动作列、已终结的开放问题),与现在跑的系统
已有明显出入。改写成只描述当前状态的「配置文件设计.md」。

新文档 9 节:概览 / 文件格式(路径与容量、语法、出厂模板原文、值类型)/
运行时机制(上电加载、外科手术式保存、2s 轮询与沉降、视图一致性守卫、
写者归属)/ 段与键表(8 段全满、注册顺序、接入新段模板、段回调)/
接口(引擎 API、平台后端)/ 内存占用(编译期钉死的 9217B 暂存)/
异常与恢复 / 双端差异 / 已知限制。

顺带修正一处事实错误:旧文档称 FTP STOR 是「写 .TMP 再 rename 原子更新」,
实际 lftpd receive_file 是原地覆写,已按代码现状改写。

旧二进制档(NCFG)的叙述按裁定从全仓移除:文档只描述当前状态,不再
交代旧版本兼容性。删掉网络配置说明 §3.2 整节(后续小节重排为 3.2~3.5),
并清理 README / 架构总览 / 产品需求 / 部署环境等 11 处同类叙述。

同步:
- 8 段注册、FTP 原地覆写、2s FAT mtime 粒度等数据更新进配置分层架构图,
  重跑后与生成器逐字节一致,check_generated_fresh 里这条存量基线下架
- 全仓 24 处引用改用新文档名,旧节号逐条映射到新节号
- 文档规范 §7.1 变更记录例外名单 4 篇减为 3 篇(该档实际无变更记录表)

验证:48 个提交期钩子全通过;Keil 构建 0 错误 0 警告;
check_doc_links / check_mermaid / check_generated_fresh 均通过。
This commit is contained in:
2026-11-15 20:55:04 +08:00
parent 26293f5054
commit 007f6a0e2f
41 changed files with 501 additions and 719 deletions
+1 -1
View File
@@ -19,7 +19,7 @@
| `项目架构总览.svg` | `gen_arch_svg.py` | 六层分层结构与跨层依赖——「谁在哪一层」(不含数据流边、不含片外硬件) | `LAYERS` / `ROWS` / `FOOT` | `docs/架构设计/软件架构与运行时规格.md`:14、`docs/架构设计/项目架构总览.md`:11 |
| `架构总览_端到端链路.svg` | `gen_arch_endtoend_svg.py` | 端到端链路鸟瞰——一个电气量从引脚走到 104 报文 / 显存 / 记录文件**穿过谁、与谁在什么时候换锁**;42 框 37 边 5 条纵带,线型分数据 / 命令 / 屏障心跳 | `NODES`(id / 列 / 行 / 标题 / 副题)+ `EDGES`(出入框方位与 `f` / `g` / `my` / `gx` 旋钮)+ `BANDS`;三条独占通道 `CHAN_B` / `CHAN_78` / `CHAN_SLOTS` 与走廊 `GUT_C4C5` 在几何区 | `docs/架构设计/项目架构总览.md`:53 |
| `就绪屏障.svg` | `gen_barrier_svg.py` | Event Flags 屏障模型:位 → 生产者 → 消费者三栏对齐,哪些位真在用、哪些是预留 | `BITS` / `PRODUCERS` / `CONSUMERS` / `FOOT` | `docs/架构设计/软件架构与运行时规格.md`:63、`docs/架构设计/项目启动顺序管理.md`:48、`docs/架构设计/项目架构总览.md`:85 |
| `配置文件分层架构.svg` | `gen_cfg_arch_svg.py` | 配置引擎分层与持久化:谁解析 `[section]`、落盘走哪条链 | `ROWS` 分层清单 + 标题 / 脚注文案 | `docs/产品需求/产品需求设计文档.md`:331、`docs/子系统设计/配置文件设计说明.md`:144 |
| `配置文件分层架构.svg` | `gen_cfg_arch_svg.py` | 配置引擎分层与持久化:谁解析 `[section]`、落盘走哪条链 | `ROWS` 分层清单 + 标题 / 脚注文案 | `docs/产品需求/产品需求设计文档.md`:331、`docs/子系统设计/配置文件设计.md`:144 |
| **采集与算法** | | | | |
| `ADC前端电路.svg` | `gen_adc_frontend_svg.py` | 端子 → 串阻 → 转换节点 → 转换器引脚;含差分负端与 STM32 侧对照 | `SUB1` / `NOTE_*` 等文案常量 + 面板坐标(电路拓扑固定,网表变了才重画) | `docs/测试说明/专项验证/ADC前端注入验证流程.md`:31、`docs/硬件平台/ADC通道映射说明.md`:161 |
| `ADC码值刻度.svg` | `gen_adc_code_scale_svg.py` | 「码」的直观定义:两片转换器的刻度尺对照(16 位双极性 vs 12 位单极性) | `PANELS`(码范围 / LSB / 实测码标记位置)+ `FOOT`(换芯片才重画) | `docs/测试说明/专项验证/ADC前端注入验证流程.md`:104 |
+14 -13
View File
@@ -3,7 +3,7 @@
"""生成 docs/images/配置文件分层架构.svg —— 通用配置文件(/config.ini)分层架构图(纯标准库,无需第三方依赖)。
由 gen_net_stack_svg.py 复制改数据区:配置体系六层结构
(docs/子系统设计/配置文件设计说明.md §4.1):
(docs/子系统设计/配置文件设计.md §3.5):
PC 端(编辑器/FTP 客户端)→ lftpd FTP 服务 → /config.ini 文件 → cfg_file 引擎 → 段适配(键表)→ 消费者。
用法(仓库根目录,任意 python3):
@@ -49,32 +49,33 @@ L_PC = dict(
L_FTP = dict(
title="lftpd FTP 服务(端口 21)", sub="ftpTask · 单连接 · root = /(= 卷根)", color="#7c3aed", bg="#f5f3ff",
chips=["RETR / STOR / LIST / DELE / CWD(lftpd 现状能力)",
"STOR = 原地覆盖(无 tmp+rename)",
"路径规范化封死 .. 穿越"],
"STOR 原地覆写(无 tmp+rename):FTP 侧写入不受引擎保护",
"写权限受 [ftp] write 门控;路径规范化封死 .. 穿越"],
)
L_FILE = dict(
title="/config.ini(通用配置文件)", sub="FatFS 卷根(NAND GD5F2GQ5UE · dhara FTL)", color="#0d9488", bg="#f0fdfa",
chips=["INI 文本:[段] / key=value / ; 注释",
"CRLF · UTF-8(容忍 BOM)· ≤ 4KB",
"设备写:tmp + rename(原子);变更识别:size + mtime"],
"设备写:/config.TMP → unlink 旧文件 → rename(引擎侧原子)",
"变更识别:size + FAT 打包 mtime(2 s 粒度)"],
)
L_ENGINE = dict(
title="cfg_file(配置文件引擎)", sub="App/cfg/cfg_file.c · 双端共享", color="#2563eb", bg="#eff6ff",
chips=["INI 解析 / 序列化(逐键校验 · 容错 · 自愈)",
chips=["非破坏性解析 · 逐键校验 · 越界/坏值保持出厂默认",
"外科手术式保存(保留注释 / 未知段 → 降级安全)",
"2s 变更轮询(f_stat)+ 段变更回调",
"出厂模板生成 · 旧 NCFG blob 迁移"],
"2 s 轮询 + 4 s 沉降;视图一致性守卫拒绝坏视图",
"出厂模板生成(段注册后按 RAM 副本渲染)"],
)
L_SECT = dict(
title="段适配(键表)", sub="段 RAM 副本 = 模块静态结构体(稳态 0 增量)", color="#16a34a", bg="#f0fdf4",
chips=["net_cfg [network]:ip / mask / gateway / mac",
"未来:[adc] · [rs485] · [ftp] ...(三步接入)"],
chips=["8 段已满(= CFG_FILE_MAX_SECTIONS):network / sntp / ftp / comm",
"adc_cal / adc_cal_ofs / adc_cal_sec / run_par",
"新增段 = 调一次 cfg_file_register()(三步接入)"],
)
L_CONS = dict(
title="消费者", sub="读 / 写段 RAM 副本 + 应用", color="#e11d48", bg="#fff1f2",
chips=["netTask:组网 / 重建(代次号自愈)",
chips=["netTask:组网 / 重建([network] 唯一挂回调的段)",
"UI 网口设置页:显示 / 编辑 / 保存(零改动)",
"未来模块:cfg_file_section_data() 取段数据"],
"默认任务:cfg_file_poll(); 模块按需 cfg_file_save()"],
)
# 每一行可放多个"同级并列"的层(上层只依赖下方各层)
@@ -87,7 +88,7 @@ ROWS = [
[L_CONS],
]
FOOT = "稳态 RAM 零增量(段数据 = 模块既有结构体);暂态堆缓冲 ≤9KB(仅 load/save 时);FF_FS_REENTRANT=1 卷锁串行化多任务 FS 访问;模拟器端 = 宿主文件 sim_config.ini(同核心)"
FOOT = "稳态 RAM 零增量(段数据 = 模块既有结构体);暂存缓冲 9,217 B(4KB 读入 + 5KB 输出,仅 load/save 时);FF_FS_REENTRANT=1 卷锁串行化多任务 FS 访问;模拟器端 = 宿主文件 sim_config.ini(同核心)"
# ----------------------------- 工具函数 -----------------------------