# 前端三件（production/web）

原生 JS，无构建步骤。部署时由后端按 `WEB_DIR` 静态托管，或任意静态服务器/CDN 分发。
接口契约见上级目录 `SPEC.md`（§2 WS 协议 / §3 REST / §6 前端三件）。

## h5/ — B轨 H5 聊天页

- 入口：`h5/index.html?token=<chat_token>&dl=<推广码>&theme=<主题>`
- WS 同源推导 `ws(s)://<host>/ws`；可用 `&apiBase=<基址>` 覆盖 REST 基址（跨域部署时）。
- token 只走 WS `auth` 帧，绝不进 URL query 之外的日志面；无 token 显示「链接无效」页。
- 能力：乐观 UI + sending→sent→delivered→read 状态机、failed 一键重发（复用 cmid）、
  指数退避重连（1/2/4/8/16/30s + jitter≤500ms）、25s 心跳、history_sync 按 last_seq 补齐、
  queue_update 排队条、invite 触达卡（invite_ack 回报 accepted/dismissed）、
  图片走 `/api/v1/upload/signature` 直传后发 image 消息、typing 300ms 防抖、
  弱网（RTT>1s）黄条并关闭 typing/已读回执。
- 演示：`h5/index.html?demo=1`（本地模拟：排队→接入→收发→已读→触达卡全流程）。

## sdk/ — A轨内嵌 SDK

- 游戏站接入：引入 `loader.js` 后 `GameChat.init({ token, getFreshToken, wsUrl?, apiBase?, dl? })`。
- `wsUrl` 不填按页面同源推导 `/ws`；`dl` 不填自动读页面 URL 的 `?dl=`；
  beacon 默认 POST `apiBase + /api/v1/sdk/beacon`（sendBeacon），`beaconUrl` 可覆盖。
- token 走 auth 帧；`E_AUTH_EXPIRED` 自动回调 `getFreshToken()` 续期重连。
- 保留原型已验证能力：closed Shadow DOM 隔离、渲染错误边界、iframe 降级（__CHAT_BRIDGE__）、演示模式。
- 演示：`sdk/demo.html`（demo:true，加载 6s 后自动触发一次 deposit_failed 触达卡）。

## workbench/ — B端客服工作台

- 入口：`workbench/index.html`（同源部署）；跨域时加 `?apiBase=<基址>`。
- 登录：`POST /api/v1/agent/login` 换 agent_token（存 sessionStorage，本标签页保持登录）。
- WS 帧：conv_assigned / message / notice / queue_update / conv_recalled / typing / server_ack / receipt；
  REST：conversations 列表、accept / transfer / close / note、canned 话术 CRUD。
- 多站聚合：顶栏下方站点 tabs（全部站点 + agent.sites），会话按 site 过滤聚合；
  presence（online/busy/offline）切换发 `agent_presence` 帧。
- 演示：`workbench/index.html?demo=1`（任意口令登录；种子含 569711 / mgm-02 两站会话）。

## 验证

`review/` 下为无头浏览器实测截图（均以 demo 模式打开，控制台零报错）：
h5-demo.png / h5-invalid.png / sdk-demo.png / wb-demo.png。