admin/charging-cabinet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
charging-cabinet/docs/README.md

144 lines
10 KiB
Markdown
Raw Normal View History

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
# docs/ 文档地图
> **本文件是 `docs/` 的分类索引。** 新增、移动或改名任何文档后，**必须回来更新本文件**
> 并同步全仓引用（见文末「维护约定」）。
## 一、分类总览
| 目录 | 定位 | 权威性 | 谁该读 |
|------|------|--------|--------|
docs: 澄清"唯一 TCP 协议文档"并隔离硬件总线协议；删除已完成任务、摘出未结待办 ## 起因 用户提问：**"我们不是有一个 tcp 协议权威文档了吗？为啥还有其他 tcp 协议文档"** —— 查证后确认：**权威文档只有一份**，但目录布局让人容易误判，且**我上一轮的搬迁引入了一处断链**。 ## 一、查证结果：全仓只有一份 TCP 协议文档 按"是否同时出现 `auth_str`/`status_post`/`bat_in` 等 act 名"全仓扫描，含协议内容的只有： | 文件 | act 命中 | 性质 | |---|---:|---| | `docs/protocol/柜控板固件对接文档.md` | 171 | ⭐ **唯一权威 TCP 协议规格** | | `docs/tech/API.md` | 14 | HTTP 接口文档，TCP 章节**只有一句指回权威文档的链接** | | `AGENTS.md` / `数据模型.md` / `小程序用户端.md` | 13 / 8 / 3 | 规则与存储说明，非协议规格 | | `docs/archive/项目深度分析报告-2026-07-06.md` | 1 | 历史归档 | ⇒ **没有任何第二份 TCP 协议文档。** 用户看到的"另一份"应是下面二者之一（都已处理）： ### 1. `docs/protocol/1TN协议标准_*` —— **不是 TCP 协议** 它是**仓控板 ↔ 翌工电源的 RS485 总线协议**（另一条物理链路）。与 TCP 权威文档同放 `protocol/`，名字又像"协议标准"，极易被当成第二份平台协议。 **已移到新目录 `docs/hardware/`**（硬件侧总线协议），并在两处都写明"**不是**平台 TCP 协议"。 **结果：`docs/protocol/` 下有且仅有一个文件** —— 一眼就能确认"只有一份"。 ### 2. `tasks/001-TCP协议对齐与安全修复.md`（66 KB）—— 是任务记录，不是协议文档 文件名含"TCP协议"，且 66 KB。它已被完整处理（见下节）。 ## 二、删除已完成的任务文件，并摘出真正的未结待办 `tasks/` **已 gitignore（`.gitignore:27`），是本地草稿区、从不入库**。 `tasks/001` 的 A~AH **全部 ✅ 已完成**，但其**状态头写着"待排期（未开始编码）"** —— 是错的。 按「已完成的任务文件及时清理」，**已删除**；删前把**唯一两项未结**摘成 `tasks/002-未结待办-协议待确认项与长函数重构.md`： 1. **`energy` 数据源待硬件答复**（协议待确认第 13 项，阻塞中）+ 关联的第 16 项； 2. **长函数重构**（已授权未开工）。 > ⚠️ **顺带纠正 001 的两处数字**（实测后才发现，**不能沿用**）： > - 001 记"23 个函数超 80 行"—— **当前实测只有 8 个**（本会话多轮重构已拆掉大部分）； > - 001 记 `migrate.rs::run` 已从 280 拆到 **46 行** —— **拆分本身没被回退** > （`SCHEMA_SQL` 确在 L20、`run` 内 0 个 `CREATE TABLE`），但后续每轮迁移改动都往 `run` 里追加 > （`LEGACY_COLUMN_TARGETS` 对齐、`ensure_active_order_unique`、列注释对齐……）， > **它又长回 174 行，重新成为全仓最长函数** —— 这是一次**重构回归**，已列为第一优先。 > - 实测脚本随 002 一起留在 `tasks/`（该目录不入库，避免下次重新发明）。 ## 三、修复我上一轮搬迁引入的断链（1 处真缺陷 + 1 处机械替换误伤） 搬迁脚本只覆盖了 `docs/<name>` 与 `../<name>` 两种形态，**没覆盖三种情况**，已全部修好并加了体检： | 位置 | 问题 | 修复 | |---|---|---| | `docs/tech/API.md` | 同级相对链接 `](柜控板固件对接文档.md)` 因文件被移走而断链 | → `](../protocol/柜控板固件对接文档.md)` | | `docs/tech/数据模型.md` | 我的替换把 **markdown 链接目标** `](docs/API.md)` 也换成了 `docs/tech/API.md` ⇒ 解析成 `docs/tech/docs/tech/API.md` | 显示文字保留可读路径，**链接目标改回 `API.md`** | | `docs/archive/审查报告…md` | 指向当时已删除的 `./tcp-protocol.md`（历史事实） | 归档**保留原文**，顶部加**归档横幅 + 旧名→现名映射表** | **新增体检方法并实测能发现问题**：遍历 `docs/**/*.md` 的所有相对链接、逐个还原路径判存在性。 修完后复跑 → 只剩归档那一处（按设计保留），已用横幅给出映射。 > 📌 教训（已写进 `docs/README.md` 维护约定）：**移动文档后必须做链接体检**， > 不能只做字符串替换 —— 同级相对链接、以及"写在链接目标里的仓库相对路径"都会被漏掉。 ## 四、文档地图同步更新 `docs/README.md` 新增： - 顶部**「关于到底有几份 TCP 协议文档」**专节：直接回答，并列出"三份内部件何时被删"的历史； - `hardware/` 目录说明； - `protocol/` 明确标注 **⛔ 不要在这里放第二份协议文档**（要补充就改那一份并升版本号）。 `AGENTS.md` 项目结构同步加 `hardware/` 一行。
2026-09-20 04:55:28 +08:00
| [`protocol/`](#protocol设备协议) | **平台设备协议**（TCP，冻结，对硬件工程师交付） | ⭐ **唯一权威** | 硬件工程师、固件、平台 TCP 相关开发 |
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
| [`tech/`](#tech平台技术文档) | **平台技术文档**（开发/运维必读） | ⭐ 权威（各自领域内） | 后端/前端/运维 |
docs: 澄清"唯一 TCP 协议文档"并隔离硬件总线协议；删除已完成任务、摘出未结待办 ## 起因 用户提问：**"我们不是有一个 tcp 协议权威文档了吗？为啥还有其他 tcp 协议文档"** —— 查证后确认：**权威文档只有一份**，但目录布局让人容易误判，且**我上一轮的搬迁引入了一处断链**。 ## 一、查证结果：全仓只有一份 TCP 协议文档 按"是否同时出现 `auth_str`/`status_post`/`bat_in` 等 act 名"全仓扫描，含协议内容的只有： | 文件 | act 命中 | 性质 | |---|---:|---| | `docs/protocol/柜控板固件对接文档.md` | 171 | ⭐ **唯一权威 TCP 协议规格** | | `docs/tech/API.md` | 14 | HTTP 接口文档，TCP 章节**只有一句指回权威文档的链接** | | `AGENTS.md` / `数据模型.md` / `小程序用户端.md` | 13 / 8 / 3 | 规则与存储说明，非协议规格 | | `docs/archive/项目深度分析报告-2026-07-06.md` | 1 | 历史归档 | ⇒ **没有任何第二份 TCP 协议文档。** 用户看到的"另一份"应是下面二者之一（都已处理）： ### 1. `docs/protocol/1TN协议标准_*` —— **不是 TCP 协议** 它是**仓控板 ↔ 翌工电源的 RS485 总线协议**（另一条物理链路）。与 TCP 权威文档同放 `protocol/`，名字又像"协议标准"，极易被当成第二份平台协议。 **已移到新目录 `docs/hardware/`**（硬件侧总线协议），并在两处都写明"**不是**平台 TCP 协议"。 **结果：`docs/protocol/` 下有且仅有一个文件** —— 一眼就能确认"只有一份"。 ### 2. `tasks/001-TCP协议对齐与安全修复.md`（66 KB）—— 是任务记录，不是协议文档 文件名含"TCP协议"，且 66 KB。它已被完整处理（见下节）。 ## 二、删除已完成的任务文件，并摘出真正的未结待办 `tasks/` **已 gitignore（`.gitignore:27`），是本地草稿区、从不入库**。 `tasks/001` 的 A~AH **全部 ✅ 已完成**，但其**状态头写着"待排期（未开始编码）"** —— 是错的。 按「已完成的任务文件及时清理」，**已删除**；删前把**唯一两项未结**摘成 `tasks/002-未结待办-协议待确认项与长函数重构.md`： 1. **`energy` 数据源待硬件答复**（协议待确认第 13 项，阻塞中）+ 关联的第 16 项； 2. **长函数重构**（已授权未开工）。 > ⚠️ **顺带纠正 001 的两处数字**（实测后才发现，**不能沿用**）： > - 001 记"23 个函数超 80 行"—— **当前实测只有 8 个**（本会话多轮重构已拆掉大部分）； > - 001 记 `migrate.rs::run` 已从 280 拆到 **46 行** —— **拆分本身没被回退** > （`SCHEMA_SQL` 确在 L20、`run` 内 0 个 `CREATE TABLE`），但后续每轮迁移改动都往 `run` 里追加 > （`LEGACY_COLUMN_TARGETS` 对齐、`ensure_active_order_unique`、列注释对齐……）， > **它又长回 174 行，重新成为全仓最长函数** —— 这是一次**重构回归**，已列为第一优先。 > - 实测脚本随 002 一起留在 `tasks/`（该目录不入库，避免下次重新发明）。 ## 三、修复我上一轮搬迁引入的断链（1 处真缺陷 + 1 处机械替换误伤） 搬迁脚本只覆盖了 `docs/<name>` 与 `../<name>` 两种形态，**没覆盖三种情况**，已全部修好并加了体检： | 位置 | 问题 | 修复 | |---|---|---| | `docs/tech/API.md` | 同级相对链接 `](柜控板固件对接文档.md)` 因文件被移走而断链 | → `](../protocol/柜控板固件对接文档.md)` | | `docs/tech/数据模型.md` | 我的替换把 **markdown 链接目标** `](docs/API.md)` 也换成了 `docs/tech/API.md` ⇒ 解析成 `docs/tech/docs/tech/API.md` | 显示文字保留可读路径，**链接目标改回 `API.md`** | | `docs/archive/审查报告…md` | 指向当时已删除的 `./tcp-protocol.md`（历史事实） | 归档**保留原文**，顶部加**归档横幅 + 旧名→现名映射表** | **新增体检方法并实测能发现问题**：遍历 `docs/**/*.md` 的所有相对链接、逐个还原路径判存在性。 修完后复跑 → 只剩归档那一处（按设计保留），已用横幅给出映射。 > 📌 教训（已写进 `docs/README.md` 维护约定）：**移动文档后必须做链接体检**， > 不能只做字符串替换 —— 同级相对链接、以及"写在链接目标里的仓库相对路径"都会被漏掉。 ## 四、文档地图同步更新 `docs/README.md` 新增： - 顶部**「关于到底有几份 TCP 协议文档」**专节：直接回答，并列出"三份内部件何时被删"的历史； - `hardware/` 目录说明； - `protocol/` 明确标注 **⛔ 不要在这里放第二份协议文档**（要补充就改那一份并升版本号）。 `AGENTS.md` 项目结构同步加 `hardware/` 一行。
2026-09-20 04:55:28 +08:00
| [`hardware/`](#hardware硬件侧总线协议) | **硬件侧总线协议**（RS485，**不是**平台 TCP 协议） | 硬件事实依据 | 硬件工程师、对接电源/BMS 的人 |
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
| [`contract/`](#contract合同与规格) | **合同、规格、验收标准**（商务依据） | 事实依据，但不描述实现 | PM、验收方、新人了解范围 |
| [`compound-notes/`](#compound-notes经验沉淀) | **单点经验笔记**（踩坑/技法） | 参考，非权威 | 遇到同类问题的人 |
## 二、谁是权威（口径优先级，避免"两份文档谁对"的扯皮）
docs: 澄清"唯一 TCP 协议文档"并隔离硬件总线协议；删除已完成任务、摘出未结待办 ## 起因 用户提问：**"我们不是有一个 tcp 协议权威文档了吗？为啥还有其他 tcp 协议文档"** —— 查证后确认：**权威文档只有一份**，但目录布局让人容易误判，且**我上一轮的搬迁引入了一处断链**。 ## 一、查证结果：全仓只有一份 TCP 协议文档 按"是否同时出现 `auth_str`/`status_post`/`bat_in` 等 act 名"全仓扫描，含协议内容的只有： | 文件 | act 命中 | 性质 | |---|---:|---| | `docs/protocol/柜控板固件对接文档.md` | 171 | ⭐ **唯一权威 TCP 协议规格** | | `docs/tech/API.md` | 14 | HTTP 接口文档，TCP 章节**只有一句指回权威文档的链接** | | `AGENTS.md` / `数据模型.md` / `小程序用户端.md` | 13 / 8 / 3 | 规则与存储说明，非协议规格 | | `docs/archive/项目深度分析报告-2026-07-06.md` | 1 | 历史归档 | ⇒ **没有任何第二份 TCP 协议文档。** 用户看到的"另一份"应是下面二者之一（都已处理）： ### 1. `docs/protocol/1TN协议标准_*` —— **不是 TCP 协议** 它是**仓控板 ↔ 翌工电源的 RS485 总线协议**（另一条物理链路）。与 TCP 权威文档同放 `protocol/`，名字又像"协议标准"，极易被当成第二份平台协议。 **已移到新目录 `docs/hardware/`**（硬件侧总线协议），并在两处都写明"**不是**平台 TCP 协议"。 **结果：`docs/protocol/` 下有且仅有一个文件** —— 一眼就能确认"只有一份"。 ### 2. `tasks/001-TCP协议对齐与安全修复.md`（66 KB）—— 是任务记录，不是协议文档 文件名含"TCP协议"，且 66 KB。它已被完整处理（见下节）。 ## 二、删除已完成的任务文件，并摘出真正的未结待办 `tasks/` **已 gitignore（`.gitignore:27`），是本地草稿区、从不入库**。 `tasks/001` 的 A~AH **全部 ✅ 已完成**，但其**状态头写着"待排期（未开始编码）"** —— 是错的。 按「已完成的任务文件及时清理」，**已删除**；删前把**唯一两项未结**摘成 `tasks/002-未结待办-协议待确认项与长函数重构.md`： 1. **`energy` 数据源待硬件答复**（协议待确认第 13 项，阻塞中）+ 关联的第 16 项； 2. **长函数重构**（已授权未开工）。 > ⚠️ **顺带纠正 001 的两处数字**（实测后才发现，**不能沿用**）： > - 001 记"23 个函数超 80 行"—— **当前实测只有 8 个**（本会话多轮重构已拆掉大部分）； > - 001 记 `migrate.rs::run` 已从 280 拆到 **46 行** —— **拆分本身没被回退** > （`SCHEMA_SQL` 确在 L20、`run` 内 0 个 `CREATE TABLE`），但后续每轮迁移改动都往 `run` 里追加 > （`LEGACY_COLUMN_TARGETS` 对齐、`ensure_active_order_unique`、列注释对齐……）， > **它又长回 174 行，重新成为全仓最长函数** —— 这是一次**重构回归**，已列为第一优先。 > - 实测脚本随 002 一起留在 `tasks/`（该目录不入库，避免下次重新发明）。 ## 三、修复我上一轮搬迁引入的断链（1 处真缺陷 + 1 处机械替换误伤） 搬迁脚本只覆盖了 `docs/<name>` 与 `../<name>` 两种形态，**没覆盖三种情况**，已全部修好并加了体检： | 位置 | 问题 | 修复 | |---|---|---| | `docs/tech/API.md` | 同级相对链接 `](柜控板固件对接文档.md)` 因文件被移走而断链 | → `](../protocol/柜控板固件对接文档.md)` | | `docs/tech/数据模型.md` | 我的替换把 **markdown 链接目标** `](docs/API.md)` 也换成了 `docs/tech/API.md` ⇒ 解析成 `docs/tech/docs/tech/API.md` | 显示文字保留可读路径，**链接目标改回 `API.md`** | | `docs/archive/审查报告…md` | 指向当时已删除的 `./tcp-protocol.md`（历史事实） | 归档**保留原文**，顶部加**归档横幅 + 旧名→现名映射表** | **新增体检方法并实测能发现问题**：遍历 `docs/**/*.md` 的所有相对链接、逐个还原路径判存在性。 修完后复跑 → 只剩归档那一处（按设计保留），已用横幅给出映射。 > 📌 教训（已写进 `docs/README.md` 维护约定）：**移动文档后必须做链接体检**， > 不能只做字符串替换 —— 同级相对链接、以及"写在链接目标里的仓库相对路径"都会被漏掉。 ## 四、文档地图同步更新 `docs/README.md` 新增： - 顶部**「关于到底有几份 TCP 协议文档」**专节：直接回答，并列出"三份内部件何时被删"的历史； - `hardware/` 目录说明； - `protocol/` 明确标注 **⛔ 不要在这里放第二份协议文档**（要补充就改那一份并升版本号）。 `AGENTS.md` 项目结构同步加 `hardware/` 一行。
2026-09-20 04:55:28 +08:00
> ### ⚠️ 关于"到底有几份 TCP 协议文档"
>
> **全仓只有一份**：`docs/protocol/柜控板固件对接文档.md`。
> `docs/protocol/` 目录下**有且仅有这一个文件** —— 这是刻意的，便于一眼确认。
>
> 历史上曾有三份内部件，已在协议 v1.1 前后删除（用户指示：只保留一份权威）：
> `docs/tcp-protocol.md`、`docs/TCP报文交互示例.md`、`docs/柜控板-平台TCP接口文档.md`。
>
> 若你看到的"另一份 TCP 协议"是下面这些，它们**都不是平台 TCP 协议**：
> - `docs/hardware/1TN协议标准_*` —— **RS485 总线协议**（仓控板 ↔ 翌工电源），另一条物理链路；
> - `docs/tech/API.md` 的「TCP 设备通讯协议」章节 —— 只有一句**指回权威文档的链接**，不重复内容；
> - `tasks/*.md` —— 任务草稿（**`tasks/` 已 gitignore，不入库**），文件名可能含"TCP协议"
> 但那是任务记录，不是规格。
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
1. **`protocol/柜控板固件对接文档.md`** —— 设备协议（帧格式 / `act` / 字段名 / 签名 / `id` 规则）
的**唯一权威**。协议**冻结**，设备端固件不可改。
2. **根目录 `AGENTS.md`** —— **平台侧实现口径**的权威：Redis 键与字段、接口行为、库结构、
验收流程、部署注意事项。与 `tech/API.md` 的平台存储/行为描述冲突时，**以 `AGENTS.md` 为准**
（它的每一条都按代码契约与库实测核对过）。
3. **`tech/API.md`** —— **HTTP 接口清单与响应结构**的权威（含数据单位规范）。
4. **代码与文档冲突时**：先确认是不是代码错；确认代码对就**改文档**并在报告里点出。
## 三、逐目录说明
docs: 澄清"唯一 TCP 协议文档"并隔离硬件总线协议；删除已完成任务、摘出未结待办 ## 起因 用户提问：**"我们不是有一个 tcp 协议权威文档了吗？为啥还有其他 tcp 协议文档"** —— 查证后确认：**权威文档只有一份**，但目录布局让人容易误判，且**我上一轮的搬迁引入了一处断链**。 ## 一、查证结果：全仓只有一份 TCP 协议文档 按"是否同时出现 `auth_str`/`status_post`/`bat_in` 等 act 名"全仓扫描，含协议内容的只有： | 文件 | act 命中 | 性质 | |---|---:|---| | `docs/protocol/柜控板固件对接文档.md` | 171 | ⭐ **唯一权威 TCP 协议规格** | | `docs/tech/API.md` | 14 | HTTP 接口文档，TCP 章节**只有一句指回权威文档的链接** | | `AGENTS.md` / `数据模型.md` / `小程序用户端.md` | 13 / 8 / 3 | 规则与存储说明，非协议规格 | | `docs/archive/项目深度分析报告-2026-07-06.md` | 1 | 历史归档 | ⇒ **没有任何第二份 TCP 协议文档。** 用户看到的"另一份"应是下面二者之一（都已处理）： ### 1. `docs/protocol/1TN协议标准_*` —— **不是 TCP 协议** 它是**仓控板 ↔ 翌工电源的 RS485 总线协议**（另一条物理链路）。与 TCP 权威文档同放 `protocol/`，名字又像"协议标准"，极易被当成第二份平台协议。 **已移到新目录 `docs/hardware/`**（硬件侧总线协议），并在两处都写明"**不是**平台 TCP 协议"。 **结果：`docs/protocol/` 下有且仅有一个文件** —— 一眼就能确认"只有一份"。 ### 2. `tasks/001-TCP协议对齐与安全修复.md`（66 KB）—— 是任务记录，不是协议文档 文件名含"TCP协议"，且 66 KB。它已被完整处理（见下节）。 ## 二、删除已完成的任务文件，并摘出真正的未结待办 `tasks/` **已 gitignore（`.gitignore:27`），是本地草稿区、从不入库**。 `tasks/001` 的 A~AH **全部 ✅ 已完成**，但其**状态头写着"待排期（未开始编码）"** —— 是错的。 按「已完成的任务文件及时清理」，**已删除**；删前把**唯一两项未结**摘成 `tasks/002-未结待办-协议待确认项与长函数重构.md`： 1. **`energy` 数据源待硬件答复**（协议待确认第 13 项，阻塞中）+ 关联的第 16 项； 2. **长函数重构**（已授权未开工）。 > ⚠️ **顺带纠正 001 的两处数字**（实测后才发现，**不能沿用**）： > - 001 记"23 个函数超 80 行"—— **当前实测只有 8 个**（本会话多轮重构已拆掉大部分）； > - 001 记 `migrate.rs::run` 已从 280 拆到 **46 行** —— **拆分本身没被回退** > （`SCHEMA_SQL` 确在 L20、`run` 内 0 个 `CREATE TABLE`），但后续每轮迁移改动都往 `run` 里追加 > （`LEGACY_COLUMN_TARGETS` 对齐、`ensure_active_order_unique`、列注释对齐……）， > **它又长回 174 行，重新成为全仓最长函数** —— 这是一次**重构回归**，已列为第一优先。 > - 实测脚本随 002 一起留在 `tasks/`（该目录不入库，避免下次重新发明）。 ## 三、修复我上一轮搬迁引入的断链（1 处真缺陷 + 1 处机械替换误伤） 搬迁脚本只覆盖了 `docs/<name>` 与 `../<name>` 两种形态，**没覆盖三种情况**，已全部修好并加了体检： | 位置 | 问题 | 修复 | |---|---|---| | `docs/tech/API.md` | 同级相对链接 `](柜控板固件对接文档.md)` 因文件被移走而断链 | → `](../protocol/柜控板固件对接文档.md)` | | `docs/tech/数据模型.md` | 我的替换把 **markdown 链接目标** `](docs/API.md)` 也换成了 `docs/tech/API.md` ⇒ 解析成 `docs/tech/docs/tech/API.md` | 显示文字保留可读路径，**链接目标改回 `API.md`** | | `docs/archive/审查报告…md` | 指向当时已删除的 `./tcp-protocol.md`（历史事实） | 归档**保留原文**，顶部加**归档横幅 + 旧名→现名映射表** | **新增体检方法并实测能发现问题**：遍历 `docs/**/*.md` 的所有相对链接、逐个还原路径判存在性。 修完后复跑 → 只剩归档那一处（按设计保留），已用横幅给出映射。 > 📌 教训（已写进 `docs/README.md` 维护约定）：**移动文档后必须做链接体检**， > 不能只做字符串替换 —— 同级相对链接、以及"写在链接目标里的仓库相对路径"都会被漏掉。 ## 四、文档地图同步更新 `docs/README.md` 新增： - 顶部**「关于到底有几份 TCP 协议文档」**专节：直接回答，并列出"三份内部件何时被删"的历史； - `hardware/` 目录说明； - `protocol/` 明确标注 **⛔ 不要在这里放第二份协议文档**（要补充就改那一份并升版本号）。 `AGENTS.md` 项目结构同步加 `hardware/` 一行。
2026-09-20 04:55:28 +08:00
### protocol/ —— 平台设备协议（**只有一份**）
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
| 文件 | 说明 |
|------|------|
| `柜控板固件对接文档.md` | **唯一权威 TCP 文档**（v1.1.1）。帧格式、通用规则（`act`/`suc`/`msg_id`/60 秒超时/登录门控）、指令清单、签名算法与自测向量、安全码自愈、带注释报文示例（附 A）、变更记录（附 B）。**既是内部文档也可直接对外交付。** |
docs: 澄清"唯一 TCP 协议文档"并隔离硬件总线协议；删除已完成任务、摘出未结待办 ## 起因 用户提问：**"我们不是有一个 tcp 协议权威文档了吗？为啥还有其他 tcp 协议文档"** —— 查证后确认：**权威文档只有一份**，但目录布局让人容易误判，且**我上一轮的搬迁引入了一处断链**。 ## 一、查证结果：全仓只有一份 TCP 协议文档 按"是否同时出现 `auth_str`/`status_post`/`bat_in` 等 act 名"全仓扫描，含协议内容的只有： | 文件 | act 命中 | 性质 | |---|---:|---| | `docs/protocol/柜控板固件对接文档.md` | 171 | ⭐ **唯一权威 TCP 协议规格** | | `docs/tech/API.md` | 14 | HTTP 接口文档，TCP 章节**只有一句指回权威文档的链接** | | `AGENTS.md` / `数据模型.md` / `小程序用户端.md` | 13 / 8 / 3 | 规则与存储说明，非协议规格 | | `docs/archive/项目深度分析报告-2026-07-06.md` | 1 | 历史归档 | ⇒ **没有任何第二份 TCP 协议文档。** 用户看到的"另一份"应是下面二者之一（都已处理）： ### 1. `docs/protocol/1TN协议标准_*` —— **不是 TCP 协议** 它是**仓控板 ↔ 翌工电源的 RS485 总线协议**（另一条物理链路）。与 TCP 权威文档同放 `protocol/`，名字又像"协议标准"，极易被当成第二份平台协议。 **已移到新目录 `docs/hardware/`**（硬件侧总线协议），并在两处都写明"**不是**平台 TCP 协议"。 **结果：`docs/protocol/` 下有且仅有一个文件** —— 一眼就能确认"只有一份"。 ### 2. `tasks/001-TCP协议对齐与安全修复.md`（66 KB）—— 是任务记录，不是协议文档 文件名含"TCP协议"，且 66 KB。它已被完整处理（见下节）。 ## 二、删除已完成的任务文件，并摘出真正的未结待办 `tasks/` **已 gitignore（`.gitignore:27`），是本地草稿区、从不入库**。 `tasks/001` 的 A~AH **全部 ✅ 已完成**，但其**状态头写着"待排期（未开始编码）"** —— 是错的。 按「已完成的任务文件及时清理」，**已删除**；删前把**唯一两项未结**摘成 `tasks/002-未结待办-协议待确认项与长函数重构.md`： 1. **`energy` 数据源待硬件答复**（协议待确认第 13 项，阻塞中）+ 关联的第 16 项； 2. **长函数重构**（已授权未开工）。 > ⚠️ **顺带纠正 001 的两处数字**（实测后才发现，**不能沿用**）： > - 001 记"23 个函数超 80 行"—— **当前实测只有 8 个**（本会话多轮重构已拆掉大部分）； > - 001 记 `migrate.rs::run` 已从 280 拆到 **46 行** —— **拆分本身没被回退** > （`SCHEMA_SQL` 确在 L20、`run` 内 0 个 `CREATE TABLE`），但后续每轮迁移改动都往 `run` 里追加 > （`LEGACY_COLUMN_TARGETS` 对齐、`ensure_active_order_unique`、列注释对齐……）， > **它又长回 174 行，重新成为全仓最长函数** —— 这是一次**重构回归**，已列为第一优先。 > - 实测脚本随 002 一起留在 `tasks/`（该目录不入库，避免下次重新发明）。 ## 三、修复我上一轮搬迁引入的断链（1 处真缺陷 + 1 处机械替换误伤） 搬迁脚本只覆盖了 `docs/<name>` 与 `../<name>` 两种形态，**没覆盖三种情况**，已全部修好并加了体检： | 位置 | 问题 | 修复 | |---|---|---| | `docs/tech/API.md` | 同级相对链接 `](柜控板固件对接文档.md)` 因文件被移走而断链 | → `](../protocol/柜控板固件对接文档.md)` | | `docs/tech/数据模型.md` | 我的替换把 **markdown 链接目标** `](docs/API.md)` 也换成了 `docs/tech/API.md` ⇒ 解析成 `docs/tech/docs/tech/API.md` | 显示文字保留可读路径，**链接目标改回 `API.md`** | | `docs/archive/审查报告…md` | 指向当时已删除的 `./tcp-protocol.md`（历史事实） | 归档**保留原文**，顶部加**归档横幅 + 旧名→现名映射表** | **新增体检方法并实测能发现问题**：遍历 `docs/**/*.md` 的所有相对链接、逐个还原路径判存在性。 修完后复跑 → 只剩归档那一处（按设计保留），已用横幅给出映射。 > 📌 教训（已写进 `docs/README.md` 维护约定）：**移动文档后必须做链接体检**， > 不能只做字符串替换 —— 同级相对链接、以及"写在链接目标里的仓库相对路径"都会被漏掉。 ## 四、文档地图同步更新 `docs/README.md` 新增： - 顶部**「关于到底有几份 TCP 协议文档」**专节：直接回答，并列出"三份内部件何时被删"的历史； - `hardware/` 目录说明； - `protocol/` 明确标注 **⛔ 不要在这里放第二份协议文档**（要补充就改那一份并升版本号）。 `AGENTS.md` 项目结构同步加 `hardware/` 一行。
2026-09-20 04:55:28 +08:00
⛔ **不要在这里放第二份协议文档**（哪怕是"内部稿""示例集""补充说明"）——
历史上正是这样分叉出三份，最后对不上。要补充内容就**改这一份并升版本号**（记入它的「附 B」）。
### hardware/ —— 硬件侧总线协议
| 文件 | 说明 |
|------|------|
| `1TN协议标准_YG20240118-1_V1.0.md` | 仓控板 ↔ 电源（苏州翌工）1TN RS485 协议，文本版 |
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
| `1TN协议标准_苏州翌工电源_V1.0.pdf` | 同上，厂家原始 PDF |
chore: 清理过时与误提交产物；取消 archive/（过时就删，历史交给 git） ## 起因 用户问"历史留痕？看看有没有过时的和无用的东西可以删除" —— **不该把"归档"当免检区**。逐项查证后：确认了 3 类该删的、1 类归错类的、1 个不能删的。 ## 一、删除：被"顺手 git add"误带进无关提交的产物 用 `git log --diff-filter=A` 追来历，发现它们**根本不是有意提交的**： | 文件 | 来历 | 判据 | |---|---|---| | `换电柜用锂电池充电器1TN标准通信协议 - RS485 V1.0(1).pdf` | `652bde4`（nginx 路由修复） | 与 `docs/hardware/1TN协议标准_苏州翌工电源_V1.0.pdf` **MD5 完全相同**（`B723A1FC…`）—— 纯重复 | | `package.json` + `package-lock.json` | `652bde4`（同上） | 唯一依赖 `html-docx-js`，**全仓无任何脚本引用**（当次把合同 md 转 docx 的一次性工具残留） | | `9b0d3b8a…jpg` / `d6e6add1…png` / `ea4410ba…jpg` | `8bc7812`（"23 个函数拆分"）/ `999885c`（协议对齐） | **零引用**，且混在与图片毫无关系的重构提交里 —— 误提交的截图 | ## 二、归错类（**不是过时，所以不删**）：`开发文档.md` → `hardware/硬件与系统设计文档.md` 原本被塞进 `archive/`，但通读目录后确认它含**硬件设计内容**，这些在 `AGENTS.md`/`docs/tech/` 里**没有**： 硬件架构、仓控/柜控主板设计、指示灯状态机、充电控制逻辑（握手/双模式/动态调整/无协议模式）、 BMS 协议适配、安全防护联动、性能指标、第三方服务配置。 ⇒ 它是**归错类而非过时**：**硬件部分仍是权威参考**，只有第 7 章（软件平台）被现行文档取代。 已在 `docs/README.md` 写明"两者冲突时软件口径以 `AGENTS.md` 为准"。 ## 三、删除：两份 2026-07-06 报告（**问题已全部解决**） 逐条核对了它们"发现的问题"，**无一条仍然成立**： | 报告 | 当时的问题 | 现状 | |---|---|---| | 深度分析报告 | 敏感信息泄露（AGENTS.md 明文密码） | 已成 `AGENTS.md` 的**明示豁免**条目 | | | 目录名不一致（可能用 taro，需确认） | 已确认 `h5-uniapp`，无 taro | | | `test/` 目录缺失 | `test/` 已存在且有 7 项验收脚本 | | | 温度单位不一致（K×100 vs 0.1°C） | 已统一为 K×100 | | 数据单位审查报告 | SOC/SOH 单位标注错误 | `API.md` 早已重写；该报告基准 `tcp-protocol.md` 已不存在 | ## 四、**不删**：`生产环境.txt`（并修掉自相矛盾的表述） 它是**唯一凭据清单**（阿里云账号/小程序 AppSecret/腾讯地图 key/SSL AccessKey 都在其中）， 且被 `docs/tech/小程序用户端.md` 明确引用为"密钥记录处"。 但原文写着"仅记录在内网 Git 仓库 `生产环境.txt`，**不入代码仓库**"—— **与事实矛盾** （`git ls-files` 实测它**已入库**）。已改为准确表述：只记录在该文件、**绝不写进任何源码/.env**、 **不要删除**（新凭据追加到那里，不要散落别处）。 > 🔐 **留给你的决定**：该文件含大量明文凭据。现策略与 `AGENTS.md`「明文密码」豁免一致（内网仓库）， > 若要收紧，建议把它加入 `.gitignore` 并另存到密码管理器 —— 但这会改变 agent 的直连方式，故未擅自改。 ## 五、取消 `archive/` 目录本身 **不再设归档**。理由：被删内容在 **git 历史里完整可查**（`git log -- <原路径>`）， 归档的"留痕"价值因此为零，却持续制造"这文件还算不算依据"的歧义。 已把该结论写进 `docs/README.md` 的维护约定：**过时就删；仍有价值的归到正确的类。** ## 六、其他归位 - `营业执照.jpg`（主体资质，小程序/备案用）→ `docs/contract/` - 根目录现在只剩 5 个必要文件：`.gitignore` / `AGENTS.md` / `README.md` / `opencode.json` / `生产环境.txt` ## 校验 - docs 相对链接 **0 断链**（搬迁引入的 2 处已在上一提交修好，本次复检通过）； - 已删除文件的残留引用：**仅剩 `docs/README.md` 的处置记录/映射表**（旧名必须出现，属预期）； - `cargo check --all-targets` 两服务零 error/warning（本次只动文档与仓库清理，未碰源码逻辑）。
2026-09-20 05:00:29 +08:00
| `硬件与系统设计文档.md` | **硬件与系统设计原文**（46 KB）：硬件架构、仓控/柜控主板设计、指示灯状态机、充电控制逻辑（握手/双模式/动态调整/无协议模式）、BMS 协议适配、安全防护联动、性能指标、第三方服务配置。**硬件侧的主规格文档。** |
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
chore: 清理过时与误提交产物；取消 archive/（过时就删，历史交给 git） ## 起因 用户问"历史留痕？看看有没有过时的和无用的东西可以删除" —— **不该把"归档"当免检区**。逐项查证后：确认了 3 类该删的、1 类归错类的、1 个不能删的。 ## 一、删除：被"顺手 git add"误带进无关提交的产物 用 `git log --diff-filter=A` 追来历，发现它们**根本不是有意提交的**： | 文件 | 来历 | 判据 | |---|---|---| | `换电柜用锂电池充电器1TN标准通信协议 - RS485 V1.0(1).pdf` | `652bde4`（nginx 路由修复） | 与 `docs/hardware/1TN协议标准_苏州翌工电源_V1.0.pdf` **MD5 完全相同**（`B723A1FC…`）—— 纯重复 | | `package.json` + `package-lock.json` | `652bde4`（同上） | 唯一依赖 `html-docx-js`，**全仓无任何脚本引用**（当次把合同 md 转 docx 的一次性工具残留） | | `9b0d3b8a…jpg` / `d6e6add1…png` / `ea4410ba…jpg` | `8bc7812`（"23 个函数拆分"）/ `999885c`（协议对齐） | **零引用**，且混在与图片毫无关系的重构提交里 —— 误提交的截图 | ## 二、归错类（**不是过时，所以不删**）：`开发文档.md` → `hardware/硬件与系统设计文档.md` 原本被塞进 `archive/`，但通读目录后确认它含**硬件设计内容**，这些在 `AGENTS.md`/`docs/tech/` 里**没有**： 硬件架构、仓控/柜控主板设计、指示灯状态机、充电控制逻辑（握手/双模式/动态调整/无协议模式）、 BMS 协议适配、安全防护联动、性能指标、第三方服务配置。 ⇒ 它是**归错类而非过时**：**硬件部分仍是权威参考**，只有第 7 章（软件平台）被现行文档取代。 已在 `docs/README.md` 写明"两者冲突时软件口径以 `AGENTS.md` 为准"。 ## 三、删除：两份 2026-07-06 报告（**问题已全部解决**） 逐条核对了它们"发现的问题"，**无一条仍然成立**： | 报告 | 当时的问题 | 现状 | |---|---|---| | 深度分析报告 | 敏感信息泄露（AGENTS.md 明文密码） | 已成 `AGENTS.md` 的**明示豁免**条目 | | | 目录名不一致（可能用 taro，需确认） | 已确认 `h5-uniapp`，无 taro | | | `test/` 目录缺失 | `test/` 已存在且有 7 项验收脚本 | | | 温度单位不一致（K×100 vs 0.1°C） | 已统一为 K×100 | | 数据单位审查报告 | SOC/SOH 单位标注错误 | `API.md` 早已重写；该报告基准 `tcp-protocol.md` 已不存在 | ## 四、**不删**：`生产环境.txt`（并修掉自相矛盾的表述） 它是**唯一凭据清单**（阿里云账号/小程序 AppSecret/腾讯地图 key/SSL AccessKey 都在其中）， 且被 `docs/tech/小程序用户端.md` 明确引用为"密钥记录处"。 但原文写着"仅记录在内网 Git 仓库 `生产环境.txt`，**不入代码仓库**"—— **与事实矛盾** （`git ls-files` 实测它**已入库**）。已改为准确表述：只记录在该文件、**绝不写进任何源码/.env**、 **不要删除**（新凭据追加到那里，不要散落别处）。 > 🔐 **留给你的决定**：该文件含大量明文凭据。现策略与 `AGENTS.md`「明文密码」豁免一致（内网仓库）， > 若要收紧，建议把它加入 `.gitignore` 并另存到密码管理器 —— 但这会改变 agent 的直连方式，故未擅自改。 ## 五、取消 `archive/` 目录本身 **不再设归档**。理由：被删内容在 **git 历史里完整可查**（`git log -- <原路径>`）， 归档的"留痕"价值因此为零，却持续制造"这文件还算不算依据"的歧义。 已把该结论写进 `docs/README.md` 的维护约定：**过时就删；仍有价值的归到正确的类。** ## 六、其他归位 - `营业执照.jpg`（主体资质，小程序/备案用）→ `docs/contract/` - 根目录现在只剩 5 个必要文件：`.gitignore` / `AGENTS.md` / `README.md` / `opencode.json` / `生产环境.txt` ## 校验 - docs 相对链接 **0 断链**（搬迁引入的 2 处已在上一提交修好，本次复检通过）； - 已删除文件的残留引用：**仅剩 `docs/README.md` 的处置记录/映射表**（旧名必须出现，属预期）； - `cargo check --all-targets` 两服务零 error/warning（本次只动文档与仓库清理，未碰源码逻辑）。
2026-09-20 05:00:29 +08:00
> ⚠️ `1TN协议标准_*` 是**另一条物理链路**（柜内 485 总线），**与平台 TCP 协议无关** ——
docs: 澄清"唯一 TCP 协议文档"并隔离硬件总线协议；删除已完成任务、摘出未结待办 ## 起因 用户提问：**"我们不是有一个 tcp 协议权威文档了吗？为啥还有其他 tcp 协议文档"** —— 查证后确认：**权威文档只有一份**，但目录布局让人容易误判，且**我上一轮的搬迁引入了一处断链**。 ## 一、查证结果：全仓只有一份 TCP 协议文档 按"是否同时出现 `auth_str`/`status_post`/`bat_in` 等 act 名"全仓扫描，含协议内容的只有： | 文件 | act 命中 | 性质 | |---|---:|---| | `docs/protocol/柜控板固件对接文档.md` | 171 | ⭐ **唯一权威 TCP 协议规格** | | `docs/tech/API.md` | 14 | HTTP 接口文档，TCP 章节**只有一句指回权威文档的链接** | | `AGENTS.md` / `数据模型.md` / `小程序用户端.md` | 13 / 8 / 3 | 规则与存储说明，非协议规格 | | `docs/archive/项目深度分析报告-2026-07-06.md` | 1 | 历史归档 | ⇒ **没有任何第二份 TCP 协议文档。** 用户看到的"另一份"应是下面二者之一（都已处理）： ### 1. `docs/protocol/1TN协议标准_*` —— **不是 TCP 协议** 它是**仓控板 ↔ 翌工电源的 RS485 总线协议**（另一条物理链路）。与 TCP 权威文档同放 `protocol/`，名字又像"协议标准"，极易被当成第二份平台协议。 **已移到新目录 `docs/hardware/`**（硬件侧总线协议），并在两处都写明"**不是**平台 TCP 协议"。 **结果：`docs/protocol/` 下有且仅有一个文件** —— 一眼就能确认"只有一份"。 ### 2. `tasks/001-TCP协议对齐与安全修复.md`（66 KB）—— 是任务记录，不是协议文档 文件名含"TCP协议"，且 66 KB。它已被完整处理（见下节）。 ## 二、删除已完成的任务文件，并摘出真正的未结待办 `tasks/` **已 gitignore（`.gitignore:27`），是本地草稿区、从不入库**。 `tasks/001` 的 A~AH **全部 ✅ 已完成**，但其**状态头写着"待排期（未开始编码）"** —— 是错的。 按「已完成的任务文件及时清理」，**已删除**；删前把**唯一两项未结**摘成 `tasks/002-未结待办-协议待确认项与长函数重构.md`： 1. **`energy` 数据源待硬件答复**（协议待确认第 13 项，阻塞中）+ 关联的第 16 项； 2. **长函数重构**（已授权未开工）。 > ⚠️ **顺带纠正 001 的两处数字**（实测后才发现，**不能沿用**）： > - 001 记"23 个函数超 80 行"—— **当前实测只有 8 个**（本会话多轮重构已拆掉大部分）； > - 001 记 `migrate.rs::run` 已从 280 拆到 **46 行** —— **拆分本身没被回退** > （`SCHEMA_SQL` 确在 L20、`run` 内 0 个 `CREATE TABLE`），但后续每轮迁移改动都往 `run` 里追加 > （`LEGACY_COLUMN_TARGETS` 对齐、`ensure_active_order_unique`、列注释对齐……）， > **它又长回 174 行，重新成为全仓最长函数** —— 这是一次**重构回归**，已列为第一优先。 > - 实测脚本随 002 一起留在 `tasks/`（该目录不入库，避免下次重新发明）。 ## 三、修复我上一轮搬迁引入的断链（1 处真缺陷 + 1 处机械替换误伤） 搬迁脚本只覆盖了 `docs/<name>` 与 `../<name>` 两种形态，**没覆盖三种情况**，已全部修好并加了体检： | 位置 | 问题 | 修复 | |---|---|---| | `docs/tech/API.md` | 同级相对链接 `](柜控板固件对接文档.md)` 因文件被移走而断链 | → `](../protocol/柜控板固件对接文档.md)` | | `docs/tech/数据模型.md` | 我的替换把 **markdown 链接目标** `](docs/API.md)` 也换成了 `docs/tech/API.md` ⇒ 解析成 `docs/tech/docs/tech/API.md` | 显示文字保留可读路径，**链接目标改回 `API.md`** | | `docs/archive/审查报告…md` | 指向当时已删除的 `./tcp-protocol.md`（历史事实） | 归档**保留原文**，顶部加**归档横幅 + 旧名→现名映射表** | **新增体检方法并实测能发现问题**：遍历 `docs/**/*.md` 的所有相对链接、逐个还原路径判存在性。 修完后复跑 → 只剩归档那一处（按设计保留），已用横幅给出映射。 > 📌 教训（已写进 `docs/README.md` 维护约定）：**移动文档后必须做链接体检**， > 不能只做字符串替换 —— 同级相对链接、以及"写在链接目标里的仓库相对路径"都会被漏掉。 ## 四、文档地图同步更新 `docs/README.md` 新增： - 顶部**「关于到底有几份 TCP 协议文档」**专节：直接回答，并列出"三份内部件何时被删"的历史； - `hardware/` 目录说明； - `protocol/` 明确标注 **⛔ 不要在这里放第二份协议文档**（要补充就改那一份并升版本号）。 `AGENTS.md` 项目结构同步加 `hardware/` 一行。
2026-09-20 04:55:28 +08:00
> 别把它当成"第二份 TCP 协议"。硬件侧的其它总线协议（BMS：星恒 Modbus / 天能 485）如需入库，也放这里。
chore: 清理过时与误提交产物；取消 archive/（过时就删，历史交给 git） ## 起因 用户问"历史留痕？看看有没有过时的和无用的东西可以删除" —— **不该把"归档"当免检区**。逐项查证后：确认了 3 类该删的、1 类归错类的、1 个不能删的。 ## 一、删除：被"顺手 git add"误带进无关提交的产物 用 `git log --diff-filter=A` 追来历，发现它们**根本不是有意提交的**： | 文件 | 来历 | 判据 | |---|---|---| | `换电柜用锂电池充电器1TN标准通信协议 - RS485 V1.0(1).pdf` | `652bde4`（nginx 路由修复） | 与 `docs/hardware/1TN协议标准_苏州翌工电源_V1.0.pdf` **MD5 完全相同**（`B723A1FC…`）—— 纯重复 | | `package.json` + `package-lock.json` | `652bde4`（同上） | 唯一依赖 `html-docx-js`，**全仓无任何脚本引用**（当次把合同 md 转 docx 的一次性工具残留） | | `9b0d3b8a…jpg` / `d6e6add1…png` / `ea4410ba…jpg` | `8bc7812`（"23 个函数拆分"）/ `999885c`（协议对齐） | **零引用**，且混在与图片毫无关系的重构提交里 —— 误提交的截图 | ## 二、归错类（**不是过时，所以不删**）：`开发文档.md` → `hardware/硬件与系统设计文档.md` 原本被塞进 `archive/`，但通读目录后确认它含**硬件设计内容**，这些在 `AGENTS.md`/`docs/tech/` 里**没有**： 硬件架构、仓控/柜控主板设计、指示灯状态机、充电控制逻辑（握手/双模式/动态调整/无协议模式）、 BMS 协议适配、安全防护联动、性能指标、第三方服务配置。 ⇒ 它是**归错类而非过时**：**硬件部分仍是权威参考**，只有第 7 章（软件平台）被现行文档取代。 已在 `docs/README.md` 写明"两者冲突时软件口径以 `AGENTS.md` 为准"。 ## 三、删除：两份 2026-07-06 报告（**问题已全部解决**） 逐条核对了它们"发现的问题"，**无一条仍然成立**： | 报告 | 当时的问题 | 现状 | |---|---|---| | 深度分析报告 | 敏感信息泄露（AGENTS.md 明文密码） | 已成 `AGENTS.md` 的**明示豁免**条目 | | | 目录名不一致（可能用 taro，需确认） | 已确认 `h5-uniapp`，无 taro | | | `test/` 目录缺失 | `test/` 已存在且有 7 项验收脚本 | | | 温度单位不一致（K×100 vs 0.1°C） | 已统一为 K×100 | | 数据单位审查报告 | SOC/SOH 单位标注错误 | `API.md` 早已重写；该报告基准 `tcp-protocol.md` 已不存在 | ## 四、**不删**：`生产环境.txt`（并修掉自相矛盾的表述） 它是**唯一凭据清单**（阿里云账号/小程序 AppSecret/腾讯地图 key/SSL AccessKey 都在其中）， 且被 `docs/tech/小程序用户端.md` 明确引用为"密钥记录处"。 但原文写着"仅记录在内网 Git 仓库 `生产环境.txt`，**不入代码仓库**"—— **与事实矛盾** （`git ls-files` 实测它**已入库**）。已改为准确表述：只记录在该文件、**绝不写进任何源码/.env**、 **不要删除**（新凭据追加到那里，不要散落别处）。 > 🔐 **留给你的决定**：该文件含大量明文凭据。现策略与 `AGENTS.md`「明文密码」豁免一致（内网仓库）， > 若要收紧，建议把它加入 `.gitignore` 并另存到密码管理器 —— 但这会改变 agent 的直连方式，故未擅自改。 ## 五、取消 `archive/` 目录本身 **不再设归档**。理由：被删内容在 **git 历史里完整可查**（`git log -- <原路径>`）， 归档的"留痕"价值因此为零，却持续制造"这文件还算不算依据"的歧义。 已把该结论写进 `docs/README.md` 的维护约定：**过时就删；仍有价值的归到正确的类。** ## 六、其他归位 - `营业执照.jpg`（主体资质，小程序/备案用）→ `docs/contract/` - 根目录现在只剩 5 个必要文件：`.gitignore` / `AGENTS.md` / `README.md` / `opencode.json` / `生产环境.txt` ## 校验 - docs 相对链接 **0 断链**（搬迁引入的 2 处已在上一提交修好，本次复检通过）； - 已删除文件的残留引用：**仅剩 `docs/README.md` 的处置记录/映射表**（旧名必须出现，属预期）； - `cargo check --all-targets` 两服务零 error/warning（本次只动文档与仓库清理，未碰源码逻辑）。
2026-09-20 05:00:29 +08:00
>
> ⚠️ `硬件与系统设计文档.md` **早于现行实现**：其中**硬件设计部分仍是权威参考**，
> 但**软件平台部分（第 7 章）已被 `AGENTS.md` + `docs/tech/` 取代** ——
> 两者冲突时，软件口径一律以 `AGENTS.md` 为准（它按代码契约与库实测核对过）。
docs: 澄清"唯一 TCP 协议文档"并隔离硬件总线协议；删除已完成任务、摘出未结待办 ## 起因 用户提问：**"我们不是有一个 tcp 协议权威文档了吗？为啥还有其他 tcp 协议文档"** —— 查证后确认：**权威文档只有一份**，但目录布局让人容易误判，且**我上一轮的搬迁引入了一处断链**。 ## 一、查证结果：全仓只有一份 TCP 协议文档 按"是否同时出现 `auth_str`/`status_post`/`bat_in` 等 act 名"全仓扫描，含协议内容的只有： | 文件 | act 命中 | 性质 | |---|---:|---| | `docs/protocol/柜控板固件对接文档.md` | 171 | ⭐ **唯一权威 TCP 协议规格** | | `docs/tech/API.md` | 14 | HTTP 接口文档，TCP 章节**只有一句指回权威文档的链接** | | `AGENTS.md` / `数据模型.md` / `小程序用户端.md` | 13 / 8 / 3 | 规则与存储说明，非协议规格 | | `docs/archive/项目深度分析报告-2026-07-06.md` | 1 | 历史归档 | ⇒ **没有任何第二份 TCP 协议文档。** 用户看到的"另一份"应是下面二者之一（都已处理）： ### 1. `docs/protocol/1TN协议标准_*` —— **不是 TCP 协议** 它是**仓控板 ↔ 翌工电源的 RS485 总线协议**（另一条物理链路）。与 TCP 权威文档同放 `protocol/`，名字又像"协议标准"，极易被当成第二份平台协议。 **已移到新目录 `docs/hardware/`**（硬件侧总线协议），并在两处都写明"**不是**平台 TCP 协议"。 **结果：`docs/protocol/` 下有且仅有一个文件** —— 一眼就能确认"只有一份"。 ### 2. `tasks/001-TCP协议对齐与安全修复.md`（66 KB）—— 是任务记录，不是协议文档 文件名含"TCP协议"，且 66 KB。它已被完整处理（见下节）。 ## 二、删除已完成的任务文件，并摘出真正的未结待办 `tasks/` **已 gitignore（`.gitignore:27`），是本地草稿区、从不入库**。 `tasks/001` 的 A~AH **全部 ✅ 已完成**，但其**状态头写着"待排期（未开始编码）"** —— 是错的。 按「已完成的任务文件及时清理」，**已删除**；删前把**唯一两项未结**摘成 `tasks/002-未结待办-协议待确认项与长函数重构.md`： 1. **`energy` 数据源待硬件答复**（协议待确认第 13 项，阻塞中）+ 关联的第 16 项； 2. **长函数重构**（已授权未开工）。 > ⚠️ **顺带纠正 001 的两处数字**（实测后才发现，**不能沿用**）： > - 001 记"23 个函数超 80 行"—— **当前实测只有 8 个**（本会话多轮重构已拆掉大部分）； > - 001 记 `migrate.rs::run` 已从 280 拆到 **46 行** —— **拆分本身没被回退** > （`SCHEMA_SQL` 确在 L20、`run` 内 0 个 `CREATE TABLE`），但后续每轮迁移改动都往 `run` 里追加 > （`LEGACY_COLUMN_TARGETS` 对齐、`ensure_active_order_unique`、列注释对齐……）， > **它又长回 174 行，重新成为全仓最长函数** —— 这是一次**重构回归**，已列为第一优先。 > - 实测脚本随 002 一起留在 `tasks/`（该目录不入库，避免下次重新发明）。 ## 三、修复我上一轮搬迁引入的断链（1 处真缺陷 + 1 处机械替换误伤） 搬迁脚本只覆盖了 `docs/<name>` 与 `../<name>` 两种形态，**没覆盖三种情况**，已全部修好并加了体检： | 位置 | 问题 | 修复 | |---|---|---| | `docs/tech/API.md` | 同级相对链接 `](柜控板固件对接文档.md)` 因文件被移走而断链 | → `](../protocol/柜控板固件对接文档.md)` | | `docs/tech/数据模型.md` | 我的替换把 **markdown 链接目标** `](docs/API.md)` 也换成了 `docs/tech/API.md` ⇒ 解析成 `docs/tech/docs/tech/API.md` | 显示文字保留可读路径，**链接目标改回 `API.md`** | | `docs/archive/审查报告…md` | 指向当时已删除的 `./tcp-protocol.md`（历史事实） | 归档**保留原文**，顶部加**归档横幅 + 旧名→现名映射表** | **新增体检方法并实测能发现问题**：遍历 `docs/**/*.md` 的所有相对链接、逐个还原路径判存在性。 修完后复跑 → 只剩归档那一处（按设计保留），已用横幅给出映射。 > 📌 教训（已写进 `docs/README.md` 维护约定）：**移动文档后必须做链接体检**， > 不能只做字符串替换 —— 同级相对链接、以及"写在链接目标里的仓库相对路径"都会被漏掉。 ## 四、文档地图同步更新 `docs/README.md` 新增： - 顶部**「关于到底有几份 TCP 协议文档」**专节：直接回答，并列出"三份内部件何时被删"的历史； - `hardware/` 目录说明； - `protocol/` 明确标注 **⛔ 不要在这里放第二份协议文档**（要补充就改那一份并升版本号）。 `AGENTS.md` 项目结构同步加 `hardware/` 一行。
2026-09-20 04:55:28 +08:00
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
### 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`）双份。
chore: 清理过时与误提交产物；取消 archive/（过时就删，历史交给 git） ## 起因 用户问"历史留痕？看看有没有过时的和无用的东西可以删除" —— **不该把"归档"当免检区**。逐项查证后：确认了 3 类该删的、1 类归错类的、1 个不能删的。 ## 一、删除：被"顺手 git add"误带进无关提交的产物 用 `git log --diff-filter=A` 追来历，发现它们**根本不是有意提交的**： | 文件 | 来历 | 判据 | |---|---|---| | `换电柜用锂电池充电器1TN标准通信协议 - RS485 V1.0(1).pdf` | `652bde4`（nginx 路由修复） | 与 `docs/hardware/1TN协议标准_苏州翌工电源_V1.0.pdf` **MD5 完全相同**（`B723A1FC…`）—— 纯重复 | | `package.json` + `package-lock.json` | `652bde4`（同上） | 唯一依赖 `html-docx-js`，**全仓无任何脚本引用**（当次把合同 md 转 docx 的一次性工具残留） | | `9b0d3b8a…jpg` / `d6e6add1…png` / `ea4410ba…jpg` | `8bc7812`（"23 个函数拆分"）/ `999885c`（协议对齐） | **零引用**，且混在与图片毫无关系的重构提交里 —— 误提交的截图 | ## 二、归错类（**不是过时，所以不删**）：`开发文档.md` → `hardware/硬件与系统设计文档.md` 原本被塞进 `archive/`，但通读目录后确认它含**硬件设计内容**，这些在 `AGENTS.md`/`docs/tech/` 里**没有**： 硬件架构、仓控/柜控主板设计、指示灯状态机、充电控制逻辑（握手/双模式/动态调整/无协议模式）、 BMS 协议适配、安全防护联动、性能指标、第三方服务配置。 ⇒ 它是**归错类而非过时**：**硬件部分仍是权威参考**，只有第 7 章（软件平台）被现行文档取代。 已在 `docs/README.md` 写明"两者冲突时软件口径以 `AGENTS.md` 为准"。 ## 三、删除：两份 2026-07-06 报告（**问题已全部解决**） 逐条核对了它们"发现的问题"，**无一条仍然成立**： | 报告 | 当时的问题 | 现状 | |---|---|---| | 深度分析报告 | 敏感信息泄露（AGENTS.md 明文密码） | 已成 `AGENTS.md` 的**明示豁免**条目 | | | 目录名不一致（可能用 taro，需确认） | 已确认 `h5-uniapp`，无 taro | | | `test/` 目录缺失 | `test/` 已存在且有 7 项验收脚本 | | | 温度单位不一致（K×100 vs 0.1°C） | 已统一为 K×100 | | 数据单位审查报告 | SOC/SOH 单位标注错误 | `API.md` 早已重写；该报告基准 `tcp-protocol.md` 已不存在 | ## 四、**不删**：`生产环境.txt`（并修掉自相矛盾的表述） 它是**唯一凭据清单**（阿里云账号/小程序 AppSecret/腾讯地图 key/SSL AccessKey 都在其中）， 且被 `docs/tech/小程序用户端.md` 明确引用为"密钥记录处"。 但原文写着"仅记录在内网 Git 仓库 `生产环境.txt`，**不入代码仓库**"—— **与事实矛盾** （`git ls-files` 实测它**已入库**）。已改为准确表述：只记录在该文件、**绝不写进任何源码/.env**、 **不要删除**（新凭据追加到那里，不要散落别处）。 > 🔐 **留给你的决定**：该文件含大量明文凭据。现策略与 `AGENTS.md`「明文密码」豁免一致（内网仓库）， > 若要收紧，建议把它加入 `.gitignore` 并另存到密码管理器 —— 但这会改变 agent 的直连方式，故未擅自改。 ## 五、取消 `archive/` 目录本身 **不再设归档**。理由：被删内容在 **git 历史里完整可查**（`git log -- <原路径>`）， 归档的"留痕"价值因此为零，却持续制造"这文件还算不算依据"的歧义。 已把该结论写进 `docs/README.md` 的维护约定：**过时就删；仍有价值的归到正确的类。** ## 六、其他归位 - `营业执照.jpg`（主体资质，小程序/备案用）→ `docs/contract/` - 根目录现在只剩 5 个必要文件：`.gitignore` / `AGENTS.md` / `README.md` / `opencode.json` / `生产环境.txt` ## 校验 - docs 相对链接 **0 断链**（搬迁引入的 2 处已在上一提交修好，本次复检通过）； - 已删除文件的残留引用：**仅剩 `docs/README.md` 的处置记录/映射表**（旧名必须出现，属预期）； - `cargo check --all-targets` 两服务零 error/warning（本次只动文档与仓库清理，未碰源码逻辑）。
2026-09-20 05:00:29 +08:00
> 另有 `营业执照.jpg`（主体资质，小程序/备案用）。
>
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
> 用途：**范围与验收的事实依据**。描述"要做什么 / 达到什么标准"，**不描述当前实现**
> ——实现现状一律以 `AGENTS.md` + 代码为准。
### compound-notes/ —— 经验沉淀
单点问题的笔记（如某次 SQL 注入的成因与修法）。**参考性**内容，
遇到同类问题时查；结论若上升为通用规范，应回写进 `AGENTS.md` 的「踩过的坑」。
chore: 清理过时与误提交产物；取消 archive/（过时就删，历史交给 git） ## 起因 用户问"历史留痕？看看有没有过时的和无用的东西可以删除" —— **不该把"归档"当免检区**。逐项查证后：确认了 3 类该删的、1 类归错类的、1 个不能删的。 ## 一、删除：被"顺手 git add"误带进无关提交的产物 用 `git log --diff-filter=A` 追来历，发现它们**根本不是有意提交的**： | 文件 | 来历 | 判据 | |---|---|---| | `换电柜用锂电池充电器1TN标准通信协议 - RS485 V1.0(1).pdf` | `652bde4`（nginx 路由修复） | 与 `docs/hardware/1TN协议标准_苏州翌工电源_V1.0.pdf` **MD5 完全相同**（`B723A1FC…`）—— 纯重复 | | `package.json` + `package-lock.json` | `652bde4`（同上） | 唯一依赖 `html-docx-js`，**全仓无任何脚本引用**（当次把合同 md 转 docx 的一次性工具残留） | | `9b0d3b8a…jpg` / `d6e6add1…png` / `ea4410ba…jpg` | `8bc7812`（"23 个函数拆分"）/ `999885c`（协议对齐） | **零引用**，且混在与图片毫无关系的重构提交里 —— 误提交的截图 | ## 二、归错类（**不是过时，所以不删**）：`开发文档.md` → `hardware/硬件与系统设计文档.md` 原本被塞进 `archive/`，但通读目录后确认它含**硬件设计内容**，这些在 `AGENTS.md`/`docs/tech/` 里**没有**： 硬件架构、仓控/柜控主板设计、指示灯状态机、充电控制逻辑（握手/双模式/动态调整/无协议模式）、 BMS 协议适配、安全防护联动、性能指标、第三方服务配置。 ⇒ 它是**归错类而非过时**：**硬件部分仍是权威参考**，只有第 7 章（软件平台）被现行文档取代。 已在 `docs/README.md` 写明"两者冲突时软件口径以 `AGENTS.md` 为准"。 ## 三、删除：两份 2026-07-06 报告（**问题已全部解决**） 逐条核对了它们"发现的问题"，**无一条仍然成立**： | 报告 | 当时的问题 | 现状 | |---|---|---| | 深度分析报告 | 敏感信息泄露（AGENTS.md 明文密码） | 已成 `AGENTS.md` 的**明示豁免**条目 | | | 目录名不一致（可能用 taro，需确认） | 已确认 `h5-uniapp`，无 taro | | | `test/` 目录缺失 | `test/` 已存在且有 7 项验收脚本 | | | 温度单位不一致（K×100 vs 0.1°C） | 已统一为 K×100 | | 数据单位审查报告 | SOC/SOH 单位标注错误 | `API.md` 早已重写；该报告基准 `tcp-protocol.md` 已不存在 | ## 四、**不删**：`生产环境.txt`（并修掉自相矛盾的表述） 它是**唯一凭据清单**（阿里云账号/小程序 AppSecret/腾讯地图 key/SSL AccessKey 都在其中）， 且被 `docs/tech/小程序用户端.md` 明确引用为"密钥记录处"。 但原文写着"仅记录在内网 Git 仓库 `生产环境.txt`，**不入代码仓库**"—— **与事实矛盾** （`git ls-files` 实测它**已入库**）。已改为准确表述：只记录在该文件、**绝不写进任何源码/.env**、 **不要删除**（新凭据追加到那里，不要散落别处）。 > 🔐 **留给你的决定**：该文件含大量明文凭据。现策略与 `AGENTS.md`「明文密码」豁免一致（内网仓库）， > 若要收紧，建议把它加入 `.gitignore` 并另存到密码管理器 —— 但这会改变 agent 的直连方式，故未擅自改。 ## 五、取消 `archive/` 目录本身 **不再设归档**。理由：被删内容在 **git 历史里完整可查**（`git log -- <原路径>`）， 归档的"留痕"价值因此为零，却持续制造"这文件还算不算依据"的歧义。 已把该结论写进 `docs/README.md` 的维护约定：**过时就删；仍有价值的归到正确的类。** ## 六、其他归位 - `营业执照.jpg`（主体资质，小程序/备案用）→ `docs/contract/` - 根目录现在只剩 5 个必要文件：`.gitignore` / `AGENTS.md` / `README.md` / `opencode.json` / `生产环境.txt` ## 校验 - docs 相对链接 **0 断链**（搬迁引入的 2 处已在上一提交修好，本次复检通过）； - 已删除文件的残留引用：**仅剩 `docs/README.md` 的处置记录/映射表**（旧名必须出现，属预期）； - `cargo check --all-targets` 两服务零 error/warning（本次只动文档与仓库清理，未碰源码逻辑）。
2026-09-20 05:00:29 +08:00
### ~~archive/~~ —— 已取消（2026-09-20）
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
chore: 清理过时与误提交产物；取消 archive/（过时就删，历史交给 git） ## 起因 用户问"历史留痕？看看有没有过时的和无用的东西可以删除" —— **不该把"归档"当免检区**。逐项查证后：确认了 3 类该删的、1 类归错类的、1 个不能删的。 ## 一、删除：被"顺手 git add"误带进无关提交的产物 用 `git log --diff-filter=A` 追来历，发现它们**根本不是有意提交的**： | 文件 | 来历 | 判据 | |---|---|---| | `换电柜用锂电池充电器1TN标准通信协议 - RS485 V1.0(1).pdf` | `652bde4`（nginx 路由修复） | 与 `docs/hardware/1TN协议标准_苏州翌工电源_V1.0.pdf` **MD5 完全相同**（`B723A1FC…`）—— 纯重复 | | `package.json` + `package-lock.json` | `652bde4`（同上） | 唯一依赖 `html-docx-js`，**全仓无任何脚本引用**（当次把合同 md 转 docx 的一次性工具残留） | | `9b0d3b8a…jpg` / `d6e6add1…png` / `ea4410ba…jpg` | `8bc7812`（"23 个函数拆分"）/ `999885c`（协议对齐） | **零引用**，且混在与图片毫无关系的重构提交里 —— 误提交的截图 | ## 二、归错类（**不是过时，所以不删**）：`开发文档.md` → `hardware/硬件与系统设计文档.md` 原本被塞进 `archive/`，但通读目录后确认它含**硬件设计内容**，这些在 `AGENTS.md`/`docs/tech/` 里**没有**： 硬件架构、仓控/柜控主板设计、指示灯状态机、充电控制逻辑（握手/双模式/动态调整/无协议模式）、 BMS 协议适配、安全防护联动、性能指标、第三方服务配置。 ⇒ 它是**归错类而非过时**：**硬件部分仍是权威参考**，只有第 7 章（软件平台）被现行文档取代。 已在 `docs/README.md` 写明"两者冲突时软件口径以 `AGENTS.md` 为准"。 ## 三、删除：两份 2026-07-06 报告（**问题已全部解决**） 逐条核对了它们"发现的问题"，**无一条仍然成立**： | 报告 | 当时的问题 | 现状 | |---|---|---| | 深度分析报告 | 敏感信息泄露（AGENTS.md 明文密码） | 已成 `AGENTS.md` 的**明示豁免**条目 | | | 目录名不一致（可能用 taro，需确认） | 已确认 `h5-uniapp`，无 taro | | | `test/` 目录缺失 | `test/` 已存在且有 7 项验收脚本 | | | 温度单位不一致（K×100 vs 0.1°C） | 已统一为 K×100 | | 数据单位审查报告 | SOC/SOH 单位标注错误 | `API.md` 早已重写；该报告基准 `tcp-protocol.md` 已不存在 | ## 四、**不删**：`生产环境.txt`（并修掉自相矛盾的表述） 它是**唯一凭据清单**（阿里云账号/小程序 AppSecret/腾讯地图 key/SSL AccessKey 都在其中）， 且被 `docs/tech/小程序用户端.md` 明确引用为"密钥记录处"。 但原文写着"仅记录在内网 Git 仓库 `生产环境.txt`，**不入代码仓库**"—— **与事实矛盾** （`git ls-files` 实测它**已入库**）。已改为准确表述：只记录在该文件、**绝不写进任何源码/.env**、 **不要删除**（新凭据追加到那里，不要散落别处）。 > 🔐 **留给你的决定**：该文件含大量明文凭据。现策略与 `AGENTS.md`「明文密码」豁免一致（内网仓库）， > 若要收紧，建议把它加入 `.gitignore` 并另存到密码管理器 —— 但这会改变 agent 的直连方式，故未擅自改。 ## 五、取消 `archive/` 目录本身 **不再设归档**。理由：被删内容在 **git 历史里完整可查**（`git log -- <原路径>`）， 归档的"留痕"价值因此为零，却持续制造"这文件还算不算依据"的歧义。 已把该结论写进 `docs/README.md` 的维护约定：**过时就删；仍有价值的归到正确的类。** ## 六、其他归位 - `营业执照.jpg`（主体资质，小程序/备案用）→ `docs/contract/` - 根目录现在只剩 5 个必要文件：`.gitignore` / `AGENTS.md` / `README.md` / `opencode.json` / `生产环境.txt` ## 校验 - docs 相对链接 **0 断链**（搬迁引入的 2 处已在上一提交修好，本次复检通过）； - 已删除文件的残留引用：**仅剩 `docs/README.md` 的处置记录/映射表**（旧名必须出现，属预期）； - `cargo check --all-targets` 两服务零 error/warning（本次只动文档与仓库清理，未碰源码逻辑）。
2026-09-20 05:00:29 +08:00
**不再设归档目录。** 曾经的 `archive/` 三份文件已按下述依据处置：
| 原文件 | 处置 | 依据 |
|---|---|---|
| `开发文档.md` | **移出归档** → `hardware/硬件与系统设计文档.md` | 它**不是过时文档而是归错类**：含硬件设计（主板、指示灯状态机、充电控制、BMS 适配、防护联动），这些在 `AGENTS.md`/`tech/` 里**没有**。仅第 7 章软件部分被取代。 |
| `审查报告-数据单位一致性-2026-07-06.md` | **删除** | 一次性审查报告，**发现的问题全部已解决**（SOC/SOH 单位标注早已重写；该报告以已不存在的 `tcp-protocol.md` 为基准）。 |
| `项目深度分析报告-2026-07-06.md` | **删除** | 同上。其 4 项"发现的问题"均已失效：明文密码已成**明示豁免**、"可能用 taro"已确认是 `h5-uniapp`、`test/` 已存在、温度单位已统一。 |
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
chore: 清理过时与误提交产物；取消 archive/（过时就删，历史交给 git） ## 起因 用户问"历史留痕？看看有没有过时的和无用的东西可以删除" —— **不该把"归档"当免检区**。逐项查证后：确认了 3 类该删的、1 类归错类的、1 个不能删的。 ## 一、删除：被"顺手 git add"误带进无关提交的产物 用 `git log --diff-filter=A` 追来历，发现它们**根本不是有意提交的**： | 文件 | 来历 | 判据 | |---|---|---| | `换电柜用锂电池充电器1TN标准通信协议 - RS485 V1.0(1).pdf` | `652bde4`（nginx 路由修复） | 与 `docs/hardware/1TN协议标准_苏州翌工电源_V1.0.pdf` **MD5 完全相同**（`B723A1FC…`）—— 纯重复 | | `package.json` + `package-lock.json` | `652bde4`（同上） | 唯一依赖 `html-docx-js`，**全仓无任何脚本引用**（当次把合同 md 转 docx 的一次性工具残留） | | `9b0d3b8a…jpg` / `d6e6add1…png` / `ea4410ba…jpg` | `8bc7812`（"23 个函数拆分"）/ `999885c`（协议对齐） | **零引用**，且混在与图片毫无关系的重构提交里 —— 误提交的截图 | ## 二、归错类（**不是过时，所以不删**）：`开发文档.md` → `hardware/硬件与系统设计文档.md` 原本被塞进 `archive/`，但通读目录后确认它含**硬件设计内容**，这些在 `AGENTS.md`/`docs/tech/` 里**没有**： 硬件架构、仓控/柜控主板设计、指示灯状态机、充电控制逻辑（握手/双模式/动态调整/无协议模式）、 BMS 协议适配、安全防护联动、性能指标、第三方服务配置。 ⇒ 它是**归错类而非过时**：**硬件部分仍是权威参考**，只有第 7 章（软件平台）被现行文档取代。 已在 `docs/README.md` 写明"两者冲突时软件口径以 `AGENTS.md` 为准"。 ## 三、删除：两份 2026-07-06 报告（**问题已全部解决**） 逐条核对了它们"发现的问题"，**无一条仍然成立**： | 报告 | 当时的问题 | 现状 | |---|---|---| | 深度分析报告 | 敏感信息泄露（AGENTS.md 明文密码） | 已成 `AGENTS.md` 的**明示豁免**条目 | | | 目录名不一致（可能用 taro，需确认） | 已确认 `h5-uniapp`，无 taro | | | `test/` 目录缺失 | `test/` 已存在且有 7 项验收脚本 | | | 温度单位不一致（K×100 vs 0.1°C） | 已统一为 K×100 | | 数据单位审查报告 | SOC/SOH 单位标注错误 | `API.md` 早已重写；该报告基准 `tcp-protocol.md` 已不存在 | ## 四、**不删**：`生产环境.txt`（并修掉自相矛盾的表述） 它是**唯一凭据清单**（阿里云账号/小程序 AppSecret/腾讯地图 key/SSL AccessKey 都在其中）， 且被 `docs/tech/小程序用户端.md` 明确引用为"密钥记录处"。 但原文写着"仅记录在内网 Git 仓库 `生产环境.txt`，**不入代码仓库**"—— **与事实矛盾** （`git ls-files` 实测它**已入库**）。已改为准确表述：只记录在该文件、**绝不写进任何源码/.env**、 **不要删除**（新凭据追加到那里，不要散落别处）。 > 🔐 **留给你的决定**：该文件含大量明文凭据。现策略与 `AGENTS.md`「明文密码」豁免一致（内网仓库）， > 若要收紧，建议把它加入 `.gitignore` 并另存到密码管理器 —— 但这会改变 agent 的直连方式，故未擅自改。 ## 五、取消 `archive/` 目录本身 **不再设归档**。理由：被删内容在 **git 历史里完整可查**（`git log -- <原路径>`）， 归档的"留痕"价值因此为零，却持续制造"这文件还算不算依据"的歧义。 已把该结论写进 `docs/README.md` 的维护约定：**过时就删；仍有价值的归到正确的类。** ## 六、其他归位 - `营业执照.jpg`（主体资质，小程序/备案用）→ `docs/contract/` - 根目录现在只剩 5 个必要文件：`.gitignore` / `AGENTS.md` / `README.md` / `opencode.json` / `生产环境.txt` ## 校验 - docs 相对链接 **0 断链**（搬迁引入的 2 处已在上一提交修好，本次复检通过）； - 已删除文件的残留引用：**仅剩 `docs/README.md` 的处置记录/映射表**（旧名必须出现，属预期）； - `cargo check --all-targets` 两服务零 error/warning（本次只动文档与仓库清理，未碰源码逻辑）。
2026-09-20 05:00:29 +08:00
> 💡 **为什么不设归档**：被删除的内容**在 git 历史里完整可查**（`git log -- <原路径>`），
> 归档目录的"留痕"价值因此为零，却会持续制造"这文件还算不算依据"的歧义。
> 结论：**过时就删，历史交给 git**；仍有价值的内容应当**归到正确的类**而不是塞进 archive/。
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
## 四、旧名 → 现名映射（查旧链接时用）
| 旧路径（已不存在） | 现路径 |
|---|---|
| `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/` |
chore: 清理过时与误提交产物；取消 archive/（过时就删，历史交给 git） ## 起因 用户问"历史留痕？看看有没有过时的和无用的东西可以删除" —— **不该把"归档"当免检区**。逐项查证后：确认了 3 类该删的、1 类归错类的、1 个不能删的。 ## 一、删除：被"顺手 git add"误带进无关提交的产物 用 `git log --diff-filter=A` 追来历，发现它们**根本不是有意提交的**： | 文件 | 来历 | 判据 | |---|---|---| | `换电柜用锂电池充电器1TN标准通信协议 - RS485 V1.0(1).pdf` | `652bde4`（nginx 路由修复） | 与 `docs/hardware/1TN协议标准_苏州翌工电源_V1.0.pdf` **MD5 完全相同**（`B723A1FC…`）—— 纯重复 | | `package.json` + `package-lock.json` | `652bde4`（同上） | 唯一依赖 `html-docx-js`，**全仓无任何脚本引用**（当次把合同 md 转 docx 的一次性工具残留） | | `9b0d3b8a…jpg` / `d6e6add1…png` / `ea4410ba…jpg` | `8bc7812`（"23 个函数拆分"）/ `999885c`（协议对齐） | **零引用**，且混在与图片毫无关系的重构提交里 —— 误提交的截图 | ## 二、归错类（**不是过时，所以不删**）：`开发文档.md` → `hardware/硬件与系统设计文档.md` 原本被塞进 `archive/`，但通读目录后确认它含**硬件设计内容**，这些在 `AGENTS.md`/`docs/tech/` 里**没有**： 硬件架构、仓控/柜控主板设计、指示灯状态机、充电控制逻辑（握手/双模式/动态调整/无协议模式）、 BMS 协议适配、安全防护联动、性能指标、第三方服务配置。 ⇒ 它是**归错类而非过时**：**硬件部分仍是权威参考**，只有第 7 章（软件平台）被现行文档取代。 已在 `docs/README.md` 写明"两者冲突时软件口径以 `AGENTS.md` 为准"。 ## 三、删除：两份 2026-07-06 报告（**问题已全部解决**） 逐条核对了它们"发现的问题"，**无一条仍然成立**： | 报告 | 当时的问题 | 现状 | |---|---|---| | 深度分析报告 | 敏感信息泄露（AGENTS.md 明文密码） | 已成 `AGENTS.md` 的**明示豁免**条目 | | | 目录名不一致（可能用 taro，需确认） | 已确认 `h5-uniapp`，无 taro | | | `test/` 目录缺失 | `test/` 已存在且有 7 项验收脚本 | | | 温度单位不一致（K×100 vs 0.1°C） | 已统一为 K×100 | | 数据单位审查报告 | SOC/SOH 单位标注错误 | `API.md` 早已重写；该报告基准 `tcp-protocol.md` 已不存在 | ## 四、**不删**：`生产环境.txt`（并修掉自相矛盾的表述） 它是**唯一凭据清单**（阿里云账号/小程序 AppSecret/腾讯地图 key/SSL AccessKey 都在其中）， 且被 `docs/tech/小程序用户端.md` 明确引用为"密钥记录处"。 但原文写着"仅记录在内网 Git 仓库 `生产环境.txt`，**不入代码仓库**"—— **与事实矛盾** （`git ls-files` 实测它**已入库**）。已改为准确表述：只记录在该文件、**绝不写进任何源码/.env**、 **不要删除**（新凭据追加到那里，不要散落别处）。 > 🔐 **留给你的决定**：该文件含大量明文凭据。现策略与 `AGENTS.md`「明文密码」豁免一致（内网仓库）， > 若要收紧，建议把它加入 `.gitignore` 并另存到密码管理器 —— 但这会改变 agent 的直连方式，故未擅自改。 ## 五、取消 `archive/` 目录本身 **不再设归档**。理由：被删内容在 **git 历史里完整可查**（`git log -- <原路径>`）， 归档的"留痕"价值因此为零，却持续制造"这文件还算不算依据"的歧义。 已把该结论写进 `docs/README.md` 的维护约定：**过时就删；仍有价值的归到正确的类。** ## 六、其他归位 - `营业执照.jpg`（主体资质，小程序/备案用）→ `docs/contract/` - 根目录现在只剩 5 个必要文件：`.gitignore` / `AGENTS.md` / `README.md` / `opencode.json` / `生产环境.txt` ## 校验 - docs 相对链接 **0 断链**（搬迁引入的 2 处已在上一提交修好，本次复检通过）； - 已删除文件的残留引用：**仅剩 `docs/README.md` 的处置记录/映射表**（旧名必须出现，属预期）； - `cargo check --all-targets` 两服务零 error/warning（本次只动文档与仓库清理，未碰源码逻辑）。
2026-09-20 05:00:29 +08:00
| `docs/开发文档.md` | `docs/hardware/硬件与系统设计文档.md`（**不是过时，是归错类**） |
| 根目录 `换电柜用锂电池充电器1TN标准通信协议 - RS485 V1.0(1).pdf` | `docs/hardware/1TN协议标准_苏州翌工电源_V1.0.pdf`（**同一文件，根目录那份是重复，已删**） |
| `docs/审查报告-数据单位一致性-2026-07-06.md` · `docs/项目深度分析报告-2026-07-06.md` | **已删除**（问题全部已解决；git 历史可查） |
| 其余合同/规格/验收/协议标准 | 见上表，分别归入 `contract/`、`hardware/` 与 `protocol/` |
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
## 五、维护约定（新增/移动文档时必做）
chore: 清理过时与误提交产物；取消 archive/（过时就删，历史交给 git） ## 起因 用户问"历史留痕？看看有没有过时的和无用的东西可以删除" —— **不该把"归档"当免检区**。逐项查证后：确认了 3 类该删的、1 类归错类的、1 个不能删的。 ## 一、删除：被"顺手 git add"误带进无关提交的产物 用 `git log --diff-filter=A` 追来历，发现它们**根本不是有意提交的**： | 文件 | 来历 | 判据 | |---|---|---| | `换电柜用锂电池充电器1TN标准通信协议 - RS485 V1.0(1).pdf` | `652bde4`（nginx 路由修复） | 与 `docs/hardware/1TN协议标准_苏州翌工电源_V1.0.pdf` **MD5 完全相同**（`B723A1FC…`）—— 纯重复 | | `package.json` + `package-lock.json` | `652bde4`（同上） | 唯一依赖 `html-docx-js`，**全仓无任何脚本引用**（当次把合同 md 转 docx 的一次性工具残留） | | `9b0d3b8a…jpg` / `d6e6add1…png` / `ea4410ba…jpg` | `8bc7812`（"23 个函数拆分"）/ `999885c`（协议对齐） | **零引用**，且混在与图片毫无关系的重构提交里 —— 误提交的截图 | ## 二、归错类（**不是过时，所以不删**）：`开发文档.md` → `hardware/硬件与系统设计文档.md` 原本被塞进 `archive/`，但通读目录后确认它含**硬件设计内容**，这些在 `AGENTS.md`/`docs/tech/` 里**没有**： 硬件架构、仓控/柜控主板设计、指示灯状态机、充电控制逻辑（握手/双模式/动态调整/无协议模式）、 BMS 协议适配、安全防护联动、性能指标、第三方服务配置。 ⇒ 它是**归错类而非过时**：**硬件部分仍是权威参考**，只有第 7 章（软件平台）被现行文档取代。 已在 `docs/README.md` 写明"两者冲突时软件口径以 `AGENTS.md` 为准"。 ## 三、删除：两份 2026-07-06 报告（**问题已全部解决**） 逐条核对了它们"发现的问题"，**无一条仍然成立**： | 报告 | 当时的问题 | 现状 | |---|---|---| | 深度分析报告 | 敏感信息泄露（AGENTS.md 明文密码） | 已成 `AGENTS.md` 的**明示豁免**条目 | | | 目录名不一致（可能用 taro，需确认） | 已确认 `h5-uniapp`，无 taro | | | `test/` 目录缺失 | `test/` 已存在且有 7 项验收脚本 | | | 温度单位不一致（K×100 vs 0.1°C） | 已统一为 K×100 | | 数据单位审查报告 | SOC/SOH 单位标注错误 | `API.md` 早已重写；该报告基准 `tcp-protocol.md` 已不存在 | ## 四、**不删**：`生产环境.txt`（并修掉自相矛盾的表述） 它是**唯一凭据清单**（阿里云账号/小程序 AppSecret/腾讯地图 key/SSL AccessKey 都在其中）， 且被 `docs/tech/小程序用户端.md` 明确引用为"密钥记录处"。 但原文写着"仅记录在内网 Git 仓库 `生产环境.txt`，**不入代码仓库**"—— **与事实矛盾** （`git ls-files` 实测它**已入库**）。已改为准确表述：只记录在该文件、**绝不写进任何源码/.env**、 **不要删除**（新凭据追加到那里，不要散落别处）。 > 🔐 **留给你的决定**：该文件含大量明文凭据。现策略与 `AGENTS.md`「明文密码」豁免一致（内网仓库）， > 若要收紧，建议把它加入 `.gitignore` 并另存到密码管理器 —— 但这会改变 agent 的直连方式，故未擅自改。 ## 五、取消 `archive/` 目录本身 **不再设归档**。理由：被删内容在 **git 历史里完整可查**（`git log -- <原路径>`）， 归档的"留痕"价值因此为零，却持续制造"这文件还算不算依据"的歧义。 已把该结论写进 `docs/README.md` 的维护约定：**过时就删；仍有价值的归到正确的类。** ## 六、其他归位 - `营业执照.jpg`（主体资质，小程序/备案用）→ `docs/contract/` - 根目录现在只剩 5 个必要文件：`.gitignore` / `AGENTS.md` / `README.md` / `opencode.json` / `生产环境.txt` ## 校验 - docs 相对链接 **0 断链**（搬迁引入的 2 处已在上一提交修好，本次复检通过）； - 已删除文件的残留引用：**仅剩 `docs/README.md` 的处置记录/映射表**（旧名必须出现，属预期）； - `cargo check --all-targets` 两服务零 error/warning（本次只动文档与仓库清理，未碰源码逻辑）。
2026-09-20 05:00:29 +08:00
1. **归位**：按"协议 / 技术 / 硬件 / 合同 / 经验"分类放入对应目录，**不要再平铺在 `docs/` 根**。
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
2. **更新本索引**：在对应章节的表格里加一行（文件 + 一句话定位 + 谁该读）。
3. **同步全仓引用**：文档路径散落在 `AGENTS.md`、`README.md`、**Rust/TS/Vue 源码注释**、
`test/`、`tools/`、`tasks/` 里；移动后必须全仓替换。
校验方法（**应无输出**）：
```bash
# 找仍指向旧平铺路径的活引用
# · 排除 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' . \
chore: 清理过时与误提交产物；取消 archive/（过时就删，历史交给 git） ## 起因 用户问"历史留痕？看看有没有过时的和无用的东西可以删除" —— **不该把"归档"当免检区**。逐项查证后：确认了 3 类该删的、1 类归错类的、1 个不能删的。 ## 一、删除：被"顺手 git add"误带进无关提交的产物 用 `git log --diff-filter=A` 追来历，发现它们**根本不是有意提交的**： | 文件 | 来历 | 判据 | |---|---|---| | `换电柜用锂电池充电器1TN标准通信协议 - RS485 V1.0(1).pdf` | `652bde4`（nginx 路由修复） | 与 `docs/hardware/1TN协议标准_苏州翌工电源_V1.0.pdf` **MD5 完全相同**（`B723A1FC…`）—— 纯重复 | | `package.json` + `package-lock.json` | `652bde4`（同上） | 唯一依赖 `html-docx-js`，**全仓无任何脚本引用**（当次把合同 md 转 docx 的一次性工具残留） | | `9b0d3b8a…jpg` / `d6e6add1…png` / `ea4410ba…jpg` | `8bc7812`（"23 个函数拆分"）/ `999885c`（协议对齐） | **零引用**，且混在与图片毫无关系的重构提交里 —— 误提交的截图 | ## 二、归错类（**不是过时，所以不删**）：`开发文档.md` → `hardware/硬件与系统设计文档.md` 原本被塞进 `archive/`，但通读目录后确认它含**硬件设计内容**，这些在 `AGENTS.md`/`docs/tech/` 里**没有**： 硬件架构、仓控/柜控主板设计、指示灯状态机、充电控制逻辑（握手/双模式/动态调整/无协议模式）、 BMS 协议适配、安全防护联动、性能指标、第三方服务配置。 ⇒ 它是**归错类而非过时**：**硬件部分仍是权威参考**，只有第 7 章（软件平台）被现行文档取代。 已在 `docs/README.md` 写明"两者冲突时软件口径以 `AGENTS.md` 为准"。 ## 三、删除：两份 2026-07-06 报告（**问题已全部解决**） 逐条核对了它们"发现的问题"，**无一条仍然成立**： | 报告 | 当时的问题 | 现状 | |---|---|---| | 深度分析报告 | 敏感信息泄露（AGENTS.md 明文密码） | 已成 `AGENTS.md` 的**明示豁免**条目 | | | 目录名不一致（可能用 taro，需确认） | 已确认 `h5-uniapp`，无 taro | | | `test/` 目录缺失 | `test/` 已存在且有 7 项验收脚本 | | | 温度单位不一致（K×100 vs 0.1°C） | 已统一为 K×100 | | 数据单位审查报告 | SOC/SOH 单位标注错误 | `API.md` 早已重写；该报告基准 `tcp-protocol.md` 已不存在 | ## 四、**不删**：`生产环境.txt`（并修掉自相矛盾的表述） 它是**唯一凭据清单**（阿里云账号/小程序 AppSecret/腾讯地图 key/SSL AccessKey 都在其中）， 且被 `docs/tech/小程序用户端.md` 明确引用为"密钥记录处"。 但原文写着"仅记录在内网 Git 仓库 `生产环境.txt`，**不入代码仓库**"—— **与事实矛盾** （`git ls-files` 实测它**已入库**）。已改为准确表述：只记录在该文件、**绝不写进任何源码/.env**、 **不要删除**（新凭据追加到那里，不要散落别处）。 > 🔐 **留给你的决定**：该文件含大量明文凭据。现策略与 `AGENTS.md`「明文密码」豁免一致（内网仓库）， > 若要收紧，建议把它加入 `.gitignore` 并另存到密码管理器 —— 但这会改变 agent 的直连方式，故未擅自改。 ## 五、取消 `archive/` 目录本身 **不再设归档**。理由：被删内容在 **git 历史里完整可查**（`git log -- <原路径>`）， 归档的"留痕"价值因此为零，却持续制造"这文件还算不算依据"的歧义。 已把该结论写进 `docs/README.md` 的维护约定：**过时就删；仍有价值的归到正确的类。** ## 六、其他归位 - `营业执照.jpg`（主体资质，小程序/备案用）→ `docs/contract/` - 根目录现在只剩 5 个必要文件：`.gitignore` / `AGENTS.md` / `README.md` / `opencode.json` / `生产环境.txt` ## 校验 - docs 相对链接 **0 断链**（搬迁引入的 2 处已在上一提交修好，本次复检通过）； - 已删除文件的残留引用：**仅剩 `docs/README.md` 的处置记录/映射表**（旧名必须出现，属预期）； - `cargo check --all-targets` 两服务零 error/warning（本次只动文档与仓库清理，未碰源码逻辑）。
2026-09-20 05:00:29 +08:00
| grep -v '^\./docs/README\.md:'
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
```
> 已实测该命令**能抓到问题**：往 `docs/tech/API.md` 末尾植入一行
> `<!-- probe: docs/API.md -->` → 命中；删除后 → 无输出。
> ⚠️ 注意这些 `.md` 多为 **CRLF** —— 用脚本批量删除/替换时**必须按 `\r?\n` 处理**，
> 否则会漏改（我第一次就踩了：`\n` 正则配不上 `\r\n`，以为删干净了其实残留）。
4. **改 `AGENTS.md` 的链接**：`AGENTS.md` 里所有 `docs/...` 链接都必须是**分类后**的路径
（`docs/protocol/...`、`docs/tech/...`）。
chore: 清理过时与误提交产物；取消 archive/（过时就删，历史交给 git） ## 起因 用户问"历史留痕？看看有没有过时的和无用的东西可以删除" —— **不该把"归档"当免检区**。逐项查证后：确认了 3 类该删的、1 类归错类的、1 个不能删的。 ## 一、删除：被"顺手 git add"误带进无关提交的产物 用 `git log --diff-filter=A` 追来历，发现它们**根本不是有意提交的**： | 文件 | 来历 | 判据 | |---|---|---| | `换电柜用锂电池充电器1TN标准通信协议 - RS485 V1.0(1).pdf` | `652bde4`（nginx 路由修复） | 与 `docs/hardware/1TN协议标准_苏州翌工电源_V1.0.pdf` **MD5 完全相同**（`B723A1FC…`）—— 纯重复 | | `package.json` + `package-lock.json` | `652bde4`（同上） | 唯一依赖 `html-docx-js`，**全仓无任何脚本引用**（当次把合同 md 转 docx 的一次性工具残留） | | `9b0d3b8a…jpg` / `d6e6add1…png` / `ea4410ba…jpg` | `8bc7812`（"23 个函数拆分"）/ `999885c`（协议对齐） | **零引用**，且混在与图片毫无关系的重构提交里 —— 误提交的截图 | ## 二、归错类（**不是过时，所以不删**）：`开发文档.md` → `hardware/硬件与系统设计文档.md` 原本被塞进 `archive/`，但通读目录后确认它含**硬件设计内容**，这些在 `AGENTS.md`/`docs/tech/` 里**没有**： 硬件架构、仓控/柜控主板设计、指示灯状态机、充电控制逻辑（握手/双模式/动态调整/无协议模式）、 BMS 协议适配、安全防护联动、性能指标、第三方服务配置。 ⇒ 它是**归错类而非过时**：**硬件部分仍是权威参考**，只有第 7 章（软件平台）被现行文档取代。 已在 `docs/README.md` 写明"两者冲突时软件口径以 `AGENTS.md` 为准"。 ## 三、删除：两份 2026-07-06 报告（**问题已全部解决**） 逐条核对了它们"发现的问题"，**无一条仍然成立**： | 报告 | 当时的问题 | 现状 | |---|---|---| | 深度分析报告 | 敏感信息泄露（AGENTS.md 明文密码） | 已成 `AGENTS.md` 的**明示豁免**条目 | | | 目录名不一致（可能用 taro，需确认） | 已确认 `h5-uniapp`，无 taro | | | `test/` 目录缺失 | `test/` 已存在且有 7 项验收脚本 | | | 温度单位不一致（K×100 vs 0.1°C） | 已统一为 K×100 | | 数据单位审查报告 | SOC/SOH 单位标注错误 | `API.md` 早已重写；该报告基准 `tcp-protocol.md` 已不存在 | ## 四、**不删**：`生产环境.txt`（并修掉自相矛盾的表述） 它是**唯一凭据清单**（阿里云账号/小程序 AppSecret/腾讯地图 key/SSL AccessKey 都在其中）， 且被 `docs/tech/小程序用户端.md` 明确引用为"密钥记录处"。 但原文写着"仅记录在内网 Git 仓库 `生产环境.txt`，**不入代码仓库**"—— **与事实矛盾** （`git ls-files` 实测它**已入库**）。已改为准确表述：只记录在该文件、**绝不写进任何源码/.env**、 **不要删除**（新凭据追加到那里，不要散落别处）。 > 🔐 **留给你的决定**：该文件含大量明文凭据。现策略与 `AGENTS.md`「明文密码」豁免一致（内网仓库）， > 若要收紧，建议把它加入 `.gitignore` 并另存到密码管理器 —— 但这会改变 agent 的直连方式，故未擅自改。 ## 五、取消 `archive/` 目录本身 **不再设归档**。理由：被删内容在 **git 历史里完整可查**（`git log -- <原路径>`）， 归档的"留痕"价值因此为零，却持续制造"这文件还算不算依据"的歧义。 已把该结论写进 `docs/README.md` 的维护约定：**过时就删；仍有价值的归到正确的类。** ## 六、其他归位 - `营业执照.jpg`（主体资质，小程序/备案用）→ `docs/contract/` - 根目录现在只剩 5 个必要文件：`.gitignore` / `AGENTS.md` / `README.md` / `opencode.json` / `生产环境.txt` ## 校验 - docs 相对链接 **0 断链**（搬迁引入的 2 处已在上一提交修好，本次复检通过）； - 已删除文件的残留引用：**仅剩 `docs/README.md` 的处置记录/映射表**（旧名必须出现，属预期）； - `cargo check --all-targets` 两服务零 error/warning（本次只动文档与仓库清理，未碰源码逻辑）。
2026-09-20 05:00:29 +08:00
5. **过时就删，不要设归档**：被删内容在 git 历史里完整可查，归档只会制造
"这文件还算不算依据"的歧义。仍有价值的**归到正确的类**，规范要写进 `AGENTS.md` 或 `tech/`。
Reference in New Issue Copy Permalink