12451
7d2b57d021
docs: 澄清"唯一 TCP 协议文档"并隔离硬件总线协议；删除已完成任务、摘出未结待办
## 起因
用户提问：**"我们不是有一个 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/` 一行。
2026-09-20 04:55:28 +08:00
..
2026-09-20 04:55:28 +08:00
2026-09-20 04:55:28 +08:00