feat: 补齐模块接口契约与管理 API 文档

docs/DEVIATIONS.md

@@ -119,6 +119,36 @@
    - 备选方案：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