wandering1/STM32F4-Base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

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

Browse Source 
原「配置文件设计说明.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:
Wanderingss
2026-11-15 20:55:04 +08:00
parent 26293f5054
commit 007f6a0e2f
41 changed files with 501 additions and 719 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/images/配置文件分层架构.svg
+54 -52
View File
@@ -1,5 +1,5 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="952" viewBox="0 0 1200 952" font-family="Microsoft YaHei, Segoe UI, PingFang SC, sans-serif">
<rect x="0" y="0" width="1200" height="952" fill="#ffffff"/>
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="1048" viewBox="0 0 1200 1048" font-family="Microsoft YaHei, Segoe UI, PingFang SC, sans-serif">
<rect x="0" y="0" width="1200" height="1048" fill="#ffffff"/>
<text x="26" y="40" font-size="20" font-weight="700" fill="#0f172a">通用配置文件分层架构（/config.ini）</text>
<text x="26" y="62" font-size="13" fill="#64748b">INI 文本文件 · FTP 上传/下载 · 段键表引擎 · MCU/模拟器双端共享</text>
<rect x="26" y="78" width="1148" height="92" rx="12" fill="#f1f5f9" stroke="#475569" stroke-opacity="0.45"/>
@@ -9,60 +9,62 @@
<text x="225" y="139" font-size="13" fill="#1e293b" text-anchor="middle">文本编辑器：改 /config.ini（注释 / 加段 / 改值）</text>
<rect x="416" y="116" width="338" height="38" rx="8" fill="#ffffff" stroke="#475569" stroke-opacity="0.55"/>
<text x="586" y="139" font-size="13" fill="#1e293b" text-anchor="middle">FTP 客户端：RETR 下载 / STOR 上传（端口 21）</text>
<rect x="26" y="214" width="1148" height="92" rx="12" fill="#f5f3ff" stroke="#7c3aed" stroke-opacity="0.45"/>
<rect x="26" y="214" width="1148" height="140" rx="12" fill="#f5f3ff" stroke="#7c3aed" stroke-opacity="0.45"/>
<text x="44" y="240" font-size="17" font-weight="700" fill="#7c3aed">lftpd FTP 服务（端口 21）</text>
<text x="286" y="240" font-size="12" fill="#64748b">ftpTask · 单连接 · root = /（= 卷根）</text>
<rect x="44" y="252" width="388" height="38" rx="8" fill="#ffffff" stroke="#7c3aed" stroke-opacity="0.55"/>
<text x="238" y="275" font-size="13" fill="#1e293b" text-anchor="middle">RETR / STOR / LIST / DELE / CWD（lftpd 现状能力）</text>
<rect x="442" y="252" width="258" height="38" rx="8" fill="#ffffff" stroke="#7c3aed" stroke-opacity="0.55"/>
<text x="572" y="275" font-size="13" fill="#1e293b" text-anchor="middle">STOR = 原地覆盖（无 tmp+rename）</text>
<rect x="711" y="252" width="179" height="38" rx="8" fill="#ffffff" stroke="#7c3aed" stroke-opacity="0.55"/>
<text x="801" y="275" font-size="13" fill="#1e293b" text-anchor="middle">路径规范化封死 .. 穿越</text>
<rect x="26" y="350" width="1148" height="92" rx="12" fill="#f0fdfa" stroke="#0d9488" stroke-opacity="0.45"/>
<text x="44" y="376" font-size="17" font-weight="700" fill="#0d9488">/config.ini（通用配置文件）</text>
<text x="300" y="376" font-size="12" fill="#64748b">FatFS 卷根（NAND GD5F2GQ5UE · dhara FTL）</text>
<rect x="44" y="388" width="283" height="38" rx="8" fill="#ffffff" stroke="#0d9488" stroke-opacity="0.55"/>
<text x="185" y="411" font-size="13" fill="#1e293b" text-anchor="middle">INI 文本：[段] / key=value / ; 注释</text>
<rect x="337" y="388" width="257" height="38" rx="8" fill="#ffffff" stroke="#0d9488" stroke-opacity="0.55"/>
<text x="466" y="411" font-size="13" fill="#1e293b" text-anchor="middle">CRLF · UTF-8（容忍 BOM）· ≤ 4KB</text>
<rect x="604" y="388" width="394" height="38" rx="8" fill="#ffffff" stroke="#0d9488" stroke-opacity="0.55"/>
<text x="802" y="411" font-size="13" fill="#1e293b" text-anchor="middle">设备写：tmp + rename（原子）；变更识别：size + mtime</text>
<rect x="26" y="486" width="1148" height="140" rx="12" fill="#eff6ff" stroke="#2563eb" stroke-opacity="0.45"/>
<text x="44" y="512" font-size="17" font-weight="700" fill="#2563eb">cfg_file（配置文件引擎）</text>
<text x="271" y="512" font-size="12" fill="#64748b">App/cfg_file.c · 双端共享</text>
<rect x="44" y="524" width="325" height="38" rx="8" fill="#ffffff" stroke="#2563eb" stroke-opacity="0.55"/>
<text x="206" y="547" font-size="13" fill="#1e293b" text-anchor="middle">INI 解析 / 序列化（逐键校验 · 容错 · 自愈）</text>
<rect x="379" y="524" width="337" height="38" rx="8" fill="#ffffff" stroke="#2563eb" stroke-opacity="0.55"/>
<text x="547" y="547" font-size="13" fill="#1e293b" text-anchor="middle">外科手术式保存（保留注释 / 未知段 → 降级安全）</text>
<rect x="726" y="524" width="257" height="38" rx="8" fill="#ffffff" stroke="#2563eb" stroke-opacity="0.55"/>
<text x="855" y="547" font-size="13" fill="#1e293b" text-anchor="middle">2s 变更轮询（f_stat）+ 段变更回调</text>
<rect x="44" y="572" width="254" height="38" rx="8" fill="#ffffff" stroke="#2563eb" stroke-opacity="0.55"/>
<text x="171" y="595" font-size="13" fill="#1e293b" text-anchor="middle">出厂模板生成 · 旧 NCFG blob 迁移</text>
<rect x="26" y="670" width="1148" height="92" rx="12" fill="#f0fdf4" stroke="#16a34a" stroke-opacity="0.45"/>
<text x="44" y="696" font-size="17" font-weight="700" fill="#16a34a">段适配（键表）</text>
<text x="175" y="696" font-size="12" fill="#64748b">段 RAM 副本 = 模块静态结构体（稳态 0 增量）</text>
<rect x="44" y="708" width="361" height="38" rx="8" fill="#ffffff" stroke="#16a34a" stroke-opacity="0.55"/>
<text x="224" y="731" font-size="13" fill="#1e293b" text-anchor="middle">net_cfg [network]：ip / mask / gateway / mac</text>
<rect x="415" y="708" width="352" height="38" rx="8" fill="#ffffff" stroke="#16a34a" stroke-opacity="0.55"/>
<text x="591" y="731" font-size="13" fill="#1e293b" text-anchor="middle">未来：[adc] · [rs485] · [ftp] ...（三步接入）</text>
<rect x="26" y="806" width="1148" height="92" rx="12" fill="#fff1f2" stroke="#e11d48" stroke-opacity="0.45"/>
<text x="44" y="832" font-size="17" font-weight="700" fill="#e11d48">消费者</text>
<text x="107" y="832" font-size="12" fill="#64748b">读 / 写段 RAM 副本 + 应用</text>
<rect x="44" y="844" width="263" height="38" rx="8" fill="#ffffff" stroke="#e11d48" stroke-opacity="0.55"/>
<text x="175" y="867" font-size="13" fill="#1e293b" text-anchor="middle">netTask：组网 / 重建（代次号自愈）</text>
<rect x="317" y="844" width="320" height="38" rx="8" fill="#ffffff" stroke="#e11d48" stroke-opacity="0.55"/>
<text x="477" y="867" font-size="13" fill="#1e293b" text-anchor="middle">UI 网口设置页：显示 / 编辑 / 保存（零改动）</text>
<rect x="648" y="844" width="329" height="38" rx="8" fill="#ffffff" stroke="#e11d48" stroke-opacity="0.55"/>
<text x="813" y="867" font-size="13" fill="#1e293b" text-anchor="middle">未来模块：cfg_file_section_data() 取段数据</text>
<rect x="442" y="252" width="403" height="38" rx="8" fill="#ffffff" stroke="#7c3aed" stroke-opacity="0.55"/>
<text x="644" y="275" font-size="13" fill="#1e293b" text-anchor="middle">STOR 原地覆写（无 tmp+rename）：FTP 侧写入不受引擎保护</text>
<rect x="44" y="300" width="368" height="38" rx="8" fill="#ffffff" stroke="#7c3aed" stroke-opacity="0.55"/>
<text x="228" y="323" font-size="13" fill="#1e293b" text-anchor="middle">写权限受 [ftp] write 门控；路径规范化封死 .. 穿越</text>
<rect x="26" y="398" width="1148" height="92" rx="12" fill="#f0fdfa" stroke="#0d9488" stroke-opacity="0.45"/>
<text x="44" y="424" font-size="17" font-weight="700" fill="#0d9488">/config.ini（通用配置文件）</text>
<text x="300" y="424" font-size="12" fill="#64748b">FatFS 卷根（NAND GD5F2GQ5UE · dhara FTL）</text>
<rect x="44" y="436" width="283" height="38" rx="8" fill="#ffffff" stroke="#0d9488" stroke-opacity="0.55"/>
<text x="185" y="459" font-size="13" fill="#1e293b" text-anchor="middle">INI 文本：[段] / key=value / ; 注释</text>
<rect x="337" y="436" width="440" height="38" rx="8" fill="#ffffff" stroke="#0d9488" stroke-opacity="0.55"/>
<text x="557" y="459" font-size="13" fill="#1e293b" text-anchor="middle">设备写：/config.TMP → unlink 旧文件 → rename（引擎侧原子）</text>
<rect x="787" y="436" width="333" height="38" rx="8" fill="#ffffff" stroke="#0d9488" stroke-opacity="0.55"/>
<text x="954" y="459" font-size="13" fill="#1e293b" text-anchor="middle">变更识别：size + FAT 打包 mtime（2 s 粒度）</text>
<rect x="26" y="534" width="1148" height="140" rx="12" fill="#eff6ff" stroke="#2563eb" stroke-opacity="0.45"/>
<text x="44" y="560" font-size="17" font-weight="700" fill="#2563eb">cfg_file（配置文件引擎）</text>
<text x="271" y="560" font-size="12" fill="#64748b">App/cfg/cfg_file.c · 双端共享</text>
<rect x="44" y="572" width="344" height="38" rx="8" fill="#ffffff" stroke="#2563eb" stroke-opacity="0.55"/>
<text x="216" y="595" font-size="13" fill="#1e293b" text-anchor="middle">非破坏性解析 · 逐键校验 · 越界/坏值保持出厂默认</text>
<rect x="398" y="572" width="337" height="38" rx="8" fill="#ffffff" stroke="#2563eb" stroke-opacity="0.55"/>
<text x="567" y="595" font-size="13" fill="#1e293b" text-anchor="middle">外科手术式保存（保留注释 / 未知段 → 降级安全）</text>
<rect x="746" y="572" width="335" height="38" rx="8" fill="#ffffff" stroke="#2563eb" stroke-opacity="0.55"/>
<text x="913" y="595" font-size="13" fill="#1e293b" text-anchor="middle">2 s 轮询 + 4 s 沉降；视图一致性守卫拒绝坏视图</text>
<rect x="44" y="620" width="290" height="38" rx="8" fill="#ffffff" stroke="#2563eb" stroke-opacity="0.55"/>
<text x="189" y="643" font-size="13" fill="#1e293b" text-anchor="middle">出厂模板生成（段注册后按 RAM 副本渲染）</text>
<rect x="26" y="718" width="1148" height="140" rx="12" fill="#f0fdf4" stroke="#16a34a" stroke-opacity="0.45"/>
<text x="44" y="744" font-size="17" font-weight="700" fill="#16a34a">段适配（键表）</text>
<text x="175" y="744" font-size="12" fill="#64748b">段 RAM 副本 = 模块静态结构体（稳态 0 增量）</text>
<rect x="44" y="756" width="502" height="38" rx="8" fill="#ffffff" stroke="#16a34a" stroke-opacity="0.55"/>
<text x="295" y="779" font-size="13" fill="#1e293b" text-anchor="middle">8 段已满（= CFG_FILE_MAX_SECTIONS）：network / sntp / ftp / comm</text>
<rect x="556" y="756" width="371" height="38" rx="8" fill="#ffffff" stroke="#16a34a" stroke-opacity="0.55"/>
<text x="741" y="779" font-size="13" fill="#1e293b" text-anchor="middle">adc_cal / adc_cal_ofs / adc_cal_sec / run_par</text>
<rect x="44" y="804" width="361" height="38" rx="8" fill="#ffffff" stroke="#16a34a" stroke-opacity="0.55"/>
<text x="224" y="827" font-size="13" fill="#1e293b" text-anchor="middle">新增段 = 调一次 cfg_file_register()（三步接入）</text>
<rect x="26" y="902" width="1148" height="92" rx="12" fill="#fff1f2" stroke="#e11d48" stroke-opacity="0.45"/>
<text x="44" y="928" font-size="17" font-weight="700" fill="#e11d48">消费者</text>
<text x="107" y="928" font-size="12" fill="#64748b">读 / 写段 RAM 副本 + 应用</text>
<rect x="44" y="940" width="364" height="38" rx="8" fill="#ffffff" stroke="#e11d48" stroke-opacity="0.55"/>
<text x="226" y="963" font-size="13" fill="#1e293b" text-anchor="middle">netTask：组网 / 重建（[network] 唯一挂回调的段）</text>
<rect x="418" y="940" width="320" height="38" rx="8" fill="#ffffff" stroke="#e11d48" stroke-opacity="0.55"/>
<text x="579" y="963" font-size="13" fill="#1e293b" text-anchor="middle">UI 网口设置页：显示 / 编辑 / 保存（零改动）</text>
<rect x="749" y="940" width="397" height="38" rx="8" fill="#ffffff" stroke="#e11d48" stroke-opacity="0.55"/>
<text x="948" y="963" font-size="13" fill="#1e293b" text-anchor="middle">默认任务：cfg_file_poll(); 模块按需 cfg_file_save()</text>
<line x1="600.0" y1="176.0" x2="600.0" y2="199.0" stroke="#94a3b8" stroke-width="2.5"/>
<path d="M 600.0 206.0 l -6 -9 h 12 z" fill="#94a3b8"/>
<line x1="600.0" y1="312.0" x2="600.0" y2="335.0" stroke="#94a3b8" stroke-width="2.5"/>
<path d="M 600.0 342.0 l -6 -9 h 12 z" fill="#94a3b8"/>
<line x1="600.0" y1="448.0" x2="600.0" y2="471.0" stroke="#94a3b8" stroke-width="2.5"/>
<path d="M 600.0 478.0 l -6 -9 h 12 z" fill="#94a3b8"/>
<line x1="600.0" y1="632.0" x2="600.0" y2="655.0" stroke="#94a3b8" stroke-width="2.5"/>
<path d="M 600.0 662.0 l -6 -9 h 12 z" fill="#94a3b8"/>
<line x1="600.0" y1="768.0" x2="600.0" y2="791.0" stroke="#94a3b8" stroke-width="2.5"/>
<path d="M 600.0 798.0 l -6 -9 h 12 z" fill="#94a3b8"/>
<text x="26" y="934" font-size="12" fill="#94a3b8">稳态 RAM 零增量（段数据 = 模块既有结构体）；暂态堆缓冲 ≤9KB（仅 load/save 时）；FF_FS_REENTRANT=1 卷锁串行化多任务 FS 访问；模拟器端 = 宿主文件 sim_config.ini（同核心）</text>
<line x1="600.0" y1="360.0" x2="600.0" y2="383.0" stroke="#94a3b8" stroke-width="2.5"/>
<path d="M 600.0 390.0 l -6 -9 h 12 z" fill="#94a3b8"/>
<line x1="600.0" y1="496.0" x2="600.0" y2="519.0" stroke="#94a3b8" stroke-width="2.5"/>
<path d="M 600.0 526.0 l -6 -9 h 12 z" fill="#94a3b8"/>
<line x1="600.0" y1="680.0" x2="600.0" y2="703.0" stroke="#94a3b8" stroke-width="2.5"/>
<path d="M 600.0 710.0 l -6 -9 h 12 z" fill="#94a3b8"/>
<line x1="600.0" y1="864.0" x2="600.0" y2="887.0" stroke="#94a3b8" stroke-width="2.5"/>
<path d="M 600.0 894.0 l -6 -9 h 12 z" fill="#94a3b8"/>
<text x="26" y="1030" font-size="12" fill="#94a3b8">稳态 RAM 零增量（段数据 = 模块既有结构体）；暂存缓冲 9,217 B（4KB 读入 + 5KB 输出，仅 load/save 时）；FF_FS_REENTRANT=1 卷锁串行化多任务 FS 访问；模拟器端 = 宿主文件 sim_config.ini（同核心）</text>
</svg>
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 7.3 KiB

After

Width:  |  Height:  |  Size: 7.7 KiB