docs(02): 状态表维护（C1/C3/D4 早已闭环）+ 新增一张「待后端回应」清单
主人早上问「需要后端做的事都写进文档了吗、本地还有没有独立事件」，我借这次盘点把协作文档收口： 1. **状态表维护**：C1（语音轮次不落库）、C3（voice_output 字段）、D4（无未读状态）三行原写 「待确认」，其实**早已解决**——C1/C3 由契约 v0.59 §3.15（语音改走与文本同一条编排路径、 voice_output 补 sessionId/deviceId），D4 由 v0.37（unreadCount + 已读游标，客户端已接入）。 按正文依据打勾，并写明「客户端至今没有语音 UI，所以 C1/C3 我们从未验证过」这一诚实边界。 F6 那行从「待确认」改成「问过、后端尚未回应」，让「谁在等谁」一眼可见。 2. **新增「客户端待后端回应的清单」**（文档末尾）：只列我们问过、还没拿到明确答复的七条—— stream_chunk 三点确认 / F6① upload url 绑 host / viewer 凭据路径或确认永远 501 / 并行 tool_use 配对的 P0（他们说在修）/ llm_usage.session_id 接线（同上）/ IM 入站文件的真机验证（只能主人做）/ 以及这次状态表维护本身请他们复核。 每条都写了「要什么」与「我们这边的处置」：例如 F6① 明确**不做绕行**（不猜 base、不重写历史 URL——那会把「服务端说是什么」变成「客户端以为是什么」）；viewer 那条给了二选一 （给铸造路径，或明确永远 501，那我们就不再把它当验收项挂着）。 本次提交只动文档。
This commit is contained in:
AskaEth committed
1 parent
219c50b7c2
commit
6c2cc57cdb
1 file changed
+23
-4
+23
-4
@@ -528,13 +528,13 @@
|
||||
| B4 | 枚举未穷举 | ✅ 已闭环（后端 `GET /api/v1/meta/enums` 契约 v0.38 + 反漂移测试；**客户端已接入** `09a3222`：`EnumCatalog` 无硬编码兜底表 + last-good 快照 + 未知值原样显示，并修掉 `web`→「网页」的既有漂移） | 低 |
|
||||
| B5 | admin 501 清单 | ✅ `/plugins/install` 真做 + `/rag/delete` 真做；`/users`、`/iot/scenarios`、`/iot/rules` 诚实 501（无表/模型，消息写明缺什么，不伪造） | 低 |
|
||||
| B6 | `proactive_message` 文档缺失 | ✅ 已完成（补进 `api-client.md` §3.6） | 低 |
|
||||
| C1 | 语音轮次不落库 | 待确认 | 中 |
|
||||
| C1 | 语音轮次不落库 | ✅ **后端已解决**（契约 **v0.59 §3.15**：语音改走**与文本同一条编排路径** ⇒ 会落库、会流式、跨端同步、忙时按既有规则排队）。⚠️ **但客户端至今没有语音输入 UI，所以这条我们从未验证过**；我们定的绕行仍是 `REST /audio/transcribe` 转写 → WS `chat`（落库 + 流式 + 编排）→ `REST /audio/speech` 播放，**不接 `voice_input`**（见本文 §C1） | 中 |
|
||||
| C2 | 语音降级无信号 | ✅ 已完成（`provider` 信号：transcribe/voice_output/speech 三处统一） | 中 |
|
||||
| C3 | `voice_output` 字段 | 待确认 | 低 |
|
||||
| C3 | `voice_output` 字段 | ✅ **后端已解决**（v0.59 §3.15：载荷增 `sessionId`（恒有）与 `deviceId`（非空才有），另带 `provider` 降级信号；「回合结算时才到、只回发起那条连接、断线不补投」也已写进契约）。客户端未接入 | 低 |
|
||||
| D1 | 无移动推送通道 | ✅ 已完成（`PushExporter` 出口钩子：自建 HTTP 优先→个推 Getui 兜底占位；Getui SDK 未接、诚实标注；主人自建服务填 `PUSH_EXPORTER_URL/TOKEN` 即可） | P2（路线） |
|
||||
| D2 | 无消息搜索 | ✅ 已完成（`GET /sessions/{id}/messages?q=` 会话内搜索，q/after 互斥） | P2 |
|
||||
| D3 | 无编辑/删除/重发 | ✅ 已完成（`PATCH/DELETE /api/v1/messages/{id}`；重发不做端点，客户端编辑后再发） | P2 |
|
||||
| D4 | 无未读状态 | 待确认 | P2 |
|
||||
| D4 | 无未读状态 | ✅ **已闭环**（后端 v0.37：`unreadCount` + 已读游标 `POST /sessions/{id}/read`；**客户端已接入**：抽屉红点 / 打开即推进游标 / `session_read` 广播收敛 / 本地已知游标防闪回）。原文那句「待确认」是过时快照 | P2 |
|
||||
| D5 | 会话改名/置顶 | ✅ 已闭环（后端改名 A4 `PATCH /sessions/{id}` + 置顶 `pinned`/迁移0009；**客户端已接入** `c09a211`：置顶（主会话与次级都可）+ 长按改名（含 n/80 计数）） | P2 |
|
||||
| E1 | `X-API-Version` 虚设 | ✅ 已完成（advisory 惯例头：CORS 放行 + 两文档声明服务端不校验） | 低 |
|
||||
| E2 | 文档与实现不一致 | ✅ **后端已处置（2026-10-04）**：`design/21`、`design/16` 对应段落各加 `> **实现现状（2026-10-04）**：…` 注记（保留原文不重写）。⚠️ 其中 **「消息 `mode` 不落库」是过时快照**（实际已落库 `b686d5f`），而**该错行曾被后端会话当作依据转述一次**——详见 `E2` 小节与「回执五」补记第 5 条 | 中 |
|
||||
@@ -547,7 +547,7 @@
|
||||
| F3 | **上传图片的 URL 在自部署链路取不到** | ✅ **已闭环**（后端 **v0.56**：`chat.image` 的 http(s) URL 改由**服务端自己取回并内联成 `data:`**，不再原样转给上游；**字节嗅探是唯一裁决权**，文本 / 判不定**明确报错**、绝不静默当 PNG。`/upload` 由此真正可用） | ~~高~~ 已闭环 |
|
||||
| F4 | `[用户分享]` 正文标记违反项目红线 | ✅ **已达成一致**：来源走**独立来源 system 消息**或既有 `deviceId`/`platform` 元数据，人类可见标记放**客户端渲染层**；**不拼正文**、身份绝不从提示词文本推导（后端「回执二」确认） | 中 |
|
||||
| F5 | `PATCH /sessions/{id}` 的 400 文案误导 | ✅ **已修**（`20d452a`：「两者都缺」→ `at least one of title or pinned is required`；「存在但空白」→ **`title must not be blank`**，两种情形已能区分） | 低 |
|
||||
| F6 | 上传产物 URL 绑 host + 「5 MiB」措辞不精确 | 待确认（① upload 的 `url` 由服务端按 `r.Host` 拼成绝对地址并**原样落库** ⇒ **换服务器地址后旧图取不回**，建议存**相对路径**、读侧按当前 base 解析；② 实查「解码后 5 MiB」**只对 base64 形态成立**，URL 形态受视觉层 **50 MiB** 约束 ⇒ 文档应按形态写清） | 中（①）/ 低（②） |
|
||||
| F6 | 上传产物 URL 绑 host + 「5 MiB」措辞不精确 | ⚠️ **问过、后端尚未回应**（① upload 的 `url` 由服务端按 `r.Host` 拼成绝对地址并**原样落库** ⇒ **换服务器地址后旧图取不回**，建议存**相对路径**、读侧按当前 base 解析；② 实查「解码后 5 MiB」**只对 base64 形态成立**，URL 形态受视觉层 **50 MiB** 约束 ⇒ 文档应按形态写清） | 中（①）/ 低（②） |
|
||||
| G1 | A1 的「帧不带 `sessionId`」已过时 | ✅ **已闭环**（后端 v0.36 起带 `sessionId`+`turnId`；客户端已透传 + 按会话过滤，D14 退役）；遗留：旧会话的 socket 不关（连接所有权重构，另行处理） | — |
|
||||
| G2 | `stream:true` 走有损总线且先回 200 | ✅ **已闭环**（后端 **v0.56** / `7512d59`：改为与 WS `chat` **同一条直达编排器**的路径；响应面 `200` / `202`+queueDepth / `409 chat_busy` / `500 chat_unavailable` / `503 chat_dispatch_failed` —— **`202`/`409` 现在真的会出现**，「恒 200」不再成立） | ~~中高~~ 已闭环 |
|
||||
| G3 | base64 图片被原样落库 → 每页历史都背着它 | ✅ **已闭环**（后端 **v0.56**：`image` 加**解码后 5 MiB** 硬上限 → `400 image_too_large`，且在**解码 / 落库 / 入模型之前**拦下；报错文案指路 `/upload`） | ~~中~~ 已闭环 |
|
||||
@@ -1449,3 +1449,22 @@ v0.61 让**扫描件/图片型 PDF** 落到 `status:"unreadable"`，而**原因
|
||||
「正文转文件」判决 API **原样留着、没有接线、也没有删**。等主人拍板后再动。
|
||||
**对你们的影响**只有一条：若最后决定「分享超长文本走文件」，走的就是既有的
|
||||
`POST /api/v1/documents` + `chat.documents`，**不需要新端点**，所以你们**现在什么都不用做**。
|
||||
|
||||
---
|
||||
|
||||
## 客户端**待后端回应**的清单（2026-10-05 早 · 只为对齐，不重复已闭环的）
|
||||
|
||||
> 只列**我们问过、还没拿到明确答复**的。已经闭环的那些不在这里重复。
|
||||
|
||||
1. **`stream_chunk` 三点确认**（2026-10-04 深夜登记，见上一节）：① 该帧今天还在产吗？② `delta` 是**增量**还是**整段**？③ 会不会与结构化帧**并存**？
|
||||
- 我们已按「非流式回退路径、`delta` 是增量、与结构化帧互斥」三点实现。若第 ① 条的答案是「已经不发」，我们就删掉那半条分支。
|
||||
2. **`F6①`：`POST /upload` 的 `url` 按请求时的 `r.Host` 拼成绝对地址并**原样落库**（2026-10-04 登记，**尚未回应**）。
|
||||
- 影响：**换服务器地址后旧图取不回**。建议落库存**相对路径**、读侧按当前 base 解析。
|
||||
- 我们这边**不做绕行**（不猜 base、不重写历史 URL）——那会把「服务端说是什么」变成「客户端以为是什么」。
|
||||
3. **铸 `viewer` 凭据的路径，或确认它永远 `501`**（2026-10-04 登记，**尚未回应**）。
|
||||
- 现状：`POST /api/v1/admin/users` 仍是 `501 not_implemented` ⇒ 我们**造不出 viewer 账号** ⇒ 「viewer 能读日志历史、收不到增量」这条**只能靠纯函数与线级单测背书，真机验不了**。
|
||||
- 要么给一条铸造路径，要么明确「永远 501」——**那我们就不把「真机验 viewer」当验收项**，不再挂着。
|
||||
4. **并行 `tool_use` / `tool_result` 的 P0**（你们「回执十二 §二」说在修）：收到，**修完补一条回执即可**，客户端不需要适配。
|
||||
5. **`llm_usage.session_id` 恒为 `NULL`**（你们「回执十二 §五」说 P0 修完后补接线）：同上，补完说一声。
|
||||
6. **IM 入站文件的真机验证**（你们「回执十二 §四」请主人验）：**只能由主人那边做**（我们没有 IM 渠道凭据，也不该去碰）。**在真机确认之前，我们两边都按「未验证」记。**
|
||||
7. ⚠️ **我们这边刚做过一次状态表维护**（2026-10-05 早）：`C1` / `C3` / `D4` 三行原写「待确认」，其实**早已由你们的 v0.59 §3.15 与 v0.37 解决**，已按正文依据打勾 —— 若我们打错了，请直接指出来。
|
||||
Reference in new issue
Block a user