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

6.9 KiB

Raw Blame History

docs/ 文档地图

本文件是 docs/ 的分类索引。 新增、移动或改名任何文档后，必须回来更新本文件 并同步全仓引用（见文末「维护约定」）。

一、分类总览

目录	定位	权威性	谁该读
`protocol/`	设备协议（冻结，对硬件工程师交付）	⭐ 唯一权威	硬件工程师、固件、平台 TCP 相关开发
`tech/`	平台技术文档（开发/运维必读）	⭐ 权威（各自领域内）	后端/前端/运维
`contract/`	合同、规格、验收标准（商务依据）	事实依据，但不描述实现	PM、验收方、新人了解范围
`compound-notes/`	单点经验笔记（踩坑/技法）	参考，非权威	遇到同类问题的人
`archive/`	历史留痕（只读，不代表现状）	⛔ 不可作为依据	追溯历史决策时

二、谁是权威（口径优先级，避免"两份文档谁对"的扯皮）

protocol/柜控板固件对接文档.md —— 设备协议（帧格式 / act / 字段名 / 签名 / id 规则）的唯一权威。协议冻结，设备端固件不可改。
根目录 AGENTS.md —— 平台侧实现口径的权威：Redis 键与字段、接口行为、库结构、验收流程、部署注意事项。与 tech/API.md 的平台存储/行为描述冲突时，以 AGENTS.md 为准 （它的每一条都按代码契约与库实测核对过）。
tech/API.md —— HTTP 接口清单与响应结构的权威（含数据单位规范）。
代码与文档冲突时：先确认是不是代码错；确认代码对就改文档并在报告里点出。

三、逐目录说明

protocol/ —— 设备协议

文件	说明
`柜控板固件对接文档.md`	唯一权威 TCP 文档（v1.1.1）。帧格式、通用规则（`act`/`suc`/`msg_id`/60 秒超时/登录门控）、指令清单、签名算法与自测向量、安全码自愈、带注释报文示例（附 A）、变更记录（附 B）。既是内部文档也可直接对外交付。
`1TN协议标准_YG20240118-1_V1.0.md`	仓控板 ↔ 电源（苏州翌工）1TN RS485 协议文本版
`1TN协议标准_苏州翌工电源_V1.0.pdf`	同上，厂家原始 PDF

tech/ —— 平台技术文档

文件	说明	入口
`API.md`	HTTP 接口清单与响应结构 + 数据单位规范（整数存储，禁浮点）	PC/小程序前端、后端
`数据模型.md`	21 张表的逐列语义、外键/唯一键、建表依赖顺序	改表结构前必读
`部署手册.md`	完整部署步骤、nginx 两份 conf.d 全文、全部 11 条部署注意事项	运维、发版
`小程序用户端.md`	小程序页面清单、逐页职责、状态位分层展示、RSSI 分档口径	小程序开发

这四份是 AGENTS.md 的详细参考篇：AGENTS.md 只保留"判据 + 链接" （因为 AGENTS.md 超出工作区指令预算 65,536 B 时会被按头部截断，尾部根本不加载）。

contract/ —— 合同与规格

开发合同 / 附件一-硬件规格 / 附件二-软件规格 / 附件三-交付与验收标准 / 附件-开发需求规格说明书，各含 .md + 原始格式（.docx / .pdf / .html）双份。

用途：范围与验收的事实依据。描述"要做什么 / 达到什么标准"，不描述当前实现 ——实现现状一律以 AGENTS.md + 代码为准。

compound-notes/ —— 经验沉淀

单点问题的笔记（如某次 SQL 注入的成因与修法）。参考性内容，遇到同类问题时查；结论若上升为通用规范，应回写进 AGENTS.md 的「踩过的坑」。

archive/ —— 历史归档

文件	说明
`开发文档.md`	早期（现行实现之前）的开发文档，与当前实现多处不一致
`审查报告-数据单位一致性-2026-07-06.md`	2026-07-06 的数据单位审查报告
`项目深度分析报告-2026-07-06.md`	2026-07-06 的项目深度分析报告

⛔ 归档目录只读、不作依据——里面的路径、结论、数字都是当时的。其中出现的旧文档名（如 tcp-protocol.md、docs/柜控板-平台TCP接口文档.md）是历史事实，不要求可点击；对应关系到当前文档的映射见下节。

四、旧名 → 现名映射（查旧链接时用）

旧路径（已不存在）	现路径
`docs/tcp-protocol.md`	`docs/protocol/柜控板固件对接文档.md`
`docs/柜控板-平台TCP接口文档.md`	已于协议 v1.1 删除（内部重复文档，内容并入上者）
`docs/柜控板固件对接文档.md`	`docs/protocol/柜控板固件对接文档.md`
`docs/API.md`	`docs/tech/API.md`
`docs/数据模型.md` · `docs/部署手册.md` · `docs/小程序用户端.md`	同名，移到 `docs/tech/`
`docs/开发文档.md`	`docs/archive/开发文档.md`
其余合同/规格/验收/协议标准	见上表，分别归入 `contract/` 与 `protocol/`

五、维护约定（新增/移动文档时必做）

归位：按"协议 / 技术 / 合同 / 经验 / 归档"分类放入对应目录，不要再平铺在 docs/ 根。
更新本索引：在对应章节的表格里加一行（文件 + 一句话定位 + 谁该读）。

同步全仓引用：文档路径散落在 AGENTS.md、README.md、Rust/TS/Vue 源码注释、 test/、tools/、tasks/ 里；移动后必须全仓替换。校验方法（应无输出）：

# 找仍指向旧平铺路径的活引用
#   · 排除 docs/archive/ —— 归档按设计保留历史原文
#   · 排除 docs/README.md —— 本文件的「旧名 → 现名映射」表**必须**出现旧名
grep -rn --exclude-dir={.git,node_modules,target,dist} \
     -e 'docs/API\.md' -e 'docs/数据模型\.md' -e 'docs/部署手册\.md' \
     -e 'docs/小程序用户端\.md' -e 'docs/开发文档\.md' . \
  | grep -v '^\./docs/archive/' | grep -v '^\./docs/README\.md:'

已实测该命令能抓到问题：往 docs/tech/API.md 末尾植入一行  → 命中；删除后 → 无输出。 ⚠️ 注意这些 .md 多为 CRLF —— 用脚本批量删除/替换时必须按 \r?\n 处理，否则会漏改（我第一次就踩了：\n 正则配不上 \r\n，以为删干净了其实残留）。

改 AGENTS.md 的链接：AGENTS.md 里所有 docs/... 链接都必须是分类后的路径（docs/protocol/...、docs/tech/...）。
别把权威内容只放进归档：归档是留痕，规范要写进 AGENTS.md 或 tech/。

6.9 KiB Raw Blame History Unescape Escape