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` 的「旧名 → 现名映射」表中给出对应关系。
63 lines
2.6 KiB
Markdown
63 lines
2.6 KiB
Markdown
# 附件三：交付与验收标准
|
||
|
||
**所属合同：** 36仓体直流电瓶车充电柜 开发合同
|
||
**合同编号：** \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
|
||
|
||
---
|
||
|
||
## 1. 交付物清单
|
||
|
||
| 编号 | 交付物 | 形式 | 数量 |
|
||
|------|--------|------|------|
|
||
| 1 | 柜控主板（含固件） | 硬件成品 | 3块（含1块备板） |
|
||
| 2 | 仓控主板（含固件） | 硬件成品 | 10块（含4块备板） |
|
||
| 3 | 后台管理系统 | 编译部署包 | 1份 |
|
||
| 4 | 微信小程序 | 编译发布包 | 1份 |
|
||
| 5 | 技术开发文档 | 电子版 | 1份 |
|
||
| 6 | 用户操作手册 | 电子版 | 1份 |
|
||
| 7 | 运维手册 | 电子版 | 1份 |
|
||
| 8 | 测试报告 | 电子版 | 1份 |
|
||
|
||
注：充电柜柜体、充电电源及外部器件（风扇/泵/阀/锁/传感器等）由甲方提供，不在乙方交付范围内。**本合同不交付任何源代码。**
|
||
|
||
## 2. 验收标准
|
||
|
||
| 验收项 | 标准 |
|
||
|--------|------|
|
||
| 硬件验收 | 各接口功能正常，通讯稳定，电气参数符合设计要求 |
|
||
| 固件验收 | 所有功能码响应正确，通讯延迟≤0.5s，无死机/异常重启 |
|
||
| 后台验收 | 各管理功能正常，数据展示准确，操作响应≤2s |
|
||
| 小程序验收 | 扫码充电流程完整，状态展示与硬件一致 |
|
||
| 整机验收 | 乙方到甲方现场，将板子安装至甲方提供的柜体中完成36仓同步充电测试及安全防护功能测试 |
|
||
|
||
## 3. 通讯协议栈
|
||
|
||
### 3.1 协议列表
|
||
|
||
| 协议 | 说明 |
|
||
|------|------|
|
||
| 电源1TN RS485 | 与充电电源通讯，电压/电流设置、状态查询、故障读取 |
|
||
| 星恒BMS Modbus-RTU | 读取电池SOC/电压/温度/告警，地址0x16 |
|
||
| 天能485协议 | 适配天能电池自定义RS485协议 |
|
||
| 电表DL/T645 | 读取柜体总耗电量，定时采集上报 |
|
||
| 仓控-柜控485协议 | 自定义帧结构（帧头/ID/功能码/长度/数据/CRC16），14个功能码 |
|
||
| 柜控-平台TCP协议 | 自定义TCP长连接，含心跳/数据上报/指令下发/OTA |
|
||
|
||
### 3.2 仓控-柜控485功能码表
|
||
|
||
| 码 | 指令 | 方向 |
|
||
|----|------|------|
|
||
| 0x01 | 上传BMS数据 | 仓控→柜控 |
|
||
| 0x02 | 上传温控数据 | 仓控→柜控 |
|
||
| 0x03 | 上传电源状态 | 仓控→柜控 |
|
||
| 0x06 | 上传OTA状态 | 仓控→柜控 |
|
||
| 0x82 | 电源参数设置 | 柜控→仓控 |
|
||
| 0x83 | 指示灯控制 | 柜控→仓控 |
|
||
| 0x84 | 查询指令 | 柜控→仓控 |
|
||
| 0x85 | 平台禁用 | 柜控→仓控 |
|
||
| 0x86 | 模式切换 | 平台→柜控 |
|
||
| 0x87 | 接触器控制 | 平台→柜控 |
|
||
| 0x89 | OTA升级 | 柜控→仓控 |
|
||
| 0x8A | BMS类型配置 | 柜控→仓控 |
|
||
| 0x8B | 报警阈值配置 | 柜控→仓控 |
|