admin/charging-cabinet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
78 Commits 1 Branch 0 Tags
Commit Graph

4 Commits

Author SHA1 Message Date
12451
401f84bda6 chore: 清掉误入库的 agent 工具记忆目录与 Vite 模板 README（内容先按主题归位） 
## 起因

用户问"现在确定所有文档都是按分类存放没重复和过期内容了吧" ——
**不能凭感觉答"是"**，于是做了一次针对**已跟踪文件**的体检（重复/断链/过期陈述三维度）。
第一轮体检结果：重复 0 组、断链 0 处，但**又扫出 3 处该处理的东西**。

## 一、`.workbuddy/memory/` —— 另一个 agent 工具的记忆目录被误入库

3 个文件（`MEMORY.md` / `2026-07-02.md` / `2026-07-07.md`），**全仓零引用**，
最后一次"提交"是搭车进 `feat(protocol): TCP v1.1 协议对齐` 这类无关提交 ——
与之前那几张误提交的图片同一模式。

- ⚠️ `2026-07-02.md` 里含一处**生图 API Key 片段**（`sk-ib7i...M2z`）；
- `.gitignore` 里 `.codebuddy/` 早有，但 `.workbuddy/` **漏了** ⇒ 才被顺手提交进来。

### 处理：内容先归位，再删目录（不是一删了之）

按 `docs/README.md` 已确立的原则"**过时就删；仍有价值的归到正确的类**"，
把 `MEMORY.md` 里仍有价值的三类内容分别落位：

| 内容 | 归到哪 | 为什么 |
|---|---|---|
| UI 颜色系统 / 背景容器 / 36 仓通道卡布局 | **`docs/tech/小程序用户端.md`** 新增「附：UI 设计规范（视觉口径，改动界面前必读）」 | 这是页面视觉口径，属小程序文档 |
| Ardot `batch_edit` 的 `fills`/`strokes`/`cornerRadius` 写法坑 + 设计稿 7 屏 ID | **`docs/compound-notes/2026-07-ardot-batch-edit-属性写法.md`** | 工具特有的单点教训，正是 compound-notes 的定义 |
| "开发前必须确认需求"、"生产环境须授权"、落地页明亮风格偏好 | **`AGENTS.md` 新增「操作规则」小节** | 项目级规则，须常驻加载 |

然后把 `.workbuddy/` 从版本控制移除并**加入 `.gitignore`**（连同 `.opencode/`、`.codegraph/`），
堵住同一个坑再犯。

## 二、`software/web/README.md` —— 建站模板残留

23 行里 9 行是 Vite/plugin-react/Oxlint 的模板话术（英文、与项目无关）。
`api-server` / `device-server` / `h5-uniapp` 三个工程**都没有** README —— 构建方式统一在
`AGENTS.md` 与 `docs/tech/部署手册.md` 里。⇒ **删除**。

## 三、一个我自己的误判（已纠正，记录以免后人重复）

我一度怀疑 `docs/tech/API.md` 接口表"少 12 行"（我数出 68 行，而 `mod.rs` 有 80 个 `.route(`）。
复核发现 **`API.md` 自己写明了计数约定**："一行 = 一次 `.route(...)` 注册，共 80 行；
展开后 93 对" —— 而我的正则 `^\|\s*(GET|POST)\s*\|` **漏掉了 `| GET / POST |` 这种链式写法**。
用能匹配链式的正则重数 = **正好 80** ⇒ **`API.md` 是准确的，我的怀疑是错的**。

## 校验（只扫 git 已跟踪文件）

- 已跟踪文件 **217**（原 221 → 删 3 个工具记忆 + 1 个模板 README）；
- 文档内容重复：**0 组**；
- 已跟踪 md 的本地链接：**0 断链**；
- `.workbuddy` 已跟踪文件数 = 0、工作区已不存在。

## 仍**刻意保留**的（不是遗漏）

- `生产环境.txt`：**唯一凭据清单**且被 `docs/tech/小程序用户端.md` 引用为密钥记录处 ——
  上一提交已把"不入代码仓库"这句与事实矛盾的表述改准；是否改走 `.gitignore`+密码管理器由你定。
- `docs/README.md` 的「旧名→现名映射」表 / 处置记录 / 自证方法：**必须**出现旧名，属预期。
- `docs/compound-notes/TEMPLATE.md`（94 B）：新建笔记的模板，给该目录提供格式约束。
- `tasks/002-未结待办-*.md`：两项未结（`energy` 等硬件答复、长函数重构），
  `tasks/` 本身已 gitignore、不入库。
 2026-09-20 05:04:53 +08:00
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（本次只动文档与仓库清理，未碰源码逻辑）。
 2026-09-20 05:00:29 +08:00
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/` 一行。
 2026-09-20 04:55:28 +08:00
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