12451
|
8eb2b7c68c
|
docs(protocol): hex 字面量字母全部大写（含 7 处"建议小写"的规范表述订正）
## 用户要求
「tcp 文档里的 hex 部分字母全部要大写」。
## 改法（⛔ 不是全局替换 a-f → A-F）
全局替换会误伤英文正文（face / define 里都有 a-f）。先普查再定向改，
只处理**明确是 hex 字面量**的三种形态，且仅当确实含小写时才改写：
| 形态 | 改前普查 | 改写处数 |
|---|---|---|
| JSON 字符串 hex `"828255152c01f40143"` | 95 处 / 16 种，含小写 6 种 | 24 |
| 反引号 hex `` `3957b959` `` | 47 处 / 30 种，含小写 7 种 | 11 |
| `0x` 前缀 | 21 处 / 9 种，**已全大写** | 0 |
共 **35 处**。危险面（2 位字母数字，可能误伤正文）普查为 **0**；
`864720562557021`(IMEI) / `8986012520983901841`(ICCID) 纯数字，不受影响。
## 大小写安全性（改前已核实）
平台侧解析全部走 `u8::from_str_radix(s, 16)`，**大小写不敏感**：
- `report_worker.rs:838/860/1152/1270/2401`
- `routes/mod.rs:637`、`routes/cabinet_tree.rs:1086`
故文档改大写**不影响设备上报与平台解析**。
## 验证：逐行证明"只是大小写"
git diff 共 28 行改动（订正规范表述前），剥掉行首 +/- 后与原行
**逐行做大写比对，非大小写差异行数 = 0** —— 证明没有误伤任何内容。
## ⚠️ 机械替换破坏了一处对照性表述（已修）
原 L584 是**故意的大小写对照**：
> 平台解析**不区分大小写**（`0e10` 与 `0E10` 等价）；**建议固件统一小写**
被机械替换后两边都成 `0E10`，对照失效。已改为：
> 平台解析**不区分大小写**（`0e10` 与 `0E10` 等价，本文示例统一用**大写**）；**建议固件也统一用大写**
并复查全文档：无其它同类被破坏的对照。
## 顺带订正 7 处矛盾规范
文档里还有 7 处**规范性表述仍写"小写"**，与现在的全大写示例直接矛盾
（这是交付给固件的指令，不能留矛盾）：
| 位置 | 原文 |
|---|---|
| `sign` 字段表 | 8 位小写十六进制签名 |
| 签名算法伪码 | hex = 小写十六进制字符串（64 字符） |
| 签名要求 | `sign` 为 8 位小写十六进制字符 |
| 固件接入自查项 | `status1`/`status2`（hex 2 位小写） |
| 常见错误表 | hex 字符串、固定 2 位小写 |
| 签名步骤 | 8 位小写十六进制 |
| C 代码注释 | SHA256(...) 的小写 hex |
统一改为"十六进制（本文示例用**大写**）"。`snake_case`、`err` 英文小写
与 hex 无关，未动。
## 复核
- 残留含小写的 hex 字面量：**1 处**，即上面故意保留的 `0e10` 对照示例；
- 全部目标值已到位（`828255152C01F40143` 8 处、`80825515180320012A` 3 处、
`80005F15180000012A` 3 处、`81026415540000012A` 5 处、`269C249D` 7 处、
`3957B959` 4 处、`012A0128` 2 处、`ABCD1234` 1 处）。
## 同批发布
官网移动端 canvas 防黑边兜底（`.stage canvas` 铺浅色背景）已发布并实测生效
（线上 HTML 含 `linear-gradient(155deg`）。GSAP 技能按用户要求**不装**；
表号按用户要求**不管**。
|
2026-09-21 13:41:17 +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 |
|