255 lines
16 KiB
Markdown
255 lines
16 KiB
Markdown
# 实现与文档的偏差
|
||
|
||
开发中凡是实现和 [PRD.md](./PRD.md)、[DEVELOPMENT.md](./DEVELOPMENT.md) 不一致的地方，以及文档没写清、开发中自己拿主意的地方，都记在这里，交给负责人事后审阅。开发全程自动推进，记下来就继续，不等审阅。
|
||
|
||
每条写清：日期、原条款（文档和小节）、实际做法、原因、备选方案、影响。各线只写自己那一节，避免多条线同时改同一段。
|
||
|
||
## 总控 L
|
||
|
||
### T0.1 2026-09-30
|
||
|
||
1. **前端嵌入方式**
|
||
- 原条款：DEVELOPMENT 第 3 节 `web/embed.go` 用 `//go:embed all:dist`；TASKS T0.1；`.gitignore` 忽略 `web/dist`。
|
||
- 实际做法：默认构建用 `-tags` 以外的 `embed_stub.go` 嵌入 `web/stub/`；`task build` 加 `-tags embeddist` 嵌入真实 `web/dist`。
|
||
- 原因：`web/dist` 不进仓库，且要求没有前端产物时也能 `go build`。
|
||
- 备选方案：提交最小 `dist`；或构建前脚本生成占位目录。
|
||
- 影响：裸 `go build` 不含真实前端；正式产物必须走 `task build`。
|
||
|
||
2. **listen.addr 写入时机**
|
||
- 原条款：DEVELOPMENT 4.1「端口写 0 时」写 `<data_dir>/listen.addr`。
|
||
- 实际做法：只要 `serve` 启动成功就写入实际监听地址。
|
||
- 原因：测试启动器统一读取该文件更简单，固定端口场景也无害。
|
||
- 备选方案：仅当配置端口为 0 时写入。
|
||
- 影响：多一个小文件；行为超集，兼容文档要求。
|
||
|
||
3. **迁移占位**
|
||
- 原条款：T0.3 才写完整表与 `VACUUM INTO` 备份；T0.1 允许空执行器加空 0001。
|
||
- 实际做法：`internal/store.Migrate` 建 `schema_migrations` 并应用 `0001_init.sql`（内容为 `SELECT 1;`）；不做迁移前备份。
|
||
- 原因：保证 serve 可跑通迁移路径，表结构留给 T0.3。
|
||
- 备选方案：完全空文件 + 只记版本。
|
||
- 影响：T0.3 需替换 0001 正文并补备份逻辑；已应用的占位版本号仍为 1。
|
||
|
||
4. **Taskfile 引入 taskfiles**
|
||
- 原条款：TASKS T0.1 / 4.2 引入 `taskfiles/*.yml`。
|
||
- 实际做法：`includes: '*': taskfile: taskfiles/*.yml, optional: true`，并放 `_init.yml` 占位。
|
||
- 原因：空目录 glob 可能失败；各线稍后加自己的 yml。
|
||
- 备选方案：主文件逐条 optional include 各线文件名。
|
||
- 影响：无。
|
||
|
||
5. **deploy/Dockerfile**
|
||
- 原条款：完整多架构镜像属 Q4；T0.1 需要 `task docker` 目标。
|
||
- 实际做法：提供单架构多阶段 Dockerfile 骨架，供 `task docker` 使用；T0.1 验证另用官方 `golang` 镜像跑 `task check`。
|
||
- 原因：让 docker 目标可执行，又不抢 Q4 范围。
|
||
- 备选方案：docker 目标仅 echo 提示。
|
||
- 影响：镜像发布流程仍由 Q4 定稿。
|
||
|
||
### T0.2 2026-09-30
|
||
|
||
1. **请求指纹规范化格式**
|
||
- 原条款：DEVELOPMENT 7.3「下列字段规范化后的 SHA-256」，未规定字节布局。
|
||
- 实际做法：对 `to.kind`、`to.id`、`body.enc`、有效 `content_type`、解码后正文、`meta` 规范 JSON、`send_at_ms`、`delay_ms`、有效 `offline.keep`/`ttl_seconds`、有效 `receipt` 做长度前缀（或有无标记）串联后算 SHA-256，输出小写十六进制；`meta` 用 `encoding/json` 对 `map` 键排序序列化；不含 `talk_password`、`rid`。
|
||
- 原因：文档未给规范格式，需固定、与键顺序无关、含可选字段区分。
|
||
- 备选方案：整段规范 JSON 对象再哈希。
|
||
- 影响：各语言 SDK / 服务端必须共用同一布局，否则防重失效。
|
||
|
||
2. **指纹使用文档默认值后的有效字段**
|
||
- 原条款：指纹字段列表含 `receipt`、`offline.*`，未说明缺省如何表示。
|
||
- 实际做法：`receipt` 缺省按 true；`offline.keep` 缺省 false；`keep` 为 true 且未给 `ttl_seconds` 时按 86400；`keep` 为 false 时 ttl 记 0；`content_type` 按 enc 补默认。
|
||
- 原因：重试时省略与显式默认应视为同一请求。
|
||
- 备选方案：按原始 JSON 有无字段区分，省略与显式默认算冲突。
|
||
- 影响：SDK 省略默认字段时防重仍命中。
|
||
|
||
3. **JSON Encoder 去掉尾部换行**
|
||
- 原条款：用 `json.Encoder` 且 `SetEscapeHTML(false)`。
|
||
- 实际做法：Encode 后去掉 `Encoder.Encode` 追加的 `\n`，整帧字节数不含该换行。
|
||
- 原因：MQTT 一发布一帧，示例 JSON 无尾换行；保留换行会抬高帧长并与本地 `frame_too_large` 判断不一致。
|
||
- 备选方案：保留换行并在 DEVELOPMENT 写明。
|
||
- 影响：线上帧比「裸 Encoder.Encode」少 1 字节。
|
||
|
||
4. **协议包校验范围**
|
||
- 原条款：T0.2 要求编号规则、正文/meta 大小、`send_at_ms`/`delay_ms` 互斥、登录密码不以 `nst_` 开头。
|
||
- 实际做法：上述必做之外，顺带校验各帧 `v`/`type`/`rid`、目标 kind、分页 limit、致命 reason 枚举等结构字段；业务错误（目标不存在、配额等）不在本包判定。
|
||
- 原因：无结构校验则编解码测试无法覆盖「合法帧」边界。
|
||
- 备选方案：协议包只做编解码，校验留给各 app 模块。
|
||
- 影响：服务端应复用本包 `Validate`，避免重复规则。
|
||
|
||
### T0.3 2026-09-30
|
||
|
||
1. **完整表放在 0002，不改已发布的 0001**
|
||
- 原条款：TASKS T0.3 / 4.2「`0001_init.sql` 包含第 7.7 节全部表」；T0.1 偏差曾写「T0.3 需替换 0001 正文」。
|
||
- 实际做法：保留 `0001_init.sql` 为 `SELECT 1;`；新增 `0002_schema.sql` 写入 DEVELOPMENT 7.7 全部业务表与索引（含 `api_tokens`、`settings`、`session_hash` 等）。`schema_migrations` 仍由迁移执行器 `CREATE TABLE IF NOT EXISTS` 维护，不放入 0002。
|
||
- 原因：T0.1 的 0001 可能已记入已有库的 `schema_migrations`；改写已发布迁移语义会导致「版本已应用但表不存在」。
|
||
- 备选方案：对未迁移库特殊检测并改写 0001（复杂且易错）。
|
||
- 影响：新库会有版本 1+2 两行；与 TASKS「表在 0001」字面不一致，与「不改已发布迁移」一致。
|
||
|
||
2. **写入队列先做一操作一事务**
|
||
- 原条款：DEVELOPMENT 7.2 合并提交（最多 256 或凑满 2ms，SAVEPOINT）；TASKS T0.3 允许简单实现，P2 换合并。
|
||
- 实际做法：`store.Queue` 用互斥锁串行，每请求一个事务；注释与本条标明 P2 再改为写 goroutine 合并提交。
|
||
- 原因：本任务范围；合并留给平台 P2。
|
||
- 备选方案：T0.3 直接做合并（抢 P2 范围）。
|
||
- 影响：高并发写入落盘次数偏多，正式压测前需完成 P2。
|
||
|
||
3. **空库不备份；仅已有 db 文件且有未应用版本时 VACUUM INTO**
|
||
- 原条款：DEVELOPMENT 7.7「有未应用版本时先 VACUUM INTO」；未区分空库。
|
||
- 实际做法：`Open` 在打开前检查 `nixmsg.db` 是否已存在；不存在则跳过备份；存在且有 pending 则写入 `<data_dir>/backup/pre-migrate-<UTC时间>.db`。迁移失败返回错误，不自动从备份恢复。
|
||
- 原因：空库备份无意义；失败退出与文档一致，恢复交给运维。
|
||
- 备选方案：失败时自动还原备份再退出。
|
||
- 影响：与任务说明一致；运维需知备份路径。
|
||
|
||
### T0.5 2026-09-30
|
||
|
||
1. **admin init / 管理员密码**
|
||
- 原条款：TASKS T0.5「自动执行 `admin init` 拿到管理员密码」；命令行启动器 JSON 含管理员密码。
|
||
- 实际做法：定义 `AdminInitializer`（默认 `CLIAdminInit`）；二进制尚无 `admin` 子命令时返回 `ErrAdminInitUnsupported`，启动器跳过并继续起 serve；`admin_password` 字段为空字符串。示例集成测试只验 `/healthz`。
|
||
- 原因：`admin init` 属 P1，当前 main 仅有 `version`/`serve`。
|
||
- 备选方案：harness 内嵌假密码写入库（无表结构可写）；或阻塞等 P1。
|
||
- 影响：P1 合入后无需改调用方接口，密码解析约定见 `parseAdminPassword`；Q/SDK 集成测试在拿到非空密码前勿依赖管理登录。
|
||
|
||
2. **MQTT 测试客户端范围**
|
||
- 原条款：能收发 DEVELOPMENT 第 6 节应用帧。
|
||
- 实际做法：提供 TCP / WebSocket（`/mqtt`，子协议 `mqtt`）传输层 `MQTTClient`，收发原始 MQTT 控制包字节；不实现 CONNECT/hello/主题业务。
|
||
- 原因：内置 broker 与协议处理尚未合入（连接 N / 后续任务）；T0.5 先给可连传输与占位 API。
|
||
- 备选方案：引入完整 MQTT 客户端库并编假 broker。
|
||
- 影响：业务级帧测试在 broker 可用后由各线基于 `Send`/`Recv` 或再包一层完成。
|
||
|
||
3. **进程停止方式**
|
||
- 原条款：优雅停机（DEVELOPMENT 7.8 / P1）。
|
||
- 实际做法：测试启动器对子进程使用 `Kill`（Windows 上 `Interrupt` 不可靠）。
|
||
- 原因：保证并行测试与清理在 Windows 上稳定。
|
||
- 备选方案：Unix 发 SIGTERM；Windows 用 Job Object / Ctrl+Break。
|
||
- 影响：不覆盖优雅停机验收；该验收仍归 P1/Q。
|
||
|
||
### T0.4 2026-09-30
|
||
|
||
1. **broker↔app 契约包放在 `internal/app/port`**
|
||
- 原条款：TASKS T0.4「broker 和 app 之间的接口」；示例路径 `internal/app/port` 或 `internal/broker/port`。
|
||
- 实际做法：放在 `internal/app/port`：`UplinkHandler`（broker→app）、`Downlink` / `ConnControl`（app→broker）。不依赖 mochi。
|
||
- 原因：契约由 app 消费形态主导，避免 broker 包在 N 线实现前成为空壳；N 线实现 broker 时 import 本包即可。
|
||
- 备选方案：放在 `internal/broker/port` 或单独 `internal/port`。
|
||
- 影响：N/M/I 依赖路径固定为 `internal/app/port`。
|
||
|
||
2. **接口方法先返回未实现或空操作，不做业务状态机**
|
||
- 原条款：T0.4 要求 Go 接口与测试假实现；不要实现真正业务逻辑。
|
||
- 实际做法：`auth` / `message` / `identity` / `group` 的写路径假实现返回 `ErrNotImplemented`；调度/推送/清理/在线查询等返回空成功或固定假数据；`wire()` 组装这些假实现，`serve` 仅调用 `RecoverOnStart`（空操作）并保留依赖引用。
|
||
- 原因：让后续各线有可编译的替换点，且不抢 P/N/M/I/A 实现范围。
|
||
- 备选方案：接口方法全部 panic；或完全不接线 serve。
|
||
- 影响：在假实现替换前，端协议与管理 API 仍不可用（本任务预期）。
|
||
|
||
3. **管理契约补充 `GET /api/admin/groups/{id}`**
|
||
- 原条款：DEVELOPMENT 第 8 节路由表列出 groups 的 GET/POST 列表创建与 PATCH/DELETE，未单列群详情。
|
||
- 实际做法：`docs/api/admin-api.md` 增加 `GET /api/admin/groups/{id}`（成员分页），供后台详情页使用。
|
||
- 原因：改名/解散/成员管理需要详情；与端协议 `group.get` 对称。
|
||
- 备选方案：详情拼进列表项或仅用 PATCH 回显。
|
||
- 影响：A/W 按契约实现该只读路由。
|
||
|
||
4. **CSV 导入校验失败时用信封外的 `data.errors`**
|
||
- 原条款：写明返回出错行号和原因；未规定 JSON 形状。
|
||
- 实际做法：HTTP 400，`ok=false`，`error.code=bad_request`，同行号列表放在顶层 `data.errors`。
|
||
- 原因：通用 `error` 只有 code/message，放不下多行明细。
|
||
- 备选方案：把明细塞进 `error.message` 字符串。
|
||
- 影响：W 线按 `data.errors` 渲染。
|
||
|
||
|
||
## 平台 P
|
||
|
||
### P1 2026-09-30
|
||
|
||
1. **admin set-password 传参方式**
|
||
- 原条款：DEVELOPMENT 11.2 仅列命令名，未规定密码如何传入。
|
||
- 实际做法：支持 `--password <pwd>`、位置参数，或从 stdin 读一行；最短 12 位。
|
||
- 原因：自动化测试与 Docker 非交互环境需要非交互传参。
|
||
- 备选方案：仅交互式 prompt。
|
||
- 影响：运维文档需写明推荐用 `--password` 或管道，勿把密码写进 shell 历史时可改用 stdin。
|
||
|
||
2. **admin init 密码字符集**
|
||
- 原条款：生成 20 位密码，未规定字符集。
|
||
- 实际做法：从去掉易混字符（0/O/1/I/l）的字母数字中均匀抽样 20 位。
|
||
- 原因：终端抄写友好。
|
||
- 备选方案：全 ASCII 可打印字符。
|
||
- 影响：熵略低于全字符集，对 20 位仍足够。
|
||
|
||
3. **PHC 哈希辅助先放在 auth，池在 P3**
|
||
- 原条款：argon2 并发池属 P3；admin init 需落库哈希属 P1。
|
||
- 实际做法：P1 在 `internal/auth` 提供 `HashPassword`/`VerifyPassword`（PHC），admin 命令直接调用；P3 再用同参数实现带并发上限的 `HashPool`。
|
||
- 原因：避免 P1 在 cmd 内复制算法，又不等到 P3 才做 init。
|
||
- 备选方案：P1 cmd 内联 argon2；或 P1/P3 合并提交。
|
||
- 影响：P3 合入后 admin 可改为走 HashPool（非必须，单次 init 无并发压力）。
|
||
|
||
4. **优雅停机顺序**
|
||
- 原条款：停接受 → 写队列最多 10 秒 → 断开连接退出。
|
||
- 实际做法：`http.Server.Shutdown`（先停接受并等待进行中的 HTTP）后，再 `Queue.Drain` 最多 10 秒；本期尚无长连接表，断开连接由 Shutdown 覆盖。
|
||
- 原因：当前 main 仅有 HTTP 健康检查；N 线接入后应在 Drain 前后显式踢连接。
|
||
- 备选方案：先关 listener、Drain、再 Shutdown。
|
||
- 影响：有 MQTT 长连接后需 N/P 联调停机路径。
|
||
|
||
### P2 2026-09-30
|
||
|
||
1. **合并写入队列替换 T0.3 简单实现**
|
||
- 原条款：DEVELOPMENT 7.2；TASKS P2。
|
||
- 实际做法：单写 goroutine；批次上限 256 或等待 2ms；每操作用 `SAVEPOINT`/`ROLLBACK TO`/`RELEASE`；Begin/Commit/SAVEPOINT 基础设施失败返回 `errors.Join(ErrBusy, err)` 并令 `IsReady()=false`；业务操作错误只回滚该 SAVEPOINT，不标 busy。
|
||
- 原因：满足每秒约 200 条写入的落盘合并需求。
|
||
- 备选方案：按固定时间窗无条件合并。
|
||
- 影响：调用方需用 `errors.Is(err, store.ErrBusy)` 映射协议 `busy`；`/readyz` 读 `DB.Ready`。
|
||
|
||
2. **调用方 context 取消与已入队任务**
|
||
- 原条款：未规定入队后取消。
|
||
- 实际做法：入队前检查 ctx；批次执行前再检查；若调用方在等待结果时取消，最多再等 30 秒取结果以免泄漏。
|
||
- 原因：写 goroutine 仍可能已执行该操作，不能静默丢结果。
|
||
- 备选方案：取消即从队列摘除（需可取消数据结构）。
|
||
- 影响：极端取消场景下调用方可能多等一会儿。
|
||
|
||
### P3 2026-09-30
|
||
|
||
1. **管理员/注册锁定阈值沿用登录 IP 档**
|
||
- 原条款：登录/对话密码阈值写清；管理员登录与注册安全码仅写「临时锁定」，未给数字。
|
||
- 实际做法：`LockAdminIP`、`LockRegisterIP`、`LockTalkPair`/`LockLoginEndpointIP` 均为 5 分钟窗口 10 次、锁 5 分钟；`LockTalkTarget`/`LockLoginEndpoint` 为 1 小时 50 次、锁 1 小时。
|
||
- 原因：与 PRD D18/F23「默认 5 分钟 10 次」叙述一致。
|
||
- 备选方案：管理员单独更严阈值。
|
||
- 影响：A/I/N 线直接用 `LoginLocks` 即可。
|
||
|
||
2. **真实 auth 实现未改 wire.go**
|
||
- 原条款：平台不改 `wire.go`；P3 实现接口。
|
||
- 实际做法：提供 `NewPool`/`NewSessionTokens`/`NewAPITokens`/`NewLoginLocks`；`wire()` 仍用 Stub，由总控或各线接线时替换。
|
||
- 原因：分工禁止改 wire.go。
|
||
- 备选方案：在 serve 旁路替换（会绕过 wire）。
|
||
- 影响：合入后需有一次接线才能在进程内用上真实哈希池。
|
||
|
||
3. **令牌随机部分用 RawURLEncoding**
|
||
- 原条款：32 字节随机数的 base64url。
|
||
- 实际做法：`encoding/base64.RawURLEncoding`（无 padding）。
|
||
- 原因：URL/Header 友好，与常见 token 惯例一致。
|
||
- 备选方案：StdEncoding 带 padding。
|
||
- 影响：SDK/文档示例需无 `=` 结尾。
|
||
|
||
## 连接 N
|
||
|
||
暂无。
|
||
|
||
## 消息 M
|
||
|
||
暂无。
|
||
|
||
## 身份 I
|
||
|
||
暂无。
|
||
|
||
## 后台接口 A
|
||
|
||
暂无。
|
||
|
||
## 后台网页 W
|
||
|
||
暂无。
|
||
|
||
## SDK 一 S1
|
||
|
||
暂无。
|
||
|
||
## SDK 二 S2
|
||
|
||
暂无。
|
||
|
||
## 测试交付 Q
|
||
|
||
暂无。
|