7d2b57d021
## 起因 用户提问：**"我们不是有一个 tcp 协议权威文档了吗？为啥还有其他 tcp 协议文档"** —— 查证后确认：**权威文档只有一份**，但目录布局让人容易误判，且**我上一轮的搬迁引入了一处断链**。 ## 一、查证结果：全仓只有一份 TCP 协议文档 按"是否同时出现 `auth_str`/`status_post`/`bat_in` 等 act 名"全仓扫描，含协议内容的只有： | 文件 | act 命中 | 性质 | |---|---:|---| | `docs/protocol/柜控板固件对接文档.md` | 171 | ⭐ **唯一权威 TCP 协议规格** | | `docs/tech/API.md` | 14 | HTTP 接口文档，TCP 章节**只有一句指回权威文档的链接** | | `AGENTS.md` / `数据模型.md` / `小程序用户端.md` | 13 / 8 / 3 | 规则与存储说明，非协议规格 | | `docs/archive/项目深度分析报告-2026-07-06.md` | 1 | 历史归档 | ⇒ **没有任何第二份 TCP 协议文档。** 用户看到的"另一份"应是下面二者之一（都已处理）： ### 1. `docs/protocol/1TN协议标准_*` —— **不是 TCP 协议** 它是**仓控板 ↔ 翌工电源的 RS485 总线协议**（另一条物理链路）。与 TCP 权威文档同放 `protocol/`，名字又像"协议标准"，极易被当成第二份平台协议。 **已移到新目录 `docs/hardware/`**（硬件侧总线协议），并在两处都写明"**不是**平台 TCP 协议"。 **结果：`docs/protocol/` 下有且仅有一个文件** —— 一眼就能确认"只有一份"。 ### 2. `tasks/001-TCP协议对齐与安全修复.md`（66 KB）—— 是任务记录，不是协议文档 文件名含"TCP协议"，且 66 KB。它已被完整处理（见下节）。 ## 二、删除已完成的任务文件，并摘出真正的未结待办 `tasks/` **已 gitignore（`.gitignore:27`），是本地草稿区、从不入库**。 `tasks/001` 的 A~AH **全部 ✅ 已完成**，但其**状态头写着"待排期（未开始编码）"** —— 是错的。 按「已完成的任务文件及时清理」，**已删除**；删前把**唯一两项未结**摘成 `tasks/002-未结待办-协议待确认项与长函数重构.md`： 1. **`energy` 数据源待硬件答复**（协议待确认第 13 项，阻塞中）+ 关联的第 16 项； 2. **长函数重构**（已授权未开工）。 > ⚠️ **顺带纠正 001 的两处数字**（实测后才发现，**不能沿用**）： > - 001 记"23 个函数超 80 行"—— **当前实测只有 8 个**（本会话多轮重构已拆掉大部分）； > - 001 记 `migrate.rs::run` 已从 280 拆到 **46 行** —— **拆分本身没被回退** > （`SCHEMA_SQL` 确在 L20、`run` 内 0 个 `CREATE TABLE`），但后续每轮迁移改动都往 `run` 里追加 > （`LEGACY_COLUMN_TARGETS` 对齐、`ensure_active_order_unique`、列注释对齐……）， > **它又长回 174 行，重新成为全仓最长函数** —— 这是一次**重构回归**，已列为第一优先。 > - 实测脚本随 002 一起留在 `tasks/`（该目录不入库，避免下次重新发明）。 ## 三、修复我上一轮搬迁引入的断链（1 处真缺陷 + 1 处机械替换误伤） 搬迁脚本只覆盖了 `docs/<name>` 与 `../<name>` 两种形态，**没覆盖三种情况**，已全部修好并加了体检： | 位置 | 问题 | 修复 | |---|---|---| | `docs/tech/API.md` | 同级相对链接 `](柜控板固件对接文档.md)` 因文件被移走而断链 | → `](../protocol/柜控板固件对接文档.md)` | | `docs/tech/数据模型.md` | 我的替换把 **markdown 链接目标** `](docs/API.md)` 也换成了 `docs/tech/API.md` ⇒ 解析成 `docs/tech/docs/tech/API.md` | 显示文字保留可读路径，**链接目标改回 `API.md`** | | `docs/archive/审查报告…md` | 指向当时已删除的 `./tcp-protocol.md`（历史事实） | 归档**保留原文**，顶部加**归档横幅 + 旧名→现名映射表** | **新增体检方法并实测能发现问题**：遍历 `docs/**/*.md` 的所有相对链接、逐个还原路径判存在性。 修完后复跑 → 只剩归档那一处（按设计保留），已用横幅给出映射。 > 📌 教训（已写进 `docs/README.md` 维护约定）：**移动文档后必须做链接体检**， > 不能只做字符串替换 —— 同级相对链接、以及"写在链接目标里的仓库相对路径"都会被漏掉。 ## 四、文档地图同步更新 `docs/README.md` 新增： - 顶部**「关于到底有几份 TCP 协议文档」**专节：直接回答，并列出"三份内部件何时被删"的历史； - `hardware/` 目录说明； - `protocol/` 明确标注 **⛔ 不要在这里放第二份协议文档**（要补充就改那一份并升版本号）。 `AGENTS.md` 项目结构同步加 `hardware/` 一行。
226 KiB
226 KiB