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` 的「旧名 → 现名映射」表中给出对应关系。
4.5 KiB
4.5 KiB
36仓体直流电瓶车充电柜 开发合同
合同编号： ________________
签订地点： ________________
签订日期： _____年____月____日____
第一条 合同双方
甲方（委托方）：
- 公司名称：______________________________
- 法定代表人：________________
- 地址：______________________________
- 联系人：________ 联系电话：____________
乙方（开发方）：
- 公司名称：______________________________
- 法定代表人：________________
- 地址：______________________________
- 联系人：________ 联系电话：____________
第二条 项目概述
- 项目名称：36仓体直流电瓶车充电柜开发项目
- 项目目标：开发充电柜配套的柜控主板、仓控主板、嵌入式固件、后台管理系统及微信小程序
- 开发周期：合同生效后12周
- 交付成果：详见第五条及附件
第三条 开发内容
| 序号 | 开发内容 | 详见附件 |
|---|---|---|
| 1 | 柜控主板硬件设计开发 | 附件一 |
| 2 | 仓控主板硬件设计开发 | 附件一 |
| 3 | 嵌入式固件开发（柜控板+仓控板） | 附件一 |
| 4 | 后台管理系统开发 | 附件二 |
| 5 | 微信小程序开发 | 附件二 |
| 6 | 通讯协议栈开发实现 | 附件三 |
乙方负责主板设计、元器件采购、焊接调试及联调支持。柜体、电源及外部器件由甲方提供。本合同不交付任何源代码。
第四条 开发阶段
| 阶段 | 时间 | 交付物 |
|---|---|---|
| M1 方案定稿 | 第1-2周 | 原理图、PCB、BOM、协议文档 |
| M2 开发完成 | 第3-6周 | 硬件样板、固件、后台、小程序 |
| M3 联调完成 | 第7-9周 | 集成测试报告 |
| M4 验收交付 | 第10-12周 | 完整成品、技术文档 |
付款方式： ________________________________________________________________________
第五条 交付与验收
交付物清单及验收标准详见附件三。整机验收时乙方到甲方现场完成联调，验收所需柜体及电源由甲方提供。
第六条 知识产权
- 乙方在本合同履行过程中产生的全部技术成果（包括但不限于源代码、设计图纸、技术文档等）的知识产权归甲乙双方共同所有。
- 任何一方均有权在自身业务范围内自由使用上述技术成果，无需征得另一方同意或另行支付费用。
第七条 保密条款
- 双方对合同履行过程中知悉的对方商业秘密、技术秘密负有保密义务。
- 保密期限自合同生效之日起3年。
- 未经对方书面同意，不得向第三方披露任何与本合同相关的信息。
第八条 质保与维护
- 硬件质保期自验收通过之日起 12个月，质保期内免费维修或更换。
- 软件质保期自验收通过之日起 6个月，质保期内免费修复Bug。
- 质保期外的维护服务费用由双方另行协商。
第九条 违约责任
- 甲方逾期付款的，每逾期一日按应付未付金额的千分之三支付违约金。
- 乙方逾期交付的，每逾期一日按合同总金额的千分之三支付违约金。
- 任何一方违反知识产权或保密条款的，应赔偿对方全部损失。
第十条 合同总金额
合同总金额：人民币 ___________ 元（大写：____________________）
第十一条 争议解决
本合同履行过程中发生争议的，双方应协商解决；协商不成的，提交合同签订地人民法院诉讼解决。
第十二条 其他
- 本合同一式两份，甲乙双方各执一份，具有同等法律效力。
- 本合同附件为合同的组成部分，与本合同具有同等法律效力。
- 未尽事宜，双方可另行签订补充协议。
甲方（盖章）： ____________________
授权代表签字：________________
日期：_____年____月____日
乙方（盖章）： ____________________
授权代表签字：________________
日期：_____年____月____日