admin/charging-cabinet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
charging-cabinet/docs/contract/附件-开发需求规格说明书.html
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

534 lines
12 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html><html lang="zh-CN"><head><meta charset="UTF-8"><title>附件-开发需求规格说明书</title><style>body{font-family:"Microsoft YaHei",sans-serif;max-width:900px;margin:40px auto;padding:20px;line-height:1.8;color:#333}
h1{text-align:center;font-size:22px;border-bottom:2px solid #333;padding-bottom:10px}
h2{font-size:18px;margin-top:30px;border-left:4px solid #333;padding-left:10px}
h3{font-size:16px;margin-top:20px}h4{font-size:15px;margin-top:15px}
table{width:100%;border-collapse:collapse;margin:15px 0;font-size:14px}
th,td{border:1px solid #999;padding:8px;text-align:left}th{background:#f0f0f0}
p,li{font-size:14px}hr{border:none;border-top:1px solid #ccc;margin:30px 0}
pre{background:#f5f5f5;padding:15px;border-radius:4px;overflow-x:auto;font-size:13px}
code{font-family:Consolas,monospace}
.blank{color:#999;border-bottom:1px solid #999;display:inline-block;min-width:150px}
.sign{margin-top:60px}.sign div{display:inline-block;width:45%;vertical-align:top}</style></head><body><h1>附件：开发需求规格说明书</h1>
<p><strong>所属合同：</strong> 36仓体直流电瓶车充电柜 开发合同
<strong>合同编号：</strong> ________________</p>
<hr>
<h2>第1章 柜控主板（ID128）硬件规格</h2>
<h3>1.1 基本参数</h3>
<table>
<thead>
<tr>
<th>项目</th>
<th>参数</th>
</tr>
</thead>
<tbody><tr>
<td>板卡数量</td>
<td>3块（含1块备板）</td>
</tr>
<tr>
<td>MCU</td>
<td>内置MCU控制器，支持OTA固件升级</td>
</tr>
<tr>
<td>供电</td>
<td>12V直流输入（预接触器，常供电）</td>
</tr>
<tr>
<td>后备电源</td>
<td>后备电池自动切换（可选），维持板子供电与4G通讯</td>
</tr>
<tr>
<td>工作温度</td>
<td>-10℃ ~ +70℃</td>
</tr>
<tr>
<td>工作湿度</td>
<td>10% ~ 90%</td>
</tr>
<tr>
<td>PCB</td>
<td>双面板/四层板，根据设计复杂度确定</td>
</tr>
</tbody></table>
<h3>1.2 接口规格</h3>
<table>
<thead>
<tr>
<th>接口</th>
<th>规格</th>
</tr>
</thead>
<tbody><tr>
<td>485接口</td>
<td>1路隔离RS485，与6个仓控板通讯，光耦隔离保护，波特率9600</td>
</tr>
<tr>
<td>485电表接口</td>
<td>1路隔离RS485，接DL/T645电表，读取耗电量数据</td>
</tr>
<tr>
<td>4G模块</td>
<td>Air780E，自定义TCP协议长连接</td>
</tr>
<tr>
<td>烟感接口</td>
<td>1路开关量输入，中断触发</td>
</tr>
<tr>
<td>浸水接口</td>
<td>1路开关量输入，中断触发</td>
</tr>
<tr>
<td>倾倒检测</td>
<td>1路开关量输入，中断触发</td>
</tr>
<tr>
<td>环境温控接口</td>
<td>1路，适配NTC/DS18B20</td>
</tr>
<tr>
<td>门锁控制</td>
<td>1路MOS管/三极管驱动输出 + 1路门磁反馈输入，控制柜体电控锁并检测锁状态</td>
</tr>
<tr>
<td>接触器控制</td>
<td>1路继电器输出，控制常开接触器（默认断开，给信号吸合）</td>
</tr>
<tr>
<td>喷淋电磁阀</td>
<td>1路继电器输出，烟感触发时自动打开</td>
</tr>
<tr>
<td>加热风扇继电器</td>
<td>1路独立继电器输出，220V/10A</td>
</tr>
<tr>
<td>电磁泵继电器</td>
<td>1路继电器输出</td>
</tr>
<tr>
<td>接触器按钮</td>
<td>2个物理按钮：合闸按钮（吸合接触器）、分闸按钮（断开接触器）</td>
</tr>
<tr>
<td>存储</td>
<td>Flash，存储BMS类型/报警阈值/无协议充电参数</td>
</tr>
</tbody></table>
<h3>1.3 供电时序</h3>
<ul>
<li>主电源12V预接触器接入，柜控板常供电</li>
<li>后备电池（可选）在380V断电时自动切换，维持板子供电与远程通讯</li>
<li>接触器默认断开，上电后自动吸合恢复供电</li>
<li>平台可远程下发恢复指令吸合接触器</li>
</ul>
<hr>
<h2>第2章 仓控主板（ID1-6）硬件规格</h2>
<h3>2.1 基本参数</h3>
<table>
<thead>
<tr>
<th>项目</th>
<th>参数</th>
</tr>
</thead>
<tbody><tr>
<td>板卡数量</td>
<td>10块（含4块备板）</td>
</tr>
<tr>
<td>MCU</td>
<td>内置MCU控制器，支持OTA固件升级</td>
</tr>
<tr>
<td>供电</td>
<td>由柜控板统一供电（12V）</td>
</tr>
<tr>
<td>工作温度</td>
<td>-10℃ ~ +70℃</td>
</tr>
<tr>
<td>ID设置</td>
<td>4位拨码开关，设置485从站ID（1-6）</td>
</tr>
</tbody></table>
<h3>2.2 接口规格</h3>
<table>
<thead>
<tr>
<th>接口</th>
<th>规格</th>
</tr>
</thead>
<tbody><tr>
<td>485接口×3</td>
<td>全部隔离：1路接柜控板（ID128）、1路接BMS总线（6仓体共用）、1路接所属电源模块</td>
</tr>
<tr>
<td>光耦隔离</td>
<td>3路485均做光耦隔离保护</td>
</tr>
<tr>
<td>温控接口</td>
<td>6路，适配NTC/DS18B20（可选）</td>
</tr>
<tr>
<td>指示灯接口</td>
<td>6路，支持绿灯/红灯控制</td>
</tr>
</tbody></table>
<h3>2.3 物料清单（乙方供）</h3>
<table>
<thead>
<tr>
<th>物料</th>
<th>数量</th>
<th>说明</th>
</tr>
</thead>
<tbody><tr>
<td>4G模块</td>
<td>3个</td>
<td>Air780E（用于柜控板）</td>
</tr>
<tr>
<td>光耦隔离芯片</td>
<td>100个</td>
<td>485隔离用</td>
</tr>
<tr>
<td>状态指示灯</td>
<td>50个</td>
<td>红绿双色</td>
</tr>
<tr>
<td>拨码开关</td>
<td>10个</td>
<td>4位</td>
</tr>
<tr>
<td>PCB打样及焊接辅料</td>
<td>1批</td>
<td>含钢网/样板焊接</td>
</tr>
</tbody></table>
<hr>
<h2>第3章 MCU固件需求</h2>
<h3>3.1 柜控板固件（1个工程）</h3>
<table>
<thead>
<tr>
<th>功能</th>
<th>说明</th>
</tr>
</thead>
<tbody><tr>
<td>485主站通讯</td>
<td>与仓控板ID1-6双向寻址通讯，响应延迟≤0.5s</td>
</tr>
<tr>
<td>4G TCP通讯</td>
<td>与后台平台自定义TCP长连接，含心跳/断线重连/数据缓存补偿</td>
</tr>
<tr>
<td>指令转发</td>
<td>接收平台充电控制/门锁/配置等指令，转发至对应仓控板</td>
</tr>
<tr>
<td>安全监测联动</td>
<td>烟感/浸水/倾倒检测，触发后断开接触器+打开喷淋电磁阀</td>
</tr>
<tr>
<td>电表采集</td>
<td>通过独立485接口按DL/T645协议读取电表耗电量，定时上报平台</td>
</tr>
<tr>
<td>辅助设备控制</td>
<td>加热风扇自动温控（&lt;0°C开/≥25°C停）、电磁泵远程通断</td>
</tr>
<tr>
<td>门锁控制</td>
<td>接收平台开门指令，直接控制柜体电控锁</td>
</tr>
<tr>
<td>OTA升级</td>
<td>接收平台固件包，本地升级或分片转发仓控板</td>
</tr>
<tr>
<td>配置管理</td>
<td>BMS协议类型、报警阈值、无协议充电参数的存储与下发</td>
</tr>
</tbody></table>
<h3>3.2 仓控板固件（1个工程）</h3>
<table>
<thead>
<tr>
<th>功能</th>
<th>说明</th>
</tr>
</thead>
<tbody><tr>
<td>485从站通讯</td>
<td>响应柜控板指令，按拨码ID（1-6）寻址</td>
</tr>
<tr>
<td>BMS多协议通讯</td>
<td>按配置协议轮询6仓体电池数据：星恒Modbus-RTU/天能自定义/无协议跳过</td>
</tr>
<tr>
<td>1TN电源协议</td>
<td>与所属充电电源独立485通讯，电压/电流/开关控制（电源自带通断）</td>
</tr>
<tr>
<td>充电控制逻辑</td>
<td>平台/柜控双模式，含电池握手/充满判断/无协议充电/低电流自动停止</td>
</tr>
<tr>
<td>状态采集与指示</td>
<td>6路红绿LED指示灯控制 + 6路温控采集（可选）</td>
</tr>
<tr>
<td>OTA升级与ID管理</td>
<td>接收固件包校验写入，拨码开关读取识别</td>
</tr>
</tbody></table>
<hr>
<h2>第4章 后台管理系统需求</h2>
<h3>4.1 功能模块</h3>
<table>
<thead>
<tr>
<th>模块</th>
<th>功能要求</th>
</tr>
</thead>
<tbody><tr>
<td>设备管理</td>
<td>实时监控、远程重启、参数配置、OTA固件升级（柜控板+仓控板）</td>
</tr>
<tr>
<td>仓体控制</td>
<td>独立电流/电压设置、禁用/解除、状态查看、远程开门</td>
</tr>
<tr>
<td>BMS协议配置</td>
<td>设置当前柜体BMS协议类型（星恒/天能/无协议充电）</td>
</tr>
<tr>
<td>无协议充电参数配置</td>
<td>设置固定充电电压/电流/停止电流阈值</td>
</tr>
<tr>
<td>充电控制模式配置</td>
<td>平台/柜控模式切换、特殊ID管理</td>
</tr>
<tr>
<td>能耗管理</td>
<td>实时显示/统计电表耗电量数据，按日/月/年生成报表</td>
</tr>
<tr>
<td>用户管理</td>
<td>注册/登录、权限分配（管理员/普通/骑手）</td>
</tr>
<tr>
<td>数据统计</td>
<td>充电量、使用率、故障率、温控数据、告警统计、能耗统计</td>
</tr>
<tr>
<td>故障管理</td>
<td>故障记录、工单分配、处理跟踪、解除禁用</td>
</tr>
<tr>
<td>报警阈值管理</td>
<td>关门超时阈值配置、高温报警阈值配置</td>
</tr>
<tr>
<td>TCP连接管理</td>
<td>连接状态监控、心跳检测、断连告警</td>
</tr>
<tr>
<td>辅助设备控制</td>
<td>电磁泵远程通断控制、加热风扇状态监控</td>
</tr>
</tbody></table>
<h3>4.2 数据模型</h3>
<table>
<thead>
<tr>
<th>实体</th>
<th>字段</th>
</tr>
</thead>
<tbody><tr>
<td>充电柜</td>
<td>id/名称/位置/状态/BMS协议类型/无协议充电参数/报警阈值/总耗电量</td>
</tr>
<tr>
<td>仓体</td>
<td>所属电源/所属仓控板ID/状态/电压电流设置/指示灯状态</td>
</tr>
<tr>
<td>仓控板</td>
<td>ID/状态/固件版本/OTA进度/6路温控（可选）</td>
</tr>
<tr>
<td>柜控板</td>
<td>ID/状态/固件版本/OTA进度/TCP状态/4G信号/加热风扇/电磁泵/喷淋/电表耗电量</td>
</tr>
<tr>
<td>充电记录</td>
<td>仓体ID/开始结束时间/充电量/最高温度/状态</td>
</tr>
<tr>
<td>故障记录</td>
<td>主板ID/故障类型/故障码/时间/处理状态/等级</td>
</tr>
</tbody></table>
<hr>
<h2>第5章 微信小程序需求</h2>
<p>微信小程序为后台管理系统的移动端版本，实现后台核心功能的移动化操作。</p>
<h3>5.1 功能页面</h3>
<table>
<thead>
<tr>
<th>页面</th>
<th>功能要求</th>
</tr>
</thead>
<tbody><tr>
<td>首页</td>
<td>充电柜概览仪表盘：在线状态、总耗电量、今日充电量、待处理告警数</td>
</tr>
<tr>
<td>设备管理</td>
<td>查看柜控板/仓控板状态、仓体列表及状态、温控数据、电表读数</td>
</tr>
<tr>
<td>远程控制</td>
<td>仓体禁用/解除、远程开门、电磁泵通断、接触器合闸/分闸</td>
</tr>
<tr>
<td>告警管理</td>
<td>实时告警推送、告警列表查看与确认处理</td>
</tr>
<tr>
<td>数据统计</td>
<td>充电量/能耗/告警统计图表（日/月/年）</td>
</tr>
<tr>
<td>个人中心</td>
<td>账号信息、修改密码、操作日志</td>
</tr>
</tbody></table>
<hr>
<h2>第6章 通讯协议栈</h2>
<h3>6.1 协议列表</h3>
<table>
<thead>
<tr>
<th>协议</th>
<th>说明</th>
</tr>
</thead>
<tbody><tr>
<td>电源1TN RS485</td>
<td>与充电电源通讯，电压/电流设置、状态查询、故障读取</td>
</tr>
<tr>
<td>星恒BMS Modbus-RTU</td>
<td>读取电池SOC/电压/温度/告警，地址0x16</td>
</tr>
<tr>
<td>天能485协议</td>
<td>适配天能电池自定义RS485协议</td>
</tr>
<tr>
<td>电表DL/T645</td>
<td>读取柜体总耗电量，定时采集上报</td>
</tr>
<tr>
<td>仓控-柜控485协议</td>
<td>自定义帧结构（帧头/ID/功能码/长度/数据/CRC16），14个功能码</td>
</tr>
<tr>
<td>柜控-平台TCP协议</td>
<td>自定义TCP长连接，含心跳/数据上报/指令下发/OTA</td>
</tr>
</tbody></table>
<h3>6.2 仓控-柜控485功能码表</h3>
<table>
<thead>
<tr>
<th>码</th>
<th>指令</th>
<th>方向</th>
</tr>
</thead>
<tbody><tr>
<td>0x01</td>
<td>上传BMS数据</td>
<td>仓控→柜控</td>
</tr>
<tr>
<td>0x02</td>
<td>上传温控数据</td>
<td>仓控→柜控</td>
</tr>
<tr>
<td>0x03</td>
<td>上传电源状态</td>
<td>仓控→柜控</td>
</tr>
<tr>
<td>0x06</td>
<td>上传OTA状态</td>
<td>仓控→柜控</td>
</tr>
<tr>
<td>0x82</td>
<td>电源参数设置</td>
<td>柜控→仓控</td>
</tr>
<tr>
<td>0x83</td>
<td>指示灯控制</td>
<td>柜控→仓控</td>
</tr>
<tr>
<td>0x84</td>
<td>查询指令</td>
<td>柜控→仓控</td>
</tr>
<tr>
<td>0x85</td>
<td>平台禁用</td>
<td>柜控→仓控</td>
</tr>
<tr>
<td>0x86</td>
<td>模式切换</td>
<td>平台→柜控</td>
</tr>
<tr>
<td>0x87</td>
<td>接触器控制</td>
<td>平台→柜控</td>
</tr>
<tr>
<td>0x89</td>
<td>OTA升级</td>
<td>柜控→仓控</td>
</tr>
<tr>
<td>0x8A</td>
<td>BMS类型配置</td>
<td>柜控→仓控</td>
</tr>
<tr>
<td>0x8B</td>
<td>报警阈值配置</td>
<td>柜控→仓控</td>
</tr>
</tbody></table>
</body></html>
Reference in New Issue View Git Blame Copy Permalink