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

6.3 KiB

Raw Blame History

换电柜用锂电池充电器 1TN 标准通信协议 RS485

标准号：YG20240118-1
版本：V1.0
制定方：苏州翌工电源科技有限公司
适用范围：换电柜 1TN 多路充电器 RS485 总线通信

版本记录

版本	修改内容	时间	修改人
S1.0	初步建立1TN RS485协议内容	2024-01-18	Eleven

1. 概述

换电柜 1TN 多路充电器支持通过 RS485 总线进行通信，通信协议为客户自定义协议，采用 Modbus-RTU 传输模式，波特率 9600。

Modbus-RTU 传输模式在一根通讯线上采用主从应答方式的通讯连接方式。由主机发起，主机的信号寻址到一台唯一地址的终端设备（从机），然后终端设备发出的应答信号以相反的方向传输给主机，即半双工的工作模式。该协议只允许在主机和终端设备之间通讯，而不允许独立的终端设备之间的数据交换，这样各终端设备不会在它们初始化时占据通讯线路，而仅限于响应到达本机的查询信号。

1.1 通讯格式

信息传输为异步方式，并以字节为单位，在主机和从机之间传递的通讯信息是 11 位的字格式。包含 1 个起始位(0)，8 个数据位和 1 个停止位。

1.2 信息帧格式

字段	字节数	说明
ADDR	1	地址码
CHx	1	通道码
CMD	1	功能码
LEN	1	数据区长度
DATA	LEN	数据区（BigEndian 网络字节序）
SUM	1	校验码 = (ADDR + CHx + CMD + LEN + DATA) 按字节相加取低8位

1.3 通讯过程

信息发送至从机时，从机接收通讯命令，如果 SUM 校验无误则执行相应的操作，然后把执行结果（数据）返送给主机。返回的信息中包括 Header、CMD、ATS、执行后的数据以及 SUM 校验码和 END。如果校验出错就不返回任何信息，则分析返回相应的错误信息。

2. 地址码（ADDR）

对应电源拨码开关。

双拨码开关：01→0x01, 10→0x02, 11→0x03
3位拨码开关：001→0x01, 010→0x02, 011→0x03, 100→0x04, 101→0x05, 110→0x06, 111→0x07

3. 通道码（CHx）

对应各个通道识别码。

通道	Bit1-7	CHx值（Bit0=0主通道）	CHx值（Bit0=1副通道）
CH1	0x00	0x00	0x01
CH2	0x01	0x02	0x03
CH3	0x02	0x04	0x05
CH4	0x03	0x06	0x07
CH5	0x04	0x08	0x09
CH6	0x05	0x0A	0x0B

4. 功能码（CMD）

序号	命令	CMD	LEN	备注
1	设置通道输出电压/电流	0x02	0x04
2	设置通道开关机	0x03	0x01
3	通道组合指令（开关机/调压/调流）	0x04	0x05
4	电源通道信息查询	0x05	0x01
5	供应商电源型号/版本号/序列号查询	0x12	0x01
6	升级状态查询	0x18	NC	详见升级协议
7	OTA 远程升级	0x19	NC	详见升级协议

5. 故障码

故障字节1

Bit	含义	Bit	含义
Bit0	输入欠压	Bit4	输出欠压
Bit1	输入过压	Bit5	输出短路
Bit2	NC	Bit6	输出过流
Bit3	输出过压	Bit7	过温

故障字节2

Bit	含义	Bit	含义
Bit0	硬件故障	Bit4	NC
Bit1	PFC故障	Bit5	NC
Bit2	风扇故障	Bit6	NC
Bit3	电池反接故障	Bit7	NC

6. 指令示例

6.1 设置输出电压/电流（CMD=0x02）

主控→电源：

ADDR	CHx	CMD	LEN	DATA	SUM
0x01	0x00	0x02	0x04	0x02 0x58 0x00 0x64	0xC5

DATA：0x0258 = 60.0V, 0x0064 = 10.0A

电源→主控：

ADDR	CHx	CMD	LEN	DATA	SUM
0x01	0x00	0x02	0x01	0x01	0x05

回复：0x01 = 设置成功

6.2 设置开关机（CMD=0x03）

主控→电源：

ADDR	CHx	CMD	LEN	DATA	SUM
0x01	0x00	0x03	0x01	0x01	0x06

DATA：0x01 = 开机, 0x00 = 关机

电源→主控：

ADDR	CHx	CMD	LEN	DATA	SUM
0x01	0x00	0x03	0x01	0x01	0x06

回复：0x01 = 设置成功

6.3 组合控制命令（CMD=0x04）

主控→电源：

ADDR	CHx	CMD	LEN	DATA	SUM
0x01	0x00	0x04	0x05	0x01 0x02 0x58 0x00 0x64	0xC9

DATA: 0x01 = 开机, 0x0258 = 60.0V, 0x0064 = 10.0A

电源→主控：

ADDR	CHx	CMD	LEN	DATA	SUM
0x01	0x00	0x04	0x07	0x02 0x58 0x00 0x64 0x01 0x01 0x1A	0xE6

回复DATA: 0x0258 = 当前电压60.0V, 0x0064 = 当前电流10.0A, 0x01 0x01 = 故障码, 0x1A = 环温26℃

6.4 读取通道运行信息（CMD=0x05）

主控→电源：

ADDR	CHx	CMD	LEN	DATA	SUM
0x01	0x00	0x05	0x01	0x00	0x07

电源→主控：

ADDR	CHx	CMD	LEN	DATA	SUM
0x01	0x00	0x05	0x0D	0x02 0x58 0x00 0x64 0x01 0x01 0x1A 0x55 0xF0 0x03 0xE8 0x08 0x98	0xBD

回复DATA解析：

偏移	数据	含义
0-1	0x0258	设置电压 60.0V
2-3	0x0064	设置电流 10.0A
4-5	0x0101	故障码
6	0x1A	环温 26℃
7-8	0x55F0	输入电压 220.00V
9-10	0x03E8	输入电流 10.00A
11-12	0x0898	输入功率 2200W

6.5 查询供应商信息（CMD=0x12）

主控→电源：

ADDR	CHx	CMD	LEN	DATA	SUM
0x01	0x00	0x12	0x01	0x00	0x14

电源→主控：

ADDR	CHx	CMD	LEN	DATA
0x01	0x00	0x12	0x0F	'YGCP1TN-A' + 硬件版本 + 软件版本 + 日期(年/月/日) + 序列号

回复DATA解析：

偏移	含义
0-1	厂商 ('YG')
2-9	电源型号 ('CP1TN-A')
10	硬件版本 (S1.0)
11	软件版本 (V1.0)
12-14	生产日期 (年/月/日)
15-16	序列号

6.3 KiB Raw Blame History Unescape Escape

换电柜用锂电池充电器 1TN 标准通信协议 RS485

版本记录

1. 概述

1.1 通讯格式

1.2 信息帧格式

1.3 通讯过程

2. 地址码（ADDR）

3. 通道码（CHx）

4. 功能码（CMD）

5. 故障码

故障字节1

故障字节2

6. 指令示例

6.1 设置输出电压/电流（CMD=0x02）

6.2 设置开关机（CMD=0x03）

6.3 组合控制命令（CMD=0x04）

6.4 读取通道运行信息（CMD=0x05）

6.5 查询供应商信息（CMD=0x12）

6.3 KiB

Raw Blame History