2 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
12451
|
a03c163c1d |
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（本次只动文档与仓库清理，未碰源码逻辑）。
|
||
|
12451
|
7d2b57d021 |
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/` 一行。 |