[spec ⑥] WebChat 多租户收尾 — 前端一等公民化 + 后端潜伏接线 + 文档同步

[hrygo]

背景

WebChat 多租户线路图 spec ①-⑤ 后端已全部合入（#746 / #748 / #753 / #757 / #755）。spec ⑥（前端一等公民化）是线路图最后一个 spec，也是愿景达成的集大成环节。本 issue 跟踪从最后一个 PR（#757 spec ④ 企业 SSO）到线路图愿景完成的所有剩余代办。

后端"已合入" ≠ "端到端可用"。spec ① R9 max-effort review 曾把若干接线项挂账给 spec ⑥，其中部分已由 #757 解除（auth/oauth handler 注册、POST /api/sessions 强制 workspace_id），其余经代码核实仍潜伏。下表为精确清单。

---

A. 后端潜伏接线（spec ⑥ 前端的前提 · 端到端跑通的硬依赖）

• A1 · workspace CRUD 路由注册 🔴
  • internal/gateway/workspace_handlers.go 已实现 Create/List/Get/Update/Delete 五方法，但 cmd/hotplex/routes.go 未注册任何 /api/workspaces* 路由（grep 仅见传入 WorkspaceStore，无 mux.Handle）→ 潜伏代码。
  • 影响：前端 workspace 切换 UI 无 API 可调，spec ⑥ 硬前提。
• A2 · WS init 创建 session 绑定 workspace 🔴
  • internal/gateway/conn.go 无任何 WorkspaceID 引用，WS 协议创建的 session 绕过 workspace 隔离 + session key 方案3 分叉。
  • spec ① R9 跟进项 🚀 OpenCode Worker 集成与 Web Chatbot 开发 #4。REST 路径已强制（api.go:237-240），WS init 路径未对齐。
• A3 · disable 用户 per-request 校验 🟡 security
  • internal/security/auth.go:80 AuthenticateRequest（API key）不查 users.status，cookie auth 同理。登录入口（local/oauth）已查 disabled，但已认证 session 在有效期内（cookie 7d / API key 永久）disable 用户仍可访问。
  • spec ① R9 跟进项 📝 docs: Consolidate specs directory, validate ACPX spec, and fix Gateway Async Init #2。需 per-request 状态校验或缓存+失效。
• A4 · cookie HMAC secret 持久化 🟡 reliability
  • internal/security/cookie.go:52 仍 rand.Read 内存生成 secret，重启即失效，所有已登录用户被踢；多实例也无法共享。
  • spec ① R9 跟进项 📚 docs: Consolidate specs directory and add comprehensive Worker documentation #3。
• A5 · webchat 前端发送 workspace_id 对齐 REST 强制 ⚠️
  • 后端 POST /api/sessions 已强制 workspace_id（api.go:237-240），webchat 前端尚未发送 → 当前 webchat REST 建会话可能 400。需先确认对现有 webchat 流程的影响，再由 spec ⑥ 前端对齐。

B. spec ⑥ 前端一等公民化（主体工作）

• B1 登录页（内建账号 + spec ④ OAuth 入口，消费 GET /api/auth/oauth/providers）
• B2 workspace 切换 UI（消费 A1 的 /api/workspaces CRUD）
• B3 worker 选择 UI（消费 spec ③ worker_preference）
• B4 agent-configs 编辑 UI（消费 spec ② agent_config_overrides）
• B5 OAuth post-login routing + 错误渲染（internal/gateway/oauth_handlers.go:175,254 留有 spec ⑥ 注释）

C. 文档同步（可立即做，不阻塞）

• C1 docs/specs/README.md 索引滞后：Roadmap/Foundation 仍标 proposed/draft 0%（实际完成）；缺 spec ②③④⑤ 四个子 spec 索引行；状态统计数字失真。
• C2 docs/specs/WebChat-Multitenancy-Roadmap-Spec.md 正文 §3 阶段B表格 spec ④ 未标 ✅、§4 spec ④ 详述未标完成（与头部 L4 已更新不一致）。

D. 遗留 / 升级时处理

• D1 migration 018 旧 API-key WS 会话 DeriveSessionKey 派生键断裂（升级孤儿行，spec ① R9 跟进项 ✨ feat(gateway,webchat): OpenCode CLI/Server workers, webchat UI, persistent sessions, and platform messaging extension #6）
• D2 spec ① 剩余增量：迁移验证测试 / 旧 webchat 会话清理 / e2e 集成测试

---

参考

• 线路图：WebChat-Multitenancy-Roadmap-Spec.md
• spec ① R9 跟进项来源：PR feat: WebChat 多租户地基（spec ① Phase 0-7） #746 review
• 已合入：feat: WebChat 多租户地基（spec ① Phase 0-7） #746(①) · WebChat 多租户 spec ②：per-workspace agent-configs 两层继承 #748(②) · WebChat 多租户 spec ③：workspace 级 worker 选择 #753(③) · WebChat 多租户 spec ④：企业 SSO（OIDC 统一认证） #757(④) · WebChat 多租户 spec ⑤：配额增强设计（热重载完整化 + 聚合指标） #755(⑤)