108 lines
6.9 KiB
Markdown
108 lines
6.9 KiB
Markdown
|
# docs/ 文档地图
|
|||
|
|
|
|||
|
|
> **本文件是 `docs/` 的分类索引。** 新增、移动或改名任何文档后，**必须回来更新本文件**
|
|||
|
|
> 并同步全仓引用（见文末「维护约定」）。
|
|||
|
|
|
|||
|
|
## 一、分类总览
|
|||
|
|
|
|||
|
|
| 目录 | 定位 | 权威性 | 谁该读 |
|
|||
|
|
|------|------|--------|--------|
|
|||
|
|
| [`protocol/`](#protocol设备协议) | **设备协议**（冻结，对硬件工程师交付） | ⭐ **唯一权威** | 硬件工程师、固件、平台 TCP 相关开发 |
|
|||
|
|
| [`tech/`](#tech平台技术文档) | **平台技术文档**（开发/运维必读） | ⭐ 权威（各自领域内） | 后端/前端/运维 |
|
|||
|
|
| [`contract/`](#contract合同与规格) | **合同、规格、验收标准**（商务依据） | 事实依据，但不描述实现 | PM、验收方、新人了解范围 |
|
|||
|
|
| [`compound-notes/`](#compound-notes经验沉淀) | **单点经验笔记**（踩坑/技法） | 参考，非权威 | 遇到同类问题的人 |
|
|||
|
|
| [`archive/`](#archive历史归档) | **历史留痕**（只读，**不代表现状**） | ⛔ **不可作为依据** | 追溯历史决策时 |
|
|||
|
|
|
|||
|
|
## 二、谁是权威（口径优先级，避免"两份文档谁对"的扯皮）
|
|||
|
|
|
|||
|
|
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）。**既是内部文档也可直接对外交付。** |
|
|||
|
|
| `1TN协议标准_YG20240118-1_V1.0.md` | 仓控板 ↔ 电源（苏州翌工）1TN RS485 协议文本版 |
|
|||
|
|
| `1TN协议标准_苏州翌工电源_V1.0.pdf` | 同上，厂家原始 PDF |
|
|||
|
|
|
|||
|
|
### tech/ —— 平台技术文档
|
|||
|
|
|
|||
|
|
| 文件 | 说明 | 入口 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| `API.md` | HTTP 接口清单与响应结构 + **数据单位规范**（整数存储，禁浮点） | PC/小程序前端、后端 |
|
|||
|
|
| `数据模型.md` | 21 张表的逐列语义、外键/唯一键、建表依赖顺序 | **改表结构前必读** |
|
|||
|
|
| `部署手册.md` | 完整部署步骤、nginx 两份 conf.d 全文、**全部 11 条部署注意事项** | 运维、发版 |
|
|||
|
|
| `小程序用户端.md` | 小程序页面清单、逐页职责、状态位分层展示、RSSI 分档口径 | 小程序开发 |
|
|||
|
|
|
|||
|
|
> 这四份是 `AGENTS.md` 的**详细参考篇**：`AGENTS.md` 只保留"判据 + 链接"
|
|||
|
|
> （因为 `AGENTS.md` 超出工作区指令预算 65,536 B 时会被**按头部截断**，尾部根本不加载）。
|
|||
|
|
|
|||
|
|
### contract/ —— 合同与规格
|
|||
|
|
|
|||
|
|
`开发合同` / `附件一-硬件规格` / `附件二-软件规格` / `附件三-交付与验收标准` /
|
|||
|
|
`附件-开发需求规格说明书`，各含 `.md` + 原始格式（`.docx` / `.pdf` / `.html`）双份。
|
|||
|
|
|
|||
|
|
> 用途：**范围与验收的事实依据**。描述"要做什么 / 达到什么标准"，**不描述当前实现**
|
|||
|
|
> ——实现现状一律以 `AGENTS.md` + 代码为准。
|
|||
|
|
|
|||
|
|
### compound-notes/ —— 经验沉淀
|
|||
|
|
|
|||
|
|
单点问题的笔记（如某次 SQL 注入的成因与修法）。**参考性**内容，
|
|||
|
|
遇到同类问题时查；结论若上升为通用规范，应回写进 `AGENTS.md` 的「踩过的坑」。
|
|||
|
|
|
|||
|
|
### archive/ —— 历史归档
|
|||
|
|
|
|||
|
|
| 文件 | 说明 |
|
|||
|
|
|------|------|
|
|||
|
|
| `开发文档.md` | 早期（现行实现之前）的开发文档，**与当前实现多处不一致** |
|
|||
|
|
| `审查报告-数据单位一致性-2026-07-06.md` | 2026-07-06 的数据单位审查报告 |
|
|||
|
|
| `项目深度分析报告-2026-07-06.md` | 2026-07-06 的项目深度分析报告 |
|
|||
|
|
|
|||
|
|
⛔ **归档目录只读、不作依据**——里面的路径、结论、数字都是**当时**的。
|
|||
|
|
其中出现的旧文档名（如 `tcp-protocol.md`、`docs/柜控板-平台TCP接口文档.md`）
|
|||
|
|
是历史事实，**不要求可点击**；对应关系到当前文档的映射见下节。
|
|||
|
|
|
|||
|
|
## 四、旧名 → 现名映射（查旧链接时用）
|
|||
|
|
|
|||
|
|
| 旧路径（已不存在） | 现路径 |
|
|||
|
|
|---|---|
|
|||
|
|
| `docs/tcp-protocol.md` | `docs/protocol/柜控板固件对接文档.md` |
|
|||
|
|
| `docs/柜控板-平台TCP接口文档.md` | 已于协议 v1.1 删除（内部重复文档，内容并入上者） |
|
|||
|
|
| `docs/柜控板固件对接文档.md` | `docs/protocol/柜控板固件对接文档.md` |
|
|||
|
|
| `docs/API.md` | `docs/tech/API.md` |
|
|||
|
|
| `docs/数据模型.md` · `docs/部署手册.md` · `docs/小程序用户端.md` | 同名，移到 `docs/tech/` |
|
|||
|
|
| `docs/开发文档.md` | `docs/archive/开发文档.md` |
|
|||
|
|
| 其余合同/规格/验收/协议标准 | 见上表，分别归入 `contract/` 与 `protocol/` |
|
|||
|
|
|
|||
|
|
## 五、维护约定（新增/移动文档时必做）
|
|||
|
|
|
|||
|
|
1. **归位**：按"协议 / 技术 / 合同 / 经验 / 归档"分类放入对应目录，**不要再平铺在 `docs/` 根**。
|
|||
|
|
2. **更新本索引**：在对应章节的表格里加一行（文件 + 一句话定位 + 谁该读）。
|
|||
|
|
3. **同步全仓引用**：文档路径散落在 `AGENTS.md`、`README.md`、**Rust/TS/Vue 源码注释**、
|
|||
|
|
`test/`、`tools/`、`tasks/` 里；移动后必须全仓替换。
|
|||
|
|
校验方法（**应无输出**）：
|
|||
|
|
```bash
|
|||
|
|
# 找仍指向旧平铺路径的活引用
|
|||
|
|
# · 排除 docs/archive/ —— 归档按设计保留历史原文
|
|||
|
|
# · 排除 docs/README.md —— 本文件的「旧名 → 现名映射」表**必须**出现旧名
|
|||
|
|
grep -rn --exclude-dir={.git,node_modules,target,dist} \
|
|||
|
|
-e 'docs/API\.md' -e 'docs/数据模型\.md' -e 'docs/部署手册\.md' \
|
|||
|
|
-e 'docs/小程序用户端\.md' -e 'docs/开发文档\.md' . \
|
|||
|
|
| grep -v '^\./docs/archive/' | grep -v '^\./docs/README\.md:'
|
|||
|
|
```
|
|||
|
|
> 已实测该命令**能抓到问题**：往 `docs/tech/API.md` 末尾植入一行
|
|||
|
|
> `<!-- probe: docs/API.md -->` → 命中；删除后 → 无输出。
|
|||
|
|
> ⚠️ 注意这些 `.md` 多为 **CRLF** —— 用脚本批量删除/替换时**必须按 `\r?\n` 处理**，
|
|||
|
|
> 否则会漏改（我第一次就踩了：`\n` 正则配不上 `\r\n`，以为删干净了其实残留）。
|
|||
|
|
4. **改 `AGENTS.md` 的链接**：`AGENTS.md` 里所有 `docs/...` 链接都必须是**分类后**的路径
|
|||
|
|
（`docs/protocol/...`、`docs/tech/...`）。
|
|||
|
|
5. **别把权威内容只放进归档**：归档是留痕，规范要写进 `AGENTS.md` 或 `tech/`。
|