@crh-fe/oava-customer-sdk 1.0.1 → 1.0.2

package/README.md

@@ -1,21 +1,240 @@
-# Customer SDK
+# @crh-fe/oava-customer-sdk
 
-This package publishes the customer SDK built from the `widget` project.
+> 数字人视频见证 / 自助视频 双录访客端 SDK
+>
+> 由 `widget` 工程构建产出，对应源码 [widget/lib/customerIndex.js](../../lib/customerIndex.js)。
+>
+> 包名：`@crh-fe/oava-customer-sdk` · 版本：`1.0.1` · 入口：`dist/customerComponent.js`
 
-## Build package artifacts
+---
+
+## 一、特性
+
+- 基于 React + WebRTC 的访客端视频组件，支持**数字人坐席**和**真人坐席**两种模式
+- 一行 `new` 即可创建实例，自带 TURN/媒体协商、推流、订阅
+- 提供人脸在框检测、等待超时、转人工等业务事件回调
+- ES Module 包，`type: "module"`，浏览器原生或 webpack 5 均可消费
+
+---
+
+## 二、安装
+
+### 1. 从内部 npm 源安装（推荐）
+
+```bash
+npm install @crh-fe/oava-customer-sdk
+```
+
+### 2. 本地 tarball 安装
+
+仓库内已打好包：
+
+```bash
+npm install ./packages/customer-sdk/oava-customer-sdk-1.0.1.tgz
+```
+
+### 3. 通过 `public/` 静态文件直接引用（不推荐，仅用于本地调试）
+
+把 `widget/output/customerComponent.js` 拷到消费者工程的 `public/` 目录，然后用 `<script>` 标签引入，会挂载在 `window.CustomerComponent`（default export）。客户 demo [`demo/customer-demo/src/components/Home.vue`](../../../demo/customer-demo/src/components/Home.vue) 同时支持这两种方式的在线切换。
+
+---
+
+## 三、快速开始
+
+```js
+import Customer from "@crh-fe/oava-customer-sdk";
+
+// 1. 实例化，传入 TURN 服务地址
+const client = new Customer("turn:49.234.13.99?transport=udp");
+
+// 2. 监听会话结束事件（必接）
+client.onEnd((e) => {
+  // e.code 参考下方【事件码表】
+  console.log("会话结束", e);
+  client.destroy();
+});
+
+// 3. 初始化挂载。id 为空时挂到 body，否则挂到指定容器
+client.init("", {
+  roomToken: "后端派单接口返回的 roomToken",
+  aiServerUrl: "https://your-face-detect-server.com",
+  faceCheckTimer: 3000,   // 人脸在框检测间隔，单位 ms，默认 2000
+  maxWaitTime: 120,       // 等待数字人/真人接入超时，单位 s，默认 120
+  userFaceBase64: "...",  // 可选，用户人脸 base64，做人像比对
+});
+```
+
+---
+
+## 四、API 参考
+
+### 4.1 `new CustomerComponent(turnServerUrl)`
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `turnServerUrl` | `string` | 否 | IRTC 媒体平台 TURN 地址，默认 `turn:106.15.227.129:3478?transport=udp` |
+
+构造函数会在控制台输出：
+
+```
+[SDK Version] v1.0.1
+[SDK version] v1.0.1, turnServerUrl: <传入值>
+```
+
+### 4.2 `init(id, options)`
+
+挂载并启动组件。
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `id` | `string` | 否 | 容器 DOM 的 `id`；**传空字符串时挂载到 `body`**，会动态创建一个 `position: fixed; inset: 0;` 的全屏容器，组件卸载时自动移除 |
+| `options` | `object` | 是 | 见下表 |
+
+#### `options` 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `roomToken` | `string` | 是 | 房间 token，由后端 `/tokens` 或派单接口下发 |
+| `aiServerUrl` | `string` | 是 | 人脸在框检测服务地址 |
+| `faceCheckTimer` | `number` | 否 | 人脸在框检测间隔，单位 **ms**，默认 `2000` |
+| `maxWaitTime` | `number` | 否 | 等待数字人/真人接入的最大时长，单位 **s**，默认 `120` |
+| `userFaceBase64` | `string` | 否 | 用户人脸 base64，用于人像比对 |
+
+### 4.3 `destroy()`
+
+销毁组件、断开 WebRTC 推拉流、卸载 React 树，并自动移除由 `init("", ...)` 创建的 `customer-component-container-id` 容器。**一次会话结束务必调用**，否则下次 `new` 会残留 DOM。
+
+### 4.4 `onEnd(callback)`
+
+注册会话结束回调，**只能触发一次**，触发后回调被置空。回调参数：
+
+```ts
+type EndCallbackParams = {
+  code: string;        // 状态码，见下表
+  message: string;     // 描述
+  data?: any;          // 业务数据
+  type?: string;       // 自定义事件类型
+  reason?: string;     // 主动离开时的原因
+};
+```
+
+#### 事件码表
+
+| code | 含义 |
+| --- | --- |
+| `300` | 见证通过 |
+| `301` | 见证不通过 |
+| `400` | 用户自己主动离开 |
+| `401` | 用户自己主动离开，去自助视频 |
+| `6001` | 加入房间失败 |
+| `6002` | 创建本地摄像头失败 |
+| `6003` | 本地推流异常中断 |
+| `6004` | 推送本地画面失败 |
+| `6005` | 订阅数字人画面失败 |
+| `6008` | 数字人流结束 |
+| `7000` | 服务异常 |
+| `7002` | 数字人坐席离开 |
+| `8001` | 等待数字人接入超时 |
+| `8002` | 等待真人坐席接入超时 |
+
+> 转人工（`transfer`）期间，坐席相关的 6001/7002 等事件会被**抑制**，不再触发 `onEnd`，直到 `cancel-transfer` 复位。
+
+---
+
+## 五、完整示例（对齐客户 demo）
+
+[`demo/customer-demo/src/components/Home.vue`](../../../demo/customer-demo/src/components/Home.vue) 里的最小闭环：
+
+```js
+import Customer from "@crh-fe/oava-customer-sdk";
+
+// 1. 加入排队
+const queueRes = await request({
+  url: `${aiUrl}/auditcenter/authless/openapi/video/joinQueue`,
+  data: { task_id: taskId },
+});
+
+// 2. 轮询排队结果，坐席接入后拿到 roomToken
+const queryRes = await request({
+  url: `${aiUrl}/auditcenter/authless/openapi/video/queryQueue`,
+  data: { task_id: taskId },
+});
+const { room_id, room_token } = JSON.parse(queryRes.data.json_params);
+
+const tokenRes = await request({
+  url: "https://zmscrh.zealcomm.cn/tokens",
+  data: { room: room_id, user: "testuser", role: "presenter", domain: "public" },
+});
+
+// 3. 实例化 SDK 并启动
+const client = new Customer("turn:49.234.13.99?transport=udp");
+
+client.onEnd((e) => {
+  if (e.code == "300") showSuccess();         // 见证通过
+  else if (e.code == "301") showFail();        // 见证不通过
+  else if (e.code == "200") return;            // 收到转人工，不结束
+  else queryAuditResult();                     // 其它码：查后端审核结果
+  client.destroy();
+});
+
+client.init("", {
+  roomToken: tokenRes,                                // 派单接口下发的 roomToken
+  aiServerUrl: "https://cpekh.test.cairenhui.com",   // 人脸在框检测
+  faceCheckTimer: 300000,
+  maxWaitTime: 10000,
+});
+```
+
+---
+
+## 六、构建与发布
+
+### 6.1 本地构建
+
+回到 `widget/` 根目录：
 
 ```bash
+# 产出 output/customerComponent.js 并同步到本 package 的 dist/
 npm run build:npm:customer
 ```
 
-## Publish
+它会按顺序执行：
+1. `npm run build` — rollup 打包
+2. `npm run sanitize:customer` — 去除 bundle 中残留的 propTypes 警告链接等
+3. `npm run sync:customer-package` — 把产物拷到 `packages/customer-sdk/dist/`
+
+### 6.2 打包 tgz
+
+```bash
+cd packages/customer-sdk
+npm pack  # 产出 oava-customer-sdk-<version>.tgz
+```
+
+仓库内已附 `oava-customer-sdk-1.0.1.tgz`，可直接 `npm install` 本地引用。
+
+### 6.3 发布到 npm
 
 ```bash
 cd packages/customer-sdk
 npm publish
+# 私有源：npm publish --registry=https://your-private-registry/
 ```
 
-## Notes
+发布前确认：
+- `packages/customer-sdk/package.json` 里的 `name` 已改成你想要的 scope（当前为 `@crh-fe/oava-customer-sdk`）
+- `version` 字段按语义化版本号递增
+- `dist/customerComponent.js` 是最新构建产物
+
+---
+
+## 七、注意事项
 
-- Update the `name` field in `package.json` before the first publish.
-- Update the `version` field only for this package when needed.
+1. **包体积约 2.8 MB**（含 React/ReactDOM/IRT 媒体 SDK/业务组件），首次加载建议走 CDN 或拆 chunk 懒加载。
+2. **纯 ESM 包**（`type: "module"`）：webpack 4 / 旧版 vue-cli 默认走 CJS interop 会拿不到 `default`，请升级到 webpack 5 / vue-cli ≥ 5，或按需使用 `import("@crh-fe/oava-customer-sdk")` 动态导入。
+3. **必须先 `npm install`**：项目依赖里要显式声明 `@crh-fe/oava-customer-sdk`，否则构建/运行会报模块未找到。
+4. **TURN 地址要可访问**：构造器里的 TURN 服务必须与生产/测试环境媒体平台对齐，否则视频流不通。
+5. **onEnd 仅触发一次**：会话结束、收到见证结论、转人工之外的超时/异常都会触发，记得在回调里调用 `client.destroy()` 释放资源。
+6. **来源切换**（仅在 demo 中需要）：demo 同时演示了
+   - 本地静态文件 `public/customerComponent.js`（适合 SDK 还没发布时的联调）
+   - npm 包 `@crh-fe/oava-customer-sdk`（适合已发布后回归验证）
+   切换时务必先 `destroy()` 旧实例，避免 DOM/媒体通道残留。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crh-fe/oava-customer-sdk",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Customer JS SDK package for oava-widget",
   "type": "module",
   "main": "./dist/customerComponent.js",