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/` 一行。

AGENTS.md

@@ -30,8 +30,9 @@ D:\charging-cabinet\
 ├── tasks/              # 任务文件（opencode执行）
 ├── docs/               # 📖 **文档地图见 docs/README.md**（按用途分类，勿再平铺）
 │   ├── README.md       # 文档索引：分类、权威性、旧名→现名映射、维护约定
-│   ├── protocol/       # 设备协议（冻结，对硬件交付）→ 柜控板固件对接文档.md ⭐唯一权威
+│   ├── protocol/       # 平台设备协议 → **只有 1 份**：柜控板固件对接文档.md ⭐唯一权威 TCP 协议
 │   ├── tech/           # 平台技术文档 → API.md / 数据模型.md / 部署手册.md / 小程序用户端.md
+│   ├── hardware/       # 硬件侧总线协议（RS485，**不是**平台 TCP 协议）→ 1TN协议标准_*
 │   ├── contract/       # 合同·规格·验收标准（商务依据，不描述实现）
 │   ├── compound-notes/ # 单点经验笔记（参考性）
 │   └── archive/        # ⛔ 历史留痕（只读，不代表现状，不可作依据）

docs/README.md

@@ -7,14 +7,29 @@
 
 | 目录 | 定位 | 权威性 | 谁该读 |
 |------|------|--------|--------|
-| [`protocol/`](#protocol设备协议) | **设备协议**（冻结，对硬件工程师交付） | ⭐ **唯一权威** | 硬件工程师、固件、平台 TCP 相关开发 |
+| [`protocol/`](#protocol设备协议) | **平台设备协议**（TCP，冻结，对硬件工程师交付） | ⭐ **唯一权威** | 硬件工程师、固件、平台 TCP 相关开发 |
 | [`tech/`](#tech平台技术文档) | **平台技术文档**（开发/运维必读） | ⭐ 权威（各自领域内） | 后端/前端/运维 |
+| [`hardware/`](#hardware硬件侧总线协议) | **硬件侧总线协议**（RS485，**不是**平台 TCP 协议） | 硬件事实依据 | 硬件工程师、对接电源/BMS 的人 |
 | [`contract/`](#contract合同与规格) | **合同、规格、验收标准**（商务依据） | 事实依据，但不描述实现 | PM、验收方、新人了解范围 |
 | [`compound-notes/`](#compound-notes经验沉淀) | **单点经验笔记**（踩坑/技法） | 参考，非权威 | 遇到同类问题的人 |
 | [`archive/`](#archive历史归档) | **历史留痕**（只读，**不代表现状**） | ⛔ **不可作为依据** | 追溯历史决策时 |
 
 ## 二、谁是权威（口径优先级，避免"两份文档谁对"的扯皮）
 
+> ### ⚠️ 关于"到底有几份 TCP 协议文档"
+>
+> **全仓只有一份**：`docs/protocol/柜控板固件对接文档.md`。
+> `docs/protocol/` 目录下**有且仅有这一个文件** —— 这是刻意的，便于一眼确认。
+>
+> 历史上曾有三份内部件，已在协议 v1.1 前后删除（用户指示：只保留一份权威）：
+> `docs/tcp-protocol.md`、`docs/TCP报文交互示例.md`、`docs/柜控板-平台TCP接口文档.md`。
+>
+> 若你看到的"另一份 TCP 协议"是下面这些，它们**都不是平台 TCP 协议**：
+> - `docs/hardware/1TN协议标准_*` —— **RS485 总线协议**（仓控板 ↔ 翌工电源），另一条物理链路；
+> - `docs/tech/API.md` 的「TCP 设备通讯协议」章节 —— 只有一句**指回权威文档的链接**，不重复内容；
+> - `tasks/*.md` —— 任务草稿（**`tasks/` 已 gitignore，不入库**），文件名可能含"TCP协议"
+>   但那是任务记录，不是规格。
+
 1. **`protocol/柜控板固件对接文档.md`** —— 设备协议（帧格式 / `act` / 字段名 / 签名 / `id` 规则）
    的**唯一权威**。协议**冻结**，设备端固件不可改。
 2. **根目录 `AGENTS.md`** —— **平台侧实现口径**的权威：Redis 键与字段、接口行为、库结构、
@@ -25,14 +40,25 @@
 
 ## 三、逐目录说明
 
-### protocol/ —— 设备协议
+### protocol/ —— 平台设备协议（**只有一份**）
 
 | 文件 | 说明 |
 |------|------|
 | `柜控板固件对接文档.md` | **唯一权威 TCP 文档**（v1.1.1）。帧格式、通用规则（`act`/`suc`/`msg_id`/60 秒超时/登录门控）、指令清单、签名算法与自测向量、安全码自愈、带注释报文示例（附 A）、变更记录（附 B）。**既是内部文档也可直接对外交付。** |
-| `1TN协议标准_YG20240118-1_V1.0.md` | 仓控板 ↔ 电源（苏州翌工）1TN RS485 协议文本版 |
+
+⛔ **不要在这里放第二份协议文档**（哪怕是"内部稿""示例集""补充说明"）——
+历史上正是这样分叉出三份，最后对不上。要补充内容就**改这一份并升版本号**（记入它的「附 B」）。
+
+### hardware/ —— 硬件侧总线协议
+
+| 文件 | 说明 |
+|------|------|
+| `1TN协议标准_YG20240118-1_V1.0.md` | 仓控板 ↔ 电源（苏州翌工）1TN RS485 协议，文本版 |
 | `1TN协议标准_苏州翌工电源_V1.0.pdf` | 同上，厂家原始 PDF |
 
+> ⚠️ 这是**另一条物理链路**（柜内 485 总线），**与平台 TCP 协议无关** ——
+> 别把它当成"第二份 TCP 协议"。硬件侧的其它总线协议（BMS：星恒 Modbus / 天能 485）如需入库，也放这里。
+
 ### tech/ —— 平台技术文档
 
 | 文件 | 说明 | 入口 |

docs/archive/审查报告-数据单位一致性-2026-07-06.md

@@ -1,3 +1,16 @@
+> ## ⛔ 本文是**历史归档**（2026-07-06），**不代表现状，不可作为依据**
+>
+> 结论、路径、字段名都是**当时**的。文中引用的旧文档名与现名对应关系：
+>
+> | 文中旧名 | 现位置 |
+> |---|---|
+> | `docs/tcp-protocol.md` | `docs/protocol/柜控板固件对接文档.md`（**唯一权威**，已升到 v1.1.1） |
+> | `docs/API.md` | `docs/tech/API.md` |
+> | `docs/开发文档.md` | `docs/archive/开发文档.md` |
+>
+> 当前口径一律以 **`AGENTS.md`**（平台侧实现）+ **`docs/protocol/柜控板固件对接文档.md`**（设备协议）为准。
+> 文档分类总览见 `docs/README.md`。
+
 # 数据单位审查报告 — 充电柜项目
 
 **日期：** 2026-07-06

docs/tech/API.md

@@ -1108,7 +1108,8 @@ Nginx 有独立的 `/api/wechat/` location 直连 API 服务，不经 `/api/pms/
 
 ## TCP 设备通讯协议
 
-> TCP 设备通讯协议见 **[柜控板固件对接文档.md](柜控板固件对接文档.md)**（唯一权威，v1.1）。本文不再重复。
+> TCP 设备通讯协议见 **[docs/protocol/柜控板固件对接文档.md](../protocol/柜控板固件对接文档.md)**
+> （**唯一权威**，v1.1.1）。**本文不再重复协议内容** —— 全仓只有这一份 TCP 协议规格文档。
 
 ---
 

docs/tech/数据模型.md

@@ -159,7 +159,7 @@ bit6 热失控｜**bit7 有电池**（决定"空仓/在位"）。
 > 旧文档那张"空闲/插入/充电中/充满/故障"五态表**已废弃**：它既不是协议口径，
 > 也无法表达"电池在位但未充电"（`batt_status` bit7=1、bit0/bit1=0）这类真实状态。
 
-**API 接口（接口总表以 [docs/tech/API.md](docs/tech/API.md) 为准，这里只列与 Redis 存储强相关的两个）：**
+**API 接口（接口总表以 [docs/tech/API.md](API.md) 为准，这里只列与 Redis 存储强相关的两个）：**
 
 | 接口 | 说明 | Redis 查询方式 |
 |------|------|----------------|