docs(02): logs REST 已接上（闭环）+ 五条契约口径建议补写 + 铸不出 viewer 账号的验收缺口

devdocs/02-前后端协同事项.md

@@ -1008,3 +1008,32 @@ POST /api/v1/chat      (221-byte body) → 200 OK
 ### 四、证据暂时保留
 
 该测试会话（`web:95827de3c277e6b80ab70d698224753e`）**暂时保留**，方便你们回看那条 user 消息与两次工具失败的时序。你们回执里说一声「可以删」，我们再清掉。
+
+---
+
+## 登记（客户端会话，2026-10-05 凌晨 · logs REST 已接上 + 五条契约口径需补写）
+
+### 一、闭环：我们之前承诺的「下一步把 logs 接上」已完成
+
+`GET /api/v1/admin/observability/logs` 现已被客户端接入（`AdminRepository.logs()` + `AdminApi`），「最近日志」区块从**「只显示进页面之后」**变成**「REST 历史 + 帧增量」**。之前 `02` 里那条「日志没有历史引导」的客户端欠账**可以关掉了**。我们按契约核过的形状（供你们对账）：
+
+- 响应 `{"data":[{time,level,source,msg}]}`（**数组**，非对象）；`time` = **RFC3339 UTC 秒精度**；**倒序（最新在前）**。
+- `level ∈ debug|info|warn|error`，是**最低等级过滤**（`warn` ⇒ warn+error）；缺省 = 全部；未知值 `400 invalid_level`。
+- `limit` 缺省 **200**、上限 **1000**（`≤0`/非法回落 200）。
+- `viewerAuth`（与 `metrics`/`trace` 同档）；未注入环形缓冲 ⇒ `501 not_implemented`（不伪造空 tail）。
+- 这次读取同时是**推送订阅握手**（§3.12）。
+
+**我们的取舍**：**不传 `?level=`**，一律取全量、**本地过滤**（与帧侧口径一致；否则服务端最低等级过滤会「饿死」本地那排要来回切的等级档）。
+
+### 二、五条建议补进契约（都不阻塞我们，但会咬后来人）
+
+1. **REST 与推送锚点的精度差没写**：推送循环的锚点用的是**纳秒**内部时间（`observability_push.go` 的 `lastLogTime`），而下发的 `time` **只有秒** ⇒ **秒级并列时「谁新」在线上无法区分**。契约只对**单份来源**保证「最新在前」，**拼接后的整体顺序是客户端自己拼的**。我们据此**自己定义顺序**（按 `time` 倒序 + 稳定排序保住到达序 + 按整条内容去重），而不是从两处局部顺序去推断。建议契约明写这一条，否则每个客户端都会各写一套。
+2. **同一秒、同 `level`/`source`/`msg` 的两条日志会被去重成一条**（日志**没有 id**，去重键只能是这四个字段——与你们 Web 面板同口径）。契约没提这条代价。若将来日志带上稳定 id，客户端可以换成按 id 去重。
+3. **`limit` 的默认值容易误读**：端点表 logs 那行写「默认 2000 条」其实是**环形缓冲容量**，而**响应条数**上限是 **1000 / 缺省 200**；同时 §2 首行的「`?limit` 缺省 50、上限 500」是给 `metrics`/`trace`/`audit` 的，**不适用于 logs**。建议在 logs 行直接写「响应上限 1000、缺省 200」。
+4. **`?level=` 的空白/大小写容忍没写**：实现是 `TrimSpace` + `Lower`（`level= WARN ` 合法），契约只说「大小写不敏感」。
+5. **`POST /api/v1/admin/users` 仍是 `501 not_implemented`** ⇒ 我们**铸不出 `viewer` 账号**，于是「viewer 在概览页能读日志历史、但收不到增量」这条**只能靠纯函数与线级单测背书，真机验不了**。若你们希望这条被真机验证过，给一条铸 viewer 凭据的路径（或确认永远 501，那我们就不把「真机验 viewer」当验收项）。
+
+### 三、顺带（与上一条登记衔接）
+
+- `observability_audit` 帧仍未做，审计 tab 仍是 REST——**我们没有按帧实现**，一致，无异议。
+- 「订阅会被没有在线 WS 连接剪掉」的既有对策没变（客户端连接常驻 + 每次连上重读 REST 重建订阅）。