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` 的「旧名 → 现名映射」表中给出对应关系。
54 lines
2.5 KiB
Markdown
54 lines
2.5 KiB
Markdown
# 附件二：软件规格
|
||
|
||
**所属合同：** 36仓体直流电瓶车充电柜 开发合同
|
||
**合同编号：** \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
|
||
|
||
---
|
||
|
||
## 第1章 后台管理系统需求
|
||
|
||
### 1.1 功能模块
|
||
|
||
| 模块 | 功能要求 |
|
||
|------|---------|
|
||
| 设备管理 | 实时监控、远程重启、参数配置、OTA固件升级（柜控板+仓控板） |
|
||
| 仓体控制 | 独立电流/电压设置、禁用/解除、状态查看、远程开门 |
|
||
| BMS协议配置 | 设置当前柜体BMS协议类型（星恒/天能/无协议充电） |
|
||
| 无协议充电参数配置 | 设置固定充电电压/电流/停止电流阈值 |
|
||
| 充电控制模式配置 | 平台/柜控模式切换、特殊ID管理 |
|
||
| 能耗管理 | 实时显示/统计电表耗电量数据，按日/月/年生成报表 |
|
||
| 用户管理 | 注册/登录、权限分配（管理员/普通/骑手） |
|
||
| 数据统计 | 充电量、使用率、故障率、温控数据、告警统计、能耗统计 |
|
||
| 故障管理 | 故障记录、工单分配、处理跟踪、解除禁用 |
|
||
| 报警阈值管理 | 关门超时阈值配置、高温报警阈值配置 |
|
||
| TCP连接管理 | 连接状态监控、心跳检测、断连告警 |
|
||
| 辅助设备控制 | 电磁泵远程通断控制、加热风扇状态监控 |
|
||
|
||
### 1.2 数据模型
|
||
|
||
| 实体 | 字段 |
|
||
|------|------|
|
||
| 充电柜 | id/名称/位置/状态/BMS协议类型/无协议充电参数/报警阈值/总耗电量 |
|
||
| 仓体 | 所属电源/所属仓控板ID/状态/电压电流设置/指示灯状态 |
|
||
| 仓控板 | ID/状态/固件版本/OTA进度/6路温控（可选） |
|
||
| 柜控板 | ID/状态/固件版本/OTA进度/TCP状态/4G信号/加热风扇/电磁泵/喷淋/电表耗电量 |
|
||
| 充电记录 | 仓体ID/开始结束时间/充电量/最高温度/状态 |
|
||
| 故障记录 | 主板ID/故障类型/故障码/时间/处理状态/等级 |
|
||
|
||
---
|
||
|
||
## 第2章 微信小程序需求
|
||
|
||
微信小程序为后台管理系统的移动端版本。
|
||
|
||
### 2.1 功能页面
|
||
|
||
| 页面 | 功能要求 |
|
||
|------|---------|
|
||
| 首页 | 充电柜概览仪表盘：在线状态、总耗电量、今日充电量、待处理告警数 |
|
||
| 设备管理 | 查看柜控板/仓控板状态、仓体列表及状态、温控数据、电表读数 |
|
||
| 远程控制 | 仓体禁用/解除、远程开门、电磁泵通断、接触器合闸/分闸 |
|
||
| 告警管理 | 实时告警推送、告警列表查看与确认处理 |
|
||
| 数据统计 | 充电量/能耗/告警统计图表（日/月/年） |
|
||
| 个人中心 | 账号信息、修改密码、操作日志 |
|