401f84bda6
## 起因
用户问"现在确定所有文档都是按分类存放没重复和过期内容了吧" ——
**不能凭感觉答"是"**，于是做了一次针对**已跟踪文件**的体检（重复/断链/过期陈述三维度）。
第一轮体检结果：重复 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、不入库。
146 lines
10 KiB
Markdown
146 lines
10 KiB
Markdown
# docs/ 文档地图
|
||
|
||
> **本文件是 `docs/` 的分类索引。** 新增、移动或改名任何文档后，**必须回来更新本文件**
|
||
> 并同步全仓引用（见文末「维护约定」）。
|
||
|
||
## 一、分类总览
|
||
|
||
| 目录 | 定位 | 权威性 | 谁该读 |
|
||
|------|------|--------|--------|
|
||
| [`protocol/`](#protocol设备协议) | **平台设备协议**（TCP，冻结，对硬件工程师交付） | ⭐ **唯一权威** | 硬件工程师、固件、平台 TCP 相关开发 |
|
||
| [`tech/`](#tech平台技术文档) | **平台技术文档**（开发/运维必读） | ⭐ 权威（各自领域内） | 后端/前端/运维 |
|
||
| [`hardware/`](#hardware硬件侧总线协议) | **硬件侧总线协议**（RS485，**不是**平台 TCP 协议） | 硬件事实依据 | 硬件工程师、对接电源/BMS 的人 |
|
||
| [`contract/`](#contract合同与规格) | **合同、规格、验收标准**（商务依据） | 事实依据，但不描述实现 | PM、验收方、新人了解范围 |
|
||
| [`compound-notes/`](#compound-notes经验沉淀) | **单点经验笔记**（踩坑/技法） | 参考，非权威 | 遇到同类问题的人 |
|
||
|
||
## 二、谁是权威（口径优先级，避免"两份文档谁对"的扯皮）
|
||
|
||
> ### ⚠️ 关于"到底有几份 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协议"
|
||
> 但那是任务记录，不是规格。
|
||
|
||
1. **`protocol/柜控板固件对接文档.md`** —— 设备协议（帧格式 / `act` / 字段名 / 签名 / `id` 规则）
|
||
的**唯一权威**。协议**冻结**，设备端固件不可改。
|
||
2. **根目录 `AGENTS.md`** —— **平台侧实现口径**的权威：Redis 键与字段、接口行为、库结构、
|
||
验收流程、部署注意事项。与 `tech/API.md` 的平台存储/行为描述冲突时，**以 `AGENTS.md` 为准**
|
||
（它的每一条都按代码契约与库实测核对过）。
|
||
3. **`tech/API.md`** —— **HTTP 接口清单与响应结构**的权威（含数据单位规范）。
|
||
4. **代码与文档冲突时**：先确认是不是代码错；确认代码对就**改文档**并在报告里点出。
|
||
|
||
## 三、逐目录说明
|
||
|
||
### protocol/ —— 平台设备协议（**只有一份**）
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `柜控板固件对接文档.md` | **唯一权威 TCP 文档**（v1.1.1）。帧格式、通用规则（`act`/`suc`/`msg_id`/60 秒超时/登录门控）、指令清单、签名算法与自测向量、安全码自愈、带注释报文示例（附 A）、变更记录（附 B）。**既是内部文档也可直接对外交付。** |
|
||
|
||
⛔ **不要在这里放第二份协议文档**（哪怕是"内部稿""示例集""补充说明"）——
|
||
历史上正是这样分叉出三份，最后对不上。要补充内容就**改这一份并升版本号**（记入它的「附 B」）。
|
||
|
||
### hardware/ —— 硬件侧总线协议
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `1TN协议标准_YG20240118-1_V1.0.md` | 仓控板 ↔ 电源（苏州翌工）1TN RS485 协议，文本版 |
|
||
| `1TN协议标准_苏州翌工电源_V1.0.pdf` | 同上，厂家原始 PDF |
|
||
| `硬件与系统设计文档.md` | **硬件与系统设计原文**（46 KB）：硬件架构、仓控/柜控主板设计、指示灯状态机、充电控制逻辑（握手/双模式/动态调整/无协议模式）、BMS 协议适配、安全防护联动、性能指标、第三方服务配置。**硬件侧的主规格文档。** |
|
||
|
||
> ⚠️ `1TN协议标准_*` 是**另一条物理链路**（柜内 485 总线），**与平台 TCP 协议无关** ——
|
||
> 别把它当成"第二份 TCP 协议"。硬件侧的其它总线协议（BMS：星恒 Modbus / 天能 485）如需入库，也放这里。
|
||
>
|
||
> ⚠️ `硬件与系统设计文档.md` **早于现行实现**：其中**硬件设计部分仍是权威参考**，
|
||
> 但**软件平台部分（第 7 章）已被 `AGENTS.md` + `docs/tech/` 取代** ——
|
||
> 两者冲突时，软件口径一律以 `AGENTS.md` 为准（它按代码契约与库实测核对过）。
|
||
|
||
### 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`）双份。
|
||
|
||
> 另有 `营业执照.jpg`（主体资质，小程序/备案用）。
|
||
>
|
||
> 用途：**范围与验收的事实依据**。描述"要做什么 / 达到什么标准"，**不描述当前实现**
|
||
> ——实现现状一律以 `AGENTS.md` + 代码为准。
|
||
|
||
### compound-notes/ —— 经验沉淀
|
||
|
||
单点问题的笔记：`2026-08-15-sql-injection-format-param-binding.md`（SQL 注入成因与修法）、
|
||
`2026-07-ardot-batch-edit-属性写法.md`（设计稿批量编辑的属性坑）、
|
||
`TEMPLATE.md`（新建笔记的模板）。**参考性**内容，
|
||
遇到同类问题时查；结论若上升为通用规范，应回写进 `AGENTS.md` 的「踩过的坑」。
|
||
|
||
### ~~archive/~~ —— 已取消（2026-09-20）
|
||
|
||
**不再设归档目录。** 曾经的 `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/` 已存在、温度单位已统一。 |
|
||
|
||
> 💡 **为什么不设归档**：被删除的内容**在 git 历史里完整可查**（`git log -- <原路径>`），
|
||
> 归档目录的"留痕"价值因此为零，却会持续制造"这文件还算不算依据"的歧义。
|
||
> 结论：**过时就删，历史交给 git**；仍有价值的内容应当**归到正确的类**而不是塞进 archive/。
|
||
|
||
## 四、旧名 → 现名映射（查旧链接时用）
|
||
|
||
| 旧路径（已不存在） | 现路径 |
|
||
|---|---|
|
||
| `docs/tcp-protocol.md` | `docs/protocol/柜控板固件对接文档.md` |
|
||
| `docs/柜控板-平台TCP接口文档.md` | 已于协议 v1.1 删除（内部重复文档，内容并入上者） |
|
||
| `docs/柜控板固件对接文档.md` | `docs/protocol/柜控板固件对接文档.md` |
|
||
| `docs/API.md` | `docs/tech/API.md` |
|
||
| `docs/数据模型.md` · `docs/部署手册.md` · `docs/小程序用户端.md` | 同名，移到 `docs/tech/` |
|
||
| `docs/开发文档.md` | `docs/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/` |
|
||
|
||
## 五、维护约定（新增/移动文档时必做）
|
||
|
||
1. **归位**：按"协议 / 技术 / 硬件 / 合同 / 经验"分类放入对应目录，**不要再平铺在 `docs/` 根**。
|
||
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' . \
|
||
| grep -v '^\./docs/README\.md:'
|
||
```
|
||
> 已实测该命令**能抓到问题**：往 `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/...`）。
|
||
5. **过时就删，不要设归档**：被删内容在 git 历史里完整可查，归档只会制造
|
||
"这文件还算不算依据"的歧义。仍有价值的**归到正确的类**，规范要写进 `AGENTS.md` 或 `tech/`。
|