admin/charging-cabinet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
charging-cabinet/docs/contract/附件一-硬件规格.md
12451 619c96c85f docs: 文档分类整理 —— AGENTS.md 只留判据与链接，详细篇按用途归入 docs/ 子目录 
## 为什么要做

`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` 的「旧名 → 现名映射」表中给出对应关系。
2026-09-20 04:42:51 +08:00

4.5 KiB
Raw Blame History

附件一：硬件规格

所属合同： 36仓体直流电瓶车充电柜 开发合同 合同编号： ________________

第1章 柜控主板（ID128）硬件规格

1.1 基本参数

项目 参数
板卡数量 3块（含1块备板）
MCU 内置MCU控制器，支持OTA固件升级
供电 12V直流输入（预接触器，常供电）
后备电源 后备电池自动切换（可选），维持板子供电与4G通讯
工作温度 -10℃ ~ +70℃
工作湿度 10% ~ 90%
PCB 双面板/四层板，根据设计复杂度确定

1.2 接口规格

接口 规格
485接口 1路隔离RS485，与6个仓控板通讯，光耦隔离保护，波特率9600
485电表接口 1路隔离RS485，接DL/T645电表，读取耗电量数据
4G模块 Air780E，自定义TCP协议长连接
烟感接口 1路开关量输入，中断触发
浸水接口 1路开关量输入，中断触发
倾倒检测 1路开关量输入，中断触发
环境温控接口 1路，适配NTC/DS18B20
门锁控制 1路MOS管/三极管驱动输出 + 1路门磁反馈输入，控制柜体电控锁并检测锁状态
接触器控制 1路继电器输出，控制常开接触器（默认断开，给信号吸合）
喷淋电磁阀 1路继电器输出，烟感触发时自动打开
加热风扇继电器 1路独立继电器输出，220V/10A
电磁泵继电器 1路继电器输出
接触器按钮 2个物理按钮：合闸按钮（吸合接触器）、分闸按钮（断开接触器）
存储 Flash，存储BMS类型/报警阈值/无协议充电参数

1.3 供电时序

  • 主电源12V预接触器接入，柜控板常供电
  • 后备电池（可选）在380V断电时自动切换，维持板子供电与远程通讯
  • 接触器默认断开，上电后自动吸合恢复供电
  • 平台可远程下发恢复指令吸合接触器

第2章 仓控主板（ID1-6）硬件规格

2.1 基本参数

项目 参数
板卡数量 10块（含4块备板）
MCU 内置MCU控制器，支持OTA固件升级
供电 由柜控板统一供电（12V）
工作温度 -10℃ ~ +70℃
ID设置 4位拨码开关，设置485从站ID（1-6）

2.2 接口规格

接口 规格
485接口×3 全部隔离：1路接柜控板（ID128）、1路接BMS总线（6仓体共用）、1路接所属电源模块
光耦隔离 3路485均做光耦隔离保护
温控接口 6路，适配NTC/DS18B20（可选）
指示灯接口 6路，支持绿灯/红灯控制

2.3 物料清单（乙方供）

物料 数量 说明
4G模块 3个 Air780E（用于柜控板）
光耦隔离芯片 100个 485隔离用
状态指示灯 50个 红绿双色
拨码开关 10个 4位
PCB打样及焊接辅料 1批 含钢网/样板焊接

第3章 MCU固件需求

3.1 柜控板固件（1个工程）

功能 说明
485主站通讯 与仓控板ID1-6双向寻址通讯，响应延迟≤0.5s
4G TCP通讯 与后台平台自定义TCP长连接，含心跳/断线重连/数据缓存补偿
指令转发 接收平台充电控制/门锁/配置等指令，转发至对应仓控板
安全监测联动 烟感/浸水/倾倒检测，触发后断开接触器+打开喷淋电磁阀
电表采集 通过独立485接口按DL/T645协议读取电表耗电量，定时上报平台
辅助设备控制 加热风扇自动温控（<0°C开/≥25°C停）、电磁泵远程通断
门锁控制 接收平台开门指令，直接控制柜体电控锁
OTA升级 接收平台固件包，本地升级或分片转发仓控板
配置管理 BMS协议类型、报警阈值、无协议充电参数的存储与下发

3.2 仓控板固件（1个工程）

功能 说明
485从站通讯 响应柜控板指令，按拨码ID（1-6）寻址
BMS多协议通讯 按配置协议轮询6仓体电池数据：星恒Modbus-RTU/天能自定义/无协议跳过
1TN电源协议 与所属充电电源独立485通讯，电压/电流/开关控制（电源自带通断）
充电控制逻辑 平台/柜控双模式，含电池握手/充满判断/无协议充电/低电流自动停止
状态采集与指示 6路红绿LED指示灯控制 + 6路温控采集（可选）
OTA升级与ID管理 接收固件包校验写入，拨码开关读取识别