619c96c85f
## 为什么要做
`AGENTS.md` 曾达 **90,370 B**，而工作区指令预算是 **65,536 B** —— 系统按**保留头部**截断，
于是**尾部约 25 KB 永远不会被加载**：组织架构、数据模型、TCP 协议、数据单位规范、
微信小程序用户端**全部处于"写了但读不到"的状态**。手册实际上部分失效。
## 一、AGENTS.md 瘦身：90,370 → 60,227 B（余量 5,309 B，尾部不再被截断）
三个**纯参考型大段**整段搬迁到 `docs/tech/`（**内容逐字保留，未删改**），
原位置换成「判据 + 链接」：
| 原 AGENTS.md 章节 | 大小 | 现位置 |
|---|---|---|
| `## 部署与维护` | 17,611 B | `docs/tech/部署手册.md` |
| `## 数据模型` | 12,100 B | `docs/tech/数据模型.md` |
| `## 微信小程序用户端` | 10,262 B | `docs/tech/小程序用户端.md` |
替换后的章节**只留改动前必须先知道的硬约束**（例如：产物名与测试环境落地名不一致、
ETXTBSY 的 `.new`→`stop`→`mv`→`start` 流程、`stream{}` 不可重加、发布顺序 device 先 api 后、
建表顺序即依赖顺序且写错报 MySQL 1824、时间列必须 DATETIME、`cabinets.status` 是配置态不表示在线……），
其余指向详细篇。**判据留在常驻加载的 AGENTS.md，逐项参考移出**。
## 二、docs/ 分类（原 21 个文件平铺 → 五个用途目录）
```
docs/
├── README.md 新增：文档地图（分类/权威性/旧名→现名映射/维护约定）
├── protocol/ 设备协议（冻结，对硬件交付）★唯一权威
│ ├── 柜控板固件对接文档.md
│ └── 1TN协议标准_*.md / *.pdf
├── tech/ 平台技术文档（开发/运维必读）
│ ├── API.md · 数据模型.md · 部署手册.md · 小程序用户端.md
├── contract/ 合同·规格·验收标准（商务依据，不描述实现）
├── compound-notes/ 单点经验笔记（原有）
└── archive/ ⛔ 历史留痕（只读，不代表现状，不可作依据）
├── 开发文档.md（早于现行实现）
└── 审查报告/深度分析报告-2026-07-06
```
- 19 个文件用 `git mv` 迁移（保留历史），3 个未跟踪文件用普通移动；
- **内容零改动**（唯一例外是引用替换），已核验 `docs/tech/API.md` 的 `git diff` 为空。
## 三、全仓引用同步：40 处 / 10 个文件
路径不只出现在文档里，还散落在**源码注释**（`db/migrate.rs`、`routes/cabinets.rs`、
`workers/report_worker.rs`、`tcp/connection.rs`、`h5-uniapp/utils/format.ts`）、
`test/tcp_e2e_smoke.py`、`tasks/001-*.md`、`README.md`、`AGENTS.md` 中，全部同步。
**并已实测校验命令能失败**：往 `docs/tech/API.md` 植入 `<!-- probe: docs/API.md -->`
→ 命中；删除 → 无输出。
> ⚠️ 过程中踩了一个坑并已修：这些 `.md` 多为 **CRLF**，我第一次用 `\n` 正则删除时
> **没匹配上 `\r\n`**，以为删干净了其实残留了一行 —— 靠 `git diff` 非空才发现。
> 已把「CRLF 必须按 `\r?\n` 处理」写进 `docs/README.md` 的维护约定。
## 四、顺带查实的失效引用（归档保留原文，不改写历史）
- `docs/tcp-protocol.md`：仅出现在 2026-07-06 的两份历史报告里（当时的事实）；
- `docs/柜控板-平台TCP接口文档.md`：仅出现在协议文档 **v1.1 变更记录**里
（记录"已删除该内部重复文档"这件事），**不是活链接**，无需修复。
两者已在 `docs/README.md` 的「旧名 → 现名映射」表中给出对应关系。
6.3 KiB
6.3 KiB
换电柜用锂电池充电器 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 | 序列号 |