@cg-devcenter/rtc-fpnn-webjs-sdk 1.0.0-cg.8 → 1.0.0-cg.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +4 -6
- package/docs/CAPABILITIES.md +1 -2
- package/docs/RTM_MIGRATION.md +1 -1
- package/docs/USAGE.md +2 -3
- package/package.json +1 -3
- package/docs/NPM_MODERNIZATION_PLAN.md +0 -475
- package/docs/TLV_LIVE_E2E_TEST.md +0 -115
package/README.md
CHANGED
|
@@ -8,9 +8,9 @@ RTC WebSocket Client SDK。新接入建议使用 `protocol: 'tlv-v1'`;`fpnn`
|
|
|
8
8
|
npm install @cg-devcenter/rtc-fpnn-webjs-sdk@latest
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
包根 ESM 入口和 `/vite-plugin` 已包含在 npm `latest` 中。普通业务项目和三个框架 Demo 直接从 npm 安装 SDK;HTML Demo 使用仓库构建出的 UMD
|
|
11
|
+
包根 ESM 入口和 `/vite-plugin` 已包含在 npm `latest` 中。普通业务项目和三个框架 Demo 直接从 npm 安装 SDK;HTML Demo 使用仓库构建出的 UMD 文件。各环境的接入方法见下方接入指南。
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
本地构建版本由根目录 `package.json` 管理;框架 Demo 从 npm 安装已发布的版本。通过 `@latest` 安装时,npm 会选择 registry 当前发布的最新版本。
|
|
14
14
|
|
|
15
15
|
## 本地构建
|
|
16
16
|
|
|
@@ -28,7 +28,7 @@ Node.js 使用 TLV v1 时,需自行提供 `webSocketFactory(url)`。SDK 不携
|
|
|
28
28
|
|
|
29
29
|
### 默认共享入口
|
|
30
30
|
|
|
31
|
-
工作区当前的 `createClient()` 在浏览器支持 SharedWorker
|
|
31
|
+
工作区当前的 `createClient()` 在浏览器支持 SharedWorker 且配置可安全传递时默认共享连接;浏览器不支持或配置含页面运行时值时自动使用当前页面的独立连接。npm `latest` `1.0.0-cg.8` 可通过 `client.getConnectionInfo()` 报告所选模式和回退原因;浏览器不支持 SharedWorker 或配置含页面运行时值时,会自动使用页面内连接。省略 `protocol` 时默认使用 FPNN,以兼容旧 `RTMClient` 接入。新项目使用 TLV 时请显式设置 `protocol: 'tlv-v1'`。支持共享的环境中,SDK 自动按 PID、协议、UID 和 Gate 地址隔离会话;同一环境的页面自动复用,业务无需配置 Worker 名称或路径。UID 可直接从 `login()` 获取。
|
|
32
32
|
|
|
33
33
|
```js
|
|
34
34
|
const client = rtm.createClient({ protocol: 'tlv-v1', pid, tlvEndpoint: endpoint });
|
|
@@ -39,7 +39,7 @@ await client.promises.sendChat(peerUid, 'hello', '{}');
|
|
|
39
39
|
client.destroy();
|
|
40
40
|
```
|
|
41
41
|
|
|
42
|
-
片段中的 `rtm`、项目参数、credential 和 `renderMessage` 由应用提供;完整流程和能力边界见 [默认共享接入](docs/USAGE.md#默认共享接入)。从旧 `new RTMClient()` 迁移且继续使用 FPNN 时,可将构造器替换为 `createClient()` 并沿用 `endpoint` 配置;工厂默认协议为 FPNN。在浏览器支持 SharedWorker
|
|
42
|
+
片段中的 `rtm`、项目参数、credential 和 `renderMessage` 由应用提供;完整流程和能力边界见 [默认共享接入](docs/USAGE.md#默认共享接入)。从旧 `new RTMClient()` 迁移且继续使用 FPNN 时,可将构造器替换为 `createClient()` 并沿用 `endpoint` 配置;工厂默认协议为 FPNN。在浏览器支持 SharedWorker 且配置可传递时自动共享;配置不可传递或浏览器不支持时自动使用独立连接,并可通过 `client.getConnectionInfo()` 查看实际模式和回退原因。npm `latest` `1.0.0-cg.8` 已支持这些能力。显式设置 `sharing: false` 也会选择独立连接。现代 ESM 项目从包根导入;Vite 项目另在配置中注册 `/vite-plugin`,避免开发依赖预构建改写 SDK 的 Worker URL;Worker 资源由 Vite 构建输出。详见 [接入指南](docs/USAGE.md)。
|
|
43
43
|
|
|
44
44
|
### 原有单连接入口
|
|
45
45
|
|
|
@@ -105,10 +105,8 @@ HTML/JavaScript、Vue 3、Vue 2.7 和 React 的发送台与收件箱 Demo 见源
|
|
|
105
105
|
|
|
106
106
|
- [接入指南与 API 参数](docs/USAGE.md)
|
|
107
107
|
- [从 GitHub 上游 SDK 迁移:新增 API、签名变化与兼容差异](docs/RTM_MIGRATION.md)
|
|
108
|
-
- [npm 接入现代化实施、验证与发布记录](docs/NPM_MODERNIZATION_PLAN.md)
|
|
109
108
|
- [FPNN 与 TLV v1 迁移对照](docs/PROTOCOL_MIGRATION.md)
|
|
110
109
|
- [能力总览与典型业务流程](docs/CAPABILITIES.md)
|
|
111
110
|
- [TLV v1 URI、请求字段与返回值](docs/TLV_CONTRACT.md)
|
|
112
111
|
- [TLV v1 传输规则](docs/TLV.md)
|
|
113
|
-
- [在线 Gate 验证](docs/TLV_LIVE_E2E_TEST.md)
|
|
114
112
|
- [TypeScript 声明](dist/rtm.d.ts)
|
package/docs/CAPABILITIES.md
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
|
|
9
9
|
## 能力地图
|
|
10
10
|
|
|
11
|
-
推荐通过 `createClient()` 接入:扁平配置,UID 从登录参数取得;浏览器支持 SharedWorker 且配置可安全传递时,SDK 按 PID、协议、UID 和 Gate endpoint
|
|
11
|
+
推荐通过 `createClient()` 接入:扁平配置,UID 从登录参数取得;浏览器支持 SharedWorker 且配置可安全传递时,SDK 按 PID、协议、UID 和 Gate endpoint 自动隔离并复用连接。npm `latest` `1.0.0-cg.8` 在不支持 Worker 或配置包含函数、自定义对象等运行时值时,自动使用当前页面连接;`getConnectionInfo()` 报告实际模式和回退原因。工厂和 `RTMSharedWorkerClient` 省略协议时均默认使用 FPNN,TLV 需显式选择。`sharing: false` 可显式选择页面内连接;旧构造器保留业务 API。混用共享入口时,连接参数仍须保持一致。npm `latest` `1.0.0-cg.8` 已包含包根 ESM、构建插件、配置值回退和诊断 API。配置、错误和生命周期见 [默认共享接入](USAGE.md#默认共享接入)。
|
|
12
12
|
|
|
13
13
|
| 业务目标 | SDK 能力 | 常用 API |
|
|
14
14
|
| --- | --- | --- |
|
|
@@ -127,4 +127,3 @@ const result = await client.promises.sendChat(peerUid, 'hello', '{}', 0, 12000);
|
|
|
127
127
|
- [FPNN 与 TLV v1 迁移对照](PROTOCOL_MIGRATION.md)
|
|
128
128
|
- [TLV v1 URI、字段和返回值](TLV_CONTRACT.md)
|
|
129
129
|
- [TLV v1 frame 与编解码](TLV.md)
|
|
130
|
-
- [在线验证与业务套件](TLV_LIVE_E2E_TEST.md)
|
package/docs/RTM_MIGRATION.md
CHANGED
|
@@ -101,7 +101,7 @@ const independentClient = rtm.createClient({
|
|
|
101
101
|
|
|
102
102
|
### 启用 SharedWorker 后真正需要调整的地方
|
|
103
103
|
|
|
104
|
-
|
|
104
|
+
npm `1.0.0-cg.8` 的 `createClient()` 会在配置不能安全传递给 Worker 时使用页面内 `RTMClient`,并通过 `getConnectionInfo()` 报告原因。该版本已包含配置回退和 `getConnectionInfo()` 诊断,浏览器不支持 SharedWorker 时也会使用页面内连接。
|
|
105
105
|
|
|
106
106
|
| 接入部分 | 迁移要求 |
|
|
107
107
|
| --- | --- |
|
package/docs/USAGE.md
CHANGED
|
@@ -22,7 +22,7 @@
|
|
|
22
22
|
|
|
23
23
|
请随文提供以下环境信息,避免接入者猜测项目配置或尝试从浏览器获取项目密钥:
|
|
24
24
|
|
|
25
|
-
- SDK:测试项目可安装 npm `latest` 标签对应的版本:`npm install @cg-devcenter/rtc-fpnn-webjs-sdk@latest`。包根 ESM 与 Vite、Webpack 4 构建插件均已随 npm `latest`
|
|
25
|
+
- SDK:测试项目可安装 npm `latest` 标签对应的版本:`npm install @cg-devcenter/rtc-fpnn-webjs-sdk@latest`。包根 ESM 与 Vite、Webpack 4 构建插件均已随 npm `latest` 发布。当前 registry `latest` 为已发布的 `1.0.0-cg.8`,下文所述配置回退和 `getConnectionInfo()` 均可通过 npm 包使用。
|
|
26
26
|
- RTC 环境:`pid`、协议(通常为 `tlv-v1`)、完整 WebSocket endpoint,以及应用页面的 origin。
|
|
27
27
|
- 测试身份:发送 UID、接收 UID、账号权限和预期验证场景;不要在文档或任务描述中粘贴长期凭证。
|
|
28
28
|
- credential 获取方式:由哪个业务服务端接口签发、请求需要的登录态/参数、响应 JSON 字段名和 credential 有效期。项目 `SecretKey` 只保留在受控服务端或本机签发工具中。
|
|
@@ -42,7 +42,7 @@
|
|
|
42
42
|
|
|
43
43
|
### 默认共享接入
|
|
44
44
|
|
|
45
|
-
|
|
45
|
+
npm `1.0.0-cg.8` 的 `createClient(options)` 优先使用 SharedWorker;浏览器不支持 SharedWorker,或配置中含有无法保留到 Worker 的运行时值(例如函数型 `webSocketFactory`、`md5`、`platformImpl` 或 metadata)时,会自动使用当前页面内的 `RTMClient`。两种模式使用同一个 `createClient()` facade、业务 API、事件和 Promise 接口;页面内模式不共享连接或登录态。该版本可通过 `client.getConnectionInfo()` 读取 `{ mode: 'shared' | 'direct', fallbackReason: string | null }`。`sharing: false` 会主动选择页面内模式,`fallbackReason` 为 `null`。Worker 脚本加载失败、初始化失败或超时仍会报告错误,不会静默改成页面内连接。省略 `protocol` 时默认使用 FPNN;直接构造 `RTMSharedWorkerClient` 表示明确要求 Worker,不能传输的配置会抛出具体原因。只有显式设置 `protocol: 'tlv-v1'` 才选择 TLV v1。该发布版本支持配置值不可传递时自动改用页面内连接,并通过 `getConnectionInfo()` 报告模式与回退原因;浏览器不支持 SharedWorker 时也会使用页面内连接。共享连接按 PID、协议、UID 和 Gate endpoint 区分环境;两个共享入口在连接参数一致时可复用同一会话。
|
|
46
46
|
|
|
47
47
|
```js
|
|
48
48
|
const client = rtm.createClient({ pid, endpoint, webSocketFactory });
|
|
@@ -619,5 +619,4 @@ TLV 不支持的调用按实现分为三类:
|
|
|
619
619
|
- [FPNN 与 TLV v1 迁移对照](PROTOCOL_MIGRATION.md)
|
|
620
620
|
- [TLV v1 URI、参数类型与返回字段](TLV_CONTRACT.md)
|
|
621
621
|
- [TLV v1 frame 与传输规则](TLV.md)
|
|
622
|
-
- [在线 Gate 验证说明](TLV_LIVE_E2E_TEST.md)
|
|
623
622
|
- [TypeScript API 声明](../dist/rtm.d.ts)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cg-devcenter/rtc-fpnn-webjs-sdk",
|
|
3
|
-
"version": "1.0.0-cg.
|
|
3
|
+
"version": "1.0.0-cg.9",
|
|
4
4
|
"description": "Browser RTM SDK with FPNN and TLV v1 MessagePack WebSocket transports",
|
|
5
5
|
"main": "./dist/rtm.min.js",
|
|
6
6
|
"browser": "./dist/rtm.min.js",
|
|
@@ -13,10 +13,8 @@
|
|
|
13
13
|
"docs/TLV.md",
|
|
14
14
|
"docs/TLV_CONTRACT.md",
|
|
15
15
|
"docs/CAPABILITIES.md",
|
|
16
|
-
"docs/TLV_LIVE_E2E_TEST.md",
|
|
17
16
|
"docs/USAGE.md",
|
|
18
17
|
"docs/RTM_MIGRATION.md",
|
|
19
|
-
"docs/NPM_MODERNIZATION_PLAN.md",
|
|
20
18
|
"docs/PROTOCOL_MIGRATION.md",
|
|
21
19
|
"docs/Users.md",
|
|
22
20
|
"docs/Groups.md",
|
|
@@ -1,475 +0,0 @@
|
|
|
1
|
-
# npm 接入现代化:实现与验证记录
|
|
2
|
-
|
|
3
|
-
状态更新(2026-10-13):工作区包版本已升至 `1.0.0-cg.8`,重建并审计本地 npm tarball;该版本尚未发布。registry `latest` 仍为 `1.0.0-cg.7`,此前已直接从 registry 安装到三个 Vite Demo,并在 Vite 6.4.4 下完成生产构建;包根 ESM、`/vite-plugin`、`/webpack4` 和 SharedWorker 入口均在该发布包中。`cg.8` 工作区构建新增的不可传输配置直连回退和 `getConnectionInfo()` 尚未发布;框架 Demo lockfile 仍固定 `cg.7`,因此使用 SharedWorker 可用性兼容推断。真实 Gate 多窗口验收和业务试接入仍未完成。
|
|
4
|
-
|
|
5
|
-
本文基于 2026-10-13 的仓库状态编写。范围是 SDK 发布格式、Worker 资源接入和兼容验证。协议与业务 API 继续遵循 [接入指南](USAGE.md) 和 [协议迁移说明](PROTOCOL_MIGRATION.md)。
|
|
6
|
-
|
|
7
|
-
## 1. 要解决的问题与完成标准
|
|
8
|
-
|
|
9
|
-
改造前的入口基线如下:
|
|
10
|
-
|
|
11
|
-
| 当前入口 | 仓库实现 | 接入成本 |
|
|
12
|
-
| --- | --- | --- |
|
|
13
|
-
| 包根入口 | `main`、`browser`、`exports["."]` 指向 `dist/rtm.min.js`,即 UMD | npm 的 ESM 接入依赖 UMD/CommonJS 互操作;共享连接需要处理 Worker 资源地址 |
|
|
14
|
-
| `/vite` | `dist/rtm.vite.mjs` 包装 UMD,并以 `?url` 导入 Worker | 业务选择专用入口;现有 Demo 还配置 `optimizeDeps.include/exclude` |
|
|
15
|
-
| 普通 HTML | 加载 `rtm.min.js`,从 `window.rtm` 使用 | 主脚本与 Worker 同源、同目录时,SDK 自动定位 Worker |
|
|
16
|
-
| CommonJS | `require()` 加载 UMD | Node 可加载 SDK;TLV 独立连接仍需注入 WebSocket 实现 |
|
|
17
|
-
|
|
18
|
-
改造后,`npm run build` 还会生成包根 ESM、入口类型和构建插件。现代 ESM 项目从包根导入;Vite 在配置中增加一次 SDK 插件;Webpack 4 使用 `/webpack4` 插件。普通脚本和 CommonJS 仍走原 UMD 文件,旧 `/vite` 路径保留。
|
|
19
|
-
|
|
20
|
-
目标是让 Vue 2、Vue 3、React、普通 JS 和 TypeScript 使用同一套 SDK API。构建工具的差异由发布格式和配套插件处理。
|
|
21
|
-
|
|
22
|
-
完成标准:
|
|
23
|
-
|
|
24
|
-
1. 现代 npm 项目可从包根进行默认导入和具名导入;业务代码不填写默认 `workerUrl`,不复制 Worker 文件。
|
|
25
|
-
2. 支持范围内的 Vite、Webpack 5 在开发服务器和生产构建中均能使用共享连接。优先实现零额外配置;若某版本需要插件,支持矩阵明确标注,插件负责完整配置。
|
|
26
|
-
3. Webpack 4 项目最多添加一次 SDK 构建插件,不要求业务维护资源路径。
|
|
27
|
-
4. 普通 HTML 的 `window.rtm`、现有 CommonJS、旧 `/vite` 和公开 API 继续可用。
|
|
28
|
-
5. 同 UID 多页面仍复用同一个 Worker 和一条 Gate WebSocket;`destroy()` 只释放当前页面。
|
|
29
|
-
6. 使用实际 npm tarball 和 registry `latest` 完成验证,保留可追溯证据。
|
|
30
|
-
|
|
31
|
-
“任意构建工具都零配置”不作为承诺。Vue/React 版本不能代替构建工具版本作为支持依据。
|
|
32
|
-
|
|
33
|
-
## 2. 目标使用方式与兼容边界
|
|
34
|
-
|
|
35
|
-
### 2.1 现代 npm 项目
|
|
36
|
-
|
|
37
|
-
现代 npm 项目从包根进行默认导入和具名导入,业务代码不填写默认 `workerUrl`,不复制 Worker 文件:
|
|
38
|
-
|
|
39
|
-
```js
|
|
40
|
-
import rtm, { createClient, RTMConfig } from '@cg-devcenter/rtc-fpnn-webjs-sdk';
|
|
41
|
-
|
|
42
|
-
// pid、endpoint、uid、credential 由业务提供。
|
|
43
|
-
const client = createClient({
|
|
44
|
-
protocol: 'tlv-v1',
|
|
45
|
-
pid,
|
|
46
|
-
tlvEndpoint: endpoint,
|
|
47
|
-
uid,
|
|
48
|
-
autoReconnect: true,
|
|
49
|
-
});
|
|
50
|
-
|
|
51
|
-
client.processor.on(RTMConfig.TLV_SERVER_PUSH.recvMessage, renderMessage);
|
|
52
|
-
await client.promises.login(uid, credential);
|
|
53
|
-
await client.promises.sendChat(peerUid, 'hello', '{}');
|
|
54
|
-
|
|
55
|
-
// 页面/组件释放时调用;共享连接的其他页面继续使用。
|
|
56
|
-
client.destroy();
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
Vite 项目只在构建配置中增加一次 SDK 插件;应用模块仍然从包根导入:
|
|
60
|
-
|
|
61
|
-
```js
|
|
62
|
-
// vite.config.js
|
|
63
|
-
import { rtmSdkVitePlugin } from '@cg-devcenter/rtc-fpnn-webjs-sdk/vite-plugin';
|
|
64
|
-
|
|
65
|
-
export default {
|
|
66
|
-
plugins: [rtmSdkVitePlugin()],
|
|
67
|
-
};
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
默认导入 `rtm.createClient()` 与具名导入 `createClient()` 必须执行同一套资源解析逻辑。底层 `RTMSharedWorkerClient` 构造器也必须获得相同的默认 Worker 地址,不能只修工厂入口。
|
|
71
|
-
|
|
72
|
-
### 2.2 普通 HTML 与 CommonJS
|
|
73
|
-
|
|
74
|
-
普通 HTML 继续部署 `rtm.min.js` 和 `rtm.shared-worker.js` 到同源、同目录:
|
|
75
|
-
|
|
76
|
-
```html
|
|
77
|
-
<script src="/sdk/rtm.min.js"></script>
|
|
78
|
-
<script>
|
|
79
|
-
const client = window.rtm.createClient({
|
|
80
|
-
protocol: 'tlv-v1',
|
|
81
|
-
pid: 12345,
|
|
82
|
-
tlvEndpoint: 'wss://<gate-host>/service/websocket',
|
|
83
|
-
});
|
|
84
|
-
// 后续仍使用现有 login、processor、promises API。
|
|
85
|
-
</script>
|
|
86
|
-
```
|
|
87
|
-
|
|
88
|
-
CommonJS 继续支持:
|
|
89
|
-
|
|
90
|
-
```js
|
|
91
|
-
const rtm = require('@cg-devcenter/rtc-fpnn-webjs-sdk');
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
Node 导入阶段不能访问不存在的浏览器全局或启动 Worker。Node 的 TLV 独立连接继续由调用方传入 `webSocketFactory`;FPNN 和共享连接的浏览器边界保持明确。
|
|
95
|
-
|
|
96
|
-
Vue 2 在 `mounted` 创建实例、在 `beforeDestroy` 释放;React 在 `useEffect` 创建实例并返回清理函数。包不需要 Vue/React 专属适配器。
|
|
97
|
-
|
|
98
|
-
```js
|
|
99
|
-
// Vue 2 生命周期示意
|
|
100
|
-
import { createClient } from '@cg-devcenter/rtc-fpnn-webjs-sdk';
|
|
101
|
-
|
|
102
|
-
export default {
|
|
103
|
-
mounted() {
|
|
104
|
-
this.rtmClient = createClient({ protocol: 'tlv-v1', pid, tlvEndpoint: endpoint, uid });
|
|
105
|
-
},
|
|
106
|
-
beforeDestroy() {
|
|
107
|
-
if (this.rtmClient) this.rtmClient.destroy();
|
|
108
|
-
},
|
|
109
|
-
};
|
|
110
|
-
```
|
|
111
|
-
|
|
112
|
-
```jsx
|
|
113
|
-
// React 生命周期示意
|
|
114
|
-
import { useEffect } from 'react';
|
|
115
|
-
import { createClient } from '@cg-devcenter/rtc-fpnn-webjs-sdk';
|
|
116
|
-
|
|
117
|
-
function useRtmClient({ pid, endpoint, uid }) {
|
|
118
|
-
useEffect(() => {
|
|
119
|
-
const client = createClient({ protocol: 'tlv-v1', pid, tlvEndpoint: endpoint, uid });
|
|
120
|
-
return () => client.destroy();
|
|
121
|
-
}, [pid, endpoint, uid]);
|
|
122
|
-
}
|
|
123
|
-
```
|
|
124
|
-
|
|
125
|
-
### 2.3 必须保留的行为
|
|
126
|
-
|
|
127
|
-
| 行为 | 改造约束 |
|
|
128
|
-
| --- | --- |
|
|
129
|
-
| `new RTMClient()` | 保留原有协议默认值、callback、Promise、事件与关闭语义 |
|
|
130
|
-
| `createClient()` | 默认 FPNN 以兼容旧 `RTMClient` 协议;SharedWorker API 可用时共享,浏览器不提供该 API 时自动使用独立连接;TLV 由调用方显式选择;Worker 资源或初始化失败时不静默降级 |
|
|
131
|
-
| `sharing: false` | 独立连接,不创建 Worker、不发起 Worker 网络请求 |
|
|
132
|
-
| `workerUrl` | 保留为显式覆盖项;优先于构建工具生成的默认地址 |
|
|
133
|
-
| UID 与环境隔离 | 沿用 PID、协议、UID、Gate endpoint 和现有名称规则 |
|
|
134
|
-
| `destroy()` | 共享模式只 detach 当前页;最后一页按既有闲置时间回收 |
|
|
135
|
-
| `bye()` / `close()` | 继续结束整个共享会话 |
|
|
136
|
-
| `/vite`、`/shared-worker`、`/dist/*` | 保留已公开路径;迁移期间不突然移除 |
|
|
137
|
-
| credential | 由后端签发;不新增持久化或跨构建入口的隐式保存 |
|
|
138
|
-
|
|
139
|
-
不同页面只有在浏览器配置文件、origin、实际 Worker URL 和共享身份配置一致时才共享连接。独立构建的两个站点即使包版本一致,也可能产生不同的资源 URL,不能直接承诺共享。
|
|
140
|
-
|
|
141
|
-
## 3. 实现方案
|
|
142
|
-
|
|
143
|
-
### 3.1 发布 ESM 与兼容入口
|
|
144
|
-
|
|
145
|
-
`scripts/build-modern.mjs` 从 SDK 实现构建 ESM,并从 `types/` 复制维护中的类型声明和插件入口。CommonJS 继续使用已有 UMD 文件,避免新增另一份运行时实现;普通浏览器也继续使用该 UMD。
|
|
146
|
-
|
|
147
|
-
产物职责如下:
|
|
148
|
-
|
|
149
|
-
| 产物 | 职责 |
|
|
150
|
-
| --- | --- |
|
|
151
|
-
| `dist/rtm.mjs` | 现代浏览器/构建工具的 ESM,支持默认与具名导出 |
|
|
152
|
-
| `dist/rtm.min.js` | UMD / CommonJS,继续提供 `window.rtm` 和 `require()` |
|
|
153
|
-
| `dist/rtm.shared-worker.js` | 完整、可独立执行的 classic SharedWorker;不依赖页面环境 |
|
|
154
|
-
| `dist/rtm.d.mts`、`dist/rtm.d.cts` | 分别描述 ESM 与 CommonJS 入口 |
|
|
155
|
-
| `dist/rtm.d.ts` | 由 `types/rtm.d.ts` 生成,保留普通 JS/旧解析方式需要的声明入口 |
|
|
156
|
-
| `dist/rtm.vite-plugin.mjs` | Vite 依赖预构建适配器 |
|
|
157
|
-
| `dist/rtm.webpack4-plugin.cjs`、`dist/rtm.webpack4-adapter.cjs` | Webpack 4 插件与 UMD 资源适配入口 |
|
|
158
|
-
| 兼容入口 | 保留 `/vite`、`/shared-worker` 和现有 `/dist/*` |
|
|
159
|
-
|
|
160
|
-
ESM 必须由源码构建,不能继续简单套用已压缩的 UMD。现有实现与依赖中有 CommonJS 和初始化副作用,首版不承诺完整 tree shaking,也不直接给包设置 `sideEffects: false`。
|
|
161
|
-
|
|
162
|
-
根 `exports` 的实际条件结构如下;其余公开子路径也保留在 `package.json`:
|
|
163
|
-
|
|
164
|
-
```json
|
|
165
|
-
{
|
|
166
|
-
"exports": {
|
|
167
|
-
".": {
|
|
168
|
-
"import": {
|
|
169
|
-
"types": "./dist/rtm.d.mts",
|
|
170
|
-
"default": "./dist/rtm.mjs"
|
|
171
|
-
},
|
|
172
|
-
"require": {
|
|
173
|
-
"types": "./dist/rtm.d.cts",
|
|
174
|
-
"default": "./dist/rtm.min.js"
|
|
175
|
-
}
|
|
176
|
-
}
|
|
177
|
-
}
|
|
178
|
-
}
|
|
179
|
-
```
|
|
180
|
-
|
|
181
|
-
`module` 指向 ESM,`main` 和 `browser` 保持指向 UMD,顶层 `types` 保留旧解析方式。Webpack 4 不通过 `module` 直接解析 ESM;使用 `/webpack4` 插件时,插件把包根 alias 到兼容适配器。
|
|
182
|
-
|
|
183
|
-
类型声明基于同一份公开 API 定义维护,检查默认导入、具名导入、`import = require()`、JS 全局命名空间及 `workerUrl` 覆盖。不要用 `skipLibCheck` 掩盖入口类型不匹配。
|
|
184
|
-
|
|
185
|
-
ESM 与 CommonJS 混用时可能出现两个模块实例;不能承诺跨格式 `instanceof` 恒成立。资源解析采用实例配置,避免新增必须共享的全局可变配置;已有 API 的模块状态要纳入回归。
|
|
186
|
-
|
|
187
|
-
### 3.2 Worker 地址由 SDK 与构建工具处理
|
|
188
|
-
|
|
189
|
-
优先复用完整的 `rtm.shared-worker.js`,把它作为构建资源交给消费工程;保留 Worker 内的协议、登录复用和 Push 分发实现。
|
|
190
|
-
|
|
191
|
-
实际 ESM 入口在包内使用相对模块 URL 解析完整 Worker 文件:
|
|
192
|
-
|
|
193
|
-
```js
|
|
194
|
-
function resolveDefaultWorkerUrl() {
|
|
195
|
-
return new URL('../dist/rtm.shared-worker.js', import.meta.url).href;
|
|
196
|
-
}
|
|
197
|
-
```
|
|
198
|
-
|
|
199
|
-
由入口在创建共享客户端时注入上述地址,优先采用业务显式传入的 `workerUrl`。独立连接和纯模块导入不执行 Worker 创建。解析逻辑集中维护,默认导出、具名导出与共享构造器都复用它。
|
|
200
|
-
|
|
201
|
-
选择独立 Worker 资源有两个好处:资源内容可以继续使用当前 standalone 构建;Worker 名称仍由 SDK 在运行时根据 UID 计算。
|
|
202
|
-
|
|
203
|
-
Vite 生产构建和 Webpack 5 会把相对模块 URL 输出为构建资源。Vite 6 开发模式若预构建 SDK,会把 `import.meta.url` 移入 `.vite/deps`,导致 Worker 解析错误;`/vite-plugin` 将包根与旧 `/vite` 子路径排除在依赖预构建之外,保留 Vite 对模块 URL 的处理。
|
|
204
|
-
|
|
205
|
-
现代入口失败时使用 SDK 配套构建插件完成资源输出与解析;不能退回让业务手写默认路径并仍宣称“零配置”。
|
|
206
|
-
|
|
207
|
-
### 3.3 Vite 兼容与预构建
|
|
208
|
-
|
|
209
|
-
直接从 npm registry 安装 `@cg-devcenter/rtc-fpnn-webjs-sdk@latest`(`1.0.0-cg.7`)后,在 Vite 6.4.4 的隔离消费工程对比验证了开发模式:不加 SDK 插件时,Vite 会把包根 ESM 预构建到 `node_modules/.vite/deps`,模块中的 `new URL('../dist/rtm.shared-worker.js', import.meta.url)` 因而解析到错误目录;加 `/vite-plugin` 后 SDK 保留在 Vite 转换链中,Worker URL 指向包内 `dist/rtm.shared-worker.js` 且请求返回 200。该 SDK 插件只调整 Vite 开发依赖预构建;生产构建中 Vite 根据 ESM 的静态 Worker URL 输出独立资源。Vue 3、Vue 2.7、React 三个 Demo 也都从 registry 安装该版本并通过生产构建,输出独立 Worker 资源。
|
|
210
|
-
|
|
211
|
-
Demo 已迁移到包根入口,并删除过去为 UMD 和 `?url` 设置的 `optimizeDeps.include/exclude`。插件会排除包根与旧 `/vite` 子路径;保留旧 `/vite` 作为迁移兼容入口。
|
|
212
|
-
|
|
213
|
-
新接入使用 `/vite-plugin` 配置一次,应用代码仍从包根导入。旧项目可继续使用 `/vite`;该入口仍使用原来的 `?url` 资源引用方式。
|
|
214
|
-
|
|
215
|
-
#### Vite 迁移步骤与放行条件
|
|
216
|
-
|
|
217
|
-
Vite 也使用通用包根入口,这是本次改造的明确目标。新项目不再把 `/vite` 作为推荐业务入口;旧 `/vite` 保留原有资源引用方式和默认、具名导出。
|
|
218
|
-
|
|
219
|
-
应用代码迁移示例:
|
|
220
|
-
|
|
221
|
-
```js
|
|
222
|
-
// 当前入口。
|
|
223
|
-
import rtm from '@cg-devcenter/rtc-fpnn-webjs-sdk/vite';
|
|
224
|
-
|
|
225
|
-
// 改造后默认导入;与现有 rtm.createClient() 调用兼容。
|
|
226
|
-
import rtm from '@cg-devcenter/rtc-fpnn-webjs-sdk';
|
|
227
|
-
|
|
228
|
-
// 或改用通用具名导入。
|
|
229
|
-
import { createClient } from '@cg-devcenter/rtc-fpnn-webjs-sdk';
|
|
230
|
-
```
|
|
231
|
-
|
|
232
|
-
以上三个导入展示迁移选择,不应放在同一个文件同时声明同名变量。
|
|
233
|
-
|
|
234
|
-
迁移按以下顺序验证:
|
|
235
|
-
|
|
236
|
-
1. 在独立 tarball 消费工程使用包根入口,移除 SDK 专属的 `optimizeDeps.include/exclude`、手动 Worker 路径和源码 alias;保留项目其他依赖需要的配置。
|
|
237
|
-
2. 测试无缓存冷启动和已预构建后的重启、源码 HMR、SDK 版本更新后的重新预构建,确认 Worker 请求地址、内容和版本对应。
|
|
238
|
-
3. 执行 production build 与 preview,在 `/`、`/app/` 和深层路由中验证自动资源加载;再验证同 UID 两页面一条 WebSocket、页面释放和显式 `workerUrl` 覆盖。
|
|
239
|
-
4. Vite 6.4.4 dev 下根入口与旧 `/vite` 都解析到同一 Worker 文件;生产混用构建只输出一个 Worker 资源。还需在正式浏览器里验证混用入口后确实复用同一连接。
|
|
240
|
-
5. 仓库 Vite Demo 的两处 SDK 导入(`src/state/demo.js`、`src/lib/rtc.js`)已迁移,SDK 专属的 `optimizeDeps.include/exclude` 已删除,Demo README 和接入指南已更新。yalc 仅用于仓库本地迭代,不是 npm 消费要求。
|
|
241
|
-
|
|
242
|
-
完成后按锁定的 Vite 版本记录结果:
|
|
243
|
-
|
|
244
|
-
| 实测结果 | 最终接入要求 | 对外描述 |
|
|
245
|
-
| --- | --- | --- |
|
|
246
|
-
| 上述流程无需额外 SDK 配置即可通过 | 包根导入即可 | 该版本支持零额外配置 |
|
|
247
|
-
| 需要预构建或资源适配,配套插件可使全部流程通过 | 包根导入 + 一次插件配置;SDK 特殊处理由插件维护 | 该版本需要配套插件 |
|
|
248
|
-
| 仅 build 通过、开发失败,或 Worker/共享行为仍有问题 | 继续修复;已验证的旧入口仍按原用法使用 | 通用入口尚未验收,不宣布迁移完成 |
|
|
249
|
-
|
|
250
|
-
Vite 6.4.4 的开发预构建需要插件,所以本实现不宣称 Vite 零额外配置。已验证根入口 + 插件的 dev 模块解析和 production build;preview、冷缓存重启、HMR、深层路由和浏览器中的实际 Worker 启动仍需在消费工程完成。
|
|
251
|
-
|
|
252
|
-
### 3.4 Webpack 5 与 Webpack 4
|
|
253
|
-
|
|
254
|
-
Webpack 5 使用标准 ESM 相对资源 URL。已用独立安装的 tarball 在 Webpack 5.111.1 production 工程验证编译,并看到完整 SharedWorker 文件输出为独立资源;仍需补 dev server、子目录部署和浏览器运行验证。
|
|
255
|
-
|
|
256
|
-
Webpack 4 不按现代 `import.meta.url` 能力设计。`/webpack4` 插件负责:
|
|
257
|
-
|
|
258
|
-
1. 从已安装 SDK 包读取与主入口匹配的 Worker 文件,开发时可访问,生产时输出到 assets。
|
|
259
|
-
2. 用兼容 Webpack 4 的适配入口注入构建生成的文件名和应用资源前缀,不使用 ESM 专用语法。
|
|
260
|
-
3. 只重定向需要适配的 SDK 包根入口;防止适配入口再引用自己造成循环解析。
|
|
261
|
-
4. 默认导入、具名导入和共享构造器都走一致的资源解析。
|
|
262
|
-
5. watch/HMR 重建时更新资源;主包与 Worker 版本一起变化。
|
|
263
|
-
|
|
264
|
-
插件通过 `resolve.alias` 重定向包根,因此不需要独立 `webpack.js` 运行入口。插件只用 Node 内置模块,导入配置时不要求 SDK 运行依赖,也不把 Webpack 构建依赖带进浏览器运行包。已用 Webpack 4.47.0 编译最小消费入口,检查 Worker 输出和 `/static/` publicPath。
|
|
265
|
-
|
|
266
|
-
Webpack 4 的配置写法:
|
|
267
|
-
|
|
268
|
-
```js
|
|
269
|
-
const RTMSDKWebpack4Plugin = require('@cg-devcenter/rtc-fpnn-webjs-sdk/webpack4');
|
|
270
|
-
|
|
271
|
-
module.exports = {
|
|
272
|
-
plugins: [new RTMSDKWebpack4Plugin()],
|
|
273
|
-
};
|
|
274
|
-
```
|
|
275
|
-
|
|
276
|
-
不通过 npm 安装脚本向业务的 `public/` 写文件。Worker 应作为构建产物由插件管理,SDK 更新后随业务重建与部署更新。
|
|
277
|
-
|
|
278
|
-
### 3.5 部署与错误处理
|
|
279
|
-
|
|
280
|
-
Worker 必须最终在页面同源地址提供,并被站点 CSP 允许。资源前缀为跨域 CDN 时不能假定 SharedWorker 可以直接加载;需要应用同源资源路由或显式覆盖部署路径,并给出明确诊断。
|
|
281
|
-
|
|
282
|
-
主脚本和 Worker 原子部署,版本变化产生对应资源更新。普通 HTML 保留原文件名;npm 构建可以使用内容 hash。新旧页面同时存活的情况下,明确共享边界,不强行合并不同版本的会话。
|
|
283
|
-
|
|
284
|
-
同一应用的包根入口与兼容 `/vite` 入口应解析到相同 Worker URL;避免导入路径不同造成两条连接。普通 HTML 与打包页面混用时,也必须以实际 URL 一致为前提。
|
|
285
|
-
|
|
286
|
-
不使用每个页面独立创建的 Blob URL 作为默认共享资源地址。各页面资源 URL 不一致会破坏当前按 URL 复用的会话前提。
|
|
287
|
-
|
|
288
|
-
SharedWorker API 不可用时,`createClient()` 自动使用独立连接;Worker 404、错误 MIME、初始化超时等资源或初始化错误继续通过 SDK 错误通道报告。错误信息包含可定位的阶段与资源地址,不包含 credential。
|
|
289
|
-
|
|
290
|
-
## 4. 实施顺序与涉及文件
|
|
291
|
-
|
|
292
|
-
| 阶段 | 工作 | 涉及位置 | 通过条件 |
|
|
293
|
-
| --- | --- | --- | --- |
|
|
294
|
-
| P0:可行性验证 | 验证 ESM Worker URL 在 Vite / Webpack 构建中的行为 | 本地 Vite Demo、安装的候选 tarball、Webpack 消费工程 | 已通过 Vite 6.4.4 dev/build、Webpack 5.111.1 production、Webpack 4.47.0 + Vue 2.7 production build;普通 HTML 在浏览器内创建客户端并观察到同目录 Worker 请求 |
|
|
295
|
-
| P1:发布格式 | 生成 ESM、保留 UMD/CJS、类型声明和条件导出 | `src/rtm.esm.mjs`、`scripts/build-modern.mjs`、`package.json`、`dist/` | 已通过构建、包根 ESM/CJS、自包含 tarball 安装和 NodeNext 类型检查 |
|
|
296
|
-
| P2:Worker 适配 | 提供实例级默认 Worker 地址、Vite 插件、Webpack 4 插件与旧入口兼容 | `src/plugins/`、`src/rtm.esm.mjs`、类型与构建文件 | 已覆盖默认 Worker URL、显式 `workerUrl`、`sharing: false` 和 Webpack 4 Worker 资源输出;不同入口之间的真实连接共享仍待浏览器验证 |
|
|
297
|
-
| P3:消费验证 | 验证安装包和 Vite/Webpack 消费构建 | `test/package-*`、Vue 3 Vite Demo、Vue 2 Webpack 4 与 React Vite 消费工程 | 本地 tarball、Vue 3/React Vite 与 Vue 2/Webpack 4 构建、Worker URL 资源请求已覆盖;框架生命周期、base 深层路由、preview 和真实 Gate 待验证 |
|
|
298
|
-
| P4:文档和发布 | 更新用法、Demo、验收记录;发布候选包并从 registry 复测 | README、`docs/USAGE.md`、Demo、发布记录 | 文档和 Demo 已更新;registry 发布、业务试接入与回退记录未执行 |
|
|
299
|
-
|
|
300
|
-
不宣称 Vite 或 Webpack 5 零配置:Vite 需 `/vite-plugin`,Webpack 4 需 `/webpack4`,Webpack 5 最小 production build 无 SDK 插件。未完成的浏览器、真实 Gate 和 registry 关卡仍按下方清单继续。
|
|
301
|
-
|
|
302
|
-
生成文件由构建脚本生成,不直接修改 `dist/` 来实现方案。公开类型声明以 `types/` 为维护源,构建会复制到 `dist/`;包构建仍由现有 Webpack 4 产出 UMD 与 Worker,并由 esbuild 构建 ESM;消费工程工具版本彼此独立。
|
|
303
|
-
|
|
304
|
-
## 5. 怎么验证
|
|
305
|
-
|
|
306
|
-
### 5.1 验证实际分发包
|
|
307
|
-
|
|
308
|
-
最终证据来自安装包。工作区相对导入、alias 到源码或 yalc 只能用于迭代,不能替代分发验证。
|
|
309
|
-
|
|
310
|
-
现有命令可先用于源码与包行为回归:
|
|
311
|
-
|
|
312
|
-
```bash
|
|
313
|
-
npm ci
|
|
314
|
-
npm run test:unit
|
|
315
|
-
npm run test:package
|
|
316
|
-
```
|
|
317
|
-
|
|
318
|
-
制作候选 tarball 时:
|
|
319
|
-
|
|
320
|
-
```bash
|
|
321
|
-
npm pack --json
|
|
322
|
-
```
|
|
323
|
-
|
|
324
|
-
当前 `prepack` 会执行构建。记录 JSON 返回的 tarball 文件名、包版本与 integrity,在仓库外的干净消费工程安装该绝对路径:
|
|
325
|
-
|
|
326
|
-
```bash
|
|
327
|
-
npm install /absolute/path/to/candidate-sdk.tgz
|
|
328
|
-
```
|
|
329
|
-
|
|
330
|
-
消费工程必须从包根/公开子路径导入,关闭源码 alias,不依赖 SDK 仓库的 `node_modules`。锁文件与环境版本保存到验证记录。
|
|
331
|
-
|
|
332
|
-
`npm run test:package` 会构建、执行 `npm pack --dry-run` 文件审计、创建并安装本地 tarball,再从安装目录执行 ESM/CJS/插件导入和 ESM/CJS NodeNext 类型检查。它还运行 UMD 行为回归、根入口 ESM、Webpack 4 插件 smoke test。
|
|
333
|
-
|
|
334
|
-
### 5.2 首批支持矩阵与当前结果
|
|
335
|
-
|
|
336
|
-
以下记录的是本次本地实现验证。通过最小构建不等于已经支持该框架的所有生命周期、部署目录或浏览器组合。
|
|
337
|
-
|
|
338
|
-
| 编号 | 消费环境 | 当前状态与证据 | 尚未覆盖 |
|
|
339
|
-
| --- | --- | --- | --- |
|
|
340
|
-
| H1 | 普通 HTML + 浏览器 | `PARTIAL`:加载 UMD 并创建共享客户端后,浏览器实际请求同目录 `/sdk/rtm.shared-worker.js`;自动 URL 解析已观察 | 真实 Gate 登录/多窗口复用及完整 HTML Demo 业务链路 |
|
|
341
|
-
| N1 | Node CommonJS | `PASS`:无 `window` 时从包根 `require()`,现有包 smoke 测试通过 | 对真实 Gate 的 Node WebSocket 链路 |
|
|
342
|
-
| N2 | Node ESM / SSR 导入 | `PASS`:包根默认/具名导入,在无 `window` 和 `SharedWorker` 下导入成功 | SSR 框架服务端请求周期和 socket 注入场景 |
|
|
343
|
-
| V1 | Vue 3 + Vite 6.4.4 | `PARTIAL`:registry `1.0.0-cg.7` 安装后 production build 输出带 hash 的 Worker;独立 Vite dev 对照确认 SDK 插件修正 Worker URL;此前 yalc 本地开发包的 preview 和本机 credential 状态 API 验收为历史记录 | registry 包的 HMR、深层路由和实际登录/连接复用 |
|
|
344
|
-
| V2 | React 18 + Vite 6.4.4 | `PARTIAL`:registry `1.0.0-cg.7` 安装后 production build 输出带 hash 的 Worker;此前 yalc 本地开发包的 dev、preview 页面和本机 credential 状态 API 验收为历史记录 | registry 包的 effect 清理、开发模式重复挂载和实际登录/连接复用 |
|
|
345
|
-
| V3 | Vue 2.7.16 + Vite 6.4.4 | `PARTIAL`:registry `1.0.0-cg.7` 安装后 production build 输出带 hash 的 Worker;使用官方 Vue 2 Vite 插件;此前 yalc 本地开发包的 preview 和本机 credential 状态 API 验收为历史记录 | registry 包的组件卸载、开发模式与实际登录/连接复用 |
|
|
346
|
-
| W5 | Webpack 5.111.1 最小工程 | `PARTIAL`:独立安装的 npm tarball production 编译成功,输出完整 Worker 资源并设置 `/static/` publicPath | dev server、浏览器请求、子目录部署和 React 生命周期 |
|
|
347
|
-
| W4 | Vue 2.7.16 + Webpack 4.47.0 | `PARTIAL`:yalc 包配合 `vue-loader` 15 production build 成功;`/webpack4` 插件输出 Worker,bundle 解析为 `/static/rtm.shared-worker.js` | Vue CLI 4 dev/watch、浏览器实际启动/连接与组件卸载生命周期 |
|
|
348
|
-
| R5 | React + CRA 5 / Webpack 5 | `NOT_RUN` | CRA 未 eject 的 dev/build 和 effect 清理 |
|
|
349
|
-
| T1 | TypeScript 消费工程 | `PASS`:工作区与安装 tarball 都通过 NodeNext ESM/CJS 声明检查 | `moduleResolution: bundler` 和旧式 TS 解析 |
|
|
350
|
-
|
|
351
|
-
若项目实际使用其他版本,新增锁定版本的矩阵行后才声明支持。不能从 Webpack 5 最小工程通过推导所有 CRA 版本通过,也不能从 Vue 3 推导所有 Vue 2 工程通过。上文标注 yalc 的浏览器和 preview 结果是此前对工作区改动的历史验收;本轮三个 Vite Demo 使用 registry 发布包 `1.0.0-cg.7` 做了生产构建,隔离消费工程用 registry 包做了 Vite dev 插件对照。以上消费工程都没有访问真实 Gate。
|
|
352
|
-
|
|
353
|
-
每个浏览器消费工程至少测试 `/` 和 `/app/` 子目录部署,以及深层业务路由进入/刷新。ESM npm 接入不应增加 `window.rtm` 依赖。
|
|
354
|
-
|
|
355
|
-
### 5.3 Browser / Worker 行为验收
|
|
356
|
-
|
|
357
|
-
资源加载用例先使用可控测试端验证 Worker 握手和消息路由;再使用专用真实 Gate 环境跑端到端链路。断言浏览器中的实际资源与连接行为:
|
|
358
|
-
|
|
359
|
-
| 用例 | 操作 | 通过标准 |
|
|
360
|
-
| --- | --- | --- |
|
|
361
|
-
| B1 自动资源 | 根入口创建共享客户端 | Worker 请求 200、JS MIME 正确、无业务 `workerUrl`、无手动复制文件 |
|
|
362
|
-
| B2 共享登录 | 同源两个页面使用相同配置与 UID;A 首次登录,B 不传 credential | 同一个 Worker、一条 Gate WebSocket;B 复用登录,收到订阅 Push |
|
|
363
|
-
| B3 并发登录 | 两个页面同时登录同一 UID | Worker 内只发起一次同 UID 鉴权,两个调用正确结束 |
|
|
364
|
-
| B4 身份隔离 | 分别更换 UID、PID、协议或 endpoint | 按既有规则隔离;同身份的其他参数冲突明确失败 |
|
|
365
|
-
| B5 生命周期 | 销毁 A,B 发消息;最后销毁 B | B 继续可用;最后一页默认 5 秒后回收;宽限期内接入可取消回收 |
|
|
366
|
-
| B6 协议关闭 | 一个页面执行 `bye()` / `close()` | 所有共享页面观察到会话关闭;未完成请求正确结束 |
|
|
367
|
-
| B7 独立连接 | `sharing: false` / 普通 `RTMClient` | 不创建、不加载 Worker;独立登录与消息正常 |
|
|
368
|
-
| B8 入口一致 | 同一构建同时使用默认/具名导入、共享构造器、兼容 `/vite` | 解析一致的 Worker 地址;按相同身份共享连接 |
|
|
369
|
-
| B9 显式覆盖 | 给上述入口传入有效、同源的自定义 `workerUrl` | 都采用覆盖地址;默认资源不会另开会话 |
|
|
370
|
-
| B10 SharedWorker 不可用 | 移除 SharedWorker API 后用 `createClient()` 创建连接 | 自动使用独立 RTMClient;协议、登录、Push 和业务 API 可用,不声称多页共享 |
|
|
371
|
-
| B11 资源错误诊断 | Worker 404、错误 MIME、初始化超时 | 能定位原因;资源/初始化错误不静默降级;无挂起 Promise |
|
|
372
|
-
| B12 升级资源 | 构建不同版本并刷新页面 | Worker 与主包版本对应,无旧资源误配;记录旧页面仍存活的边界 |
|
|
373
|
-
| B13 框架卸载 | credential 获取中卸载、登录中卸载、切 UID、React 重复挂载 | 已销毁实例不再被使用,无泄漏监听器或未处理 rejection |
|
|
374
|
-
|
|
375
|
-
跨域 CDN 和 CSP 属于部署专项验证:不允许的部署应产生清楚的诊断;允许的同源资源路由应能恢复正常。不同 Worker URL 的页面不能被误计为共享成功。
|
|
376
|
-
|
|
377
|
-
当前 ESM smoke test 使用 mock `SharedWorker` 验证默认 URL、显式覆盖、独立连接不启动 Worker 和底层共享构造器注入;它不证明真实浏览器的请求和连接复用。连接复用证据仍需来自浏览器 Worker/Network 或测试 Gate 的连接与鉴权计数。UI 显示“已登录”或 Demo 的 BroadcastChannel 本地模拟不能证明 WebSocket 复用。
|
|
378
|
-
|
|
379
|
-
### 5.4 真实 Gate 验收
|
|
380
|
-
|
|
381
|
-
参考 [在线验证说明](TLV_LIVE_E2E_TEST.md) 准备 PID、endpoint、两个专用 UID 和后端签发的 credential。
|
|
382
|
-
|
|
383
|
-
按以下顺序执行:首次登录 → 同 UID 第二页无 credential 复用 → 发送私聊 → 接收 Push → 销毁第一页 → 第二页继续收发 → 所有页面退出并确认回收。TLV 为新入口主验收协议,FPNN 用现有共享流程补回归。
|
|
384
|
-
|
|
385
|
-
真实链路中记录发送回执、接收 message_ref、连接数量、关闭结果和可复现步骤。凭证获取失败、网络不可达等情况标为阻塞;不得当作通过。协议能力项的可选跳过规则沿用现有在线测试文档。
|
|
386
|
-
|
|
387
|
-
## 6. 从实现到发布如何闭环
|
|
388
|
-
|
|
389
|
-
```mermaid
|
|
390
|
-
flowchart TD
|
|
391
|
-
A[确认支持矩阵和旧入口基线] --> B[候选入口与 Worker 可行性验证]
|
|
392
|
-
B --> C[实施构建与资源适配]
|
|
393
|
-
C --> D[源码回归和 npm tarball 安装]
|
|
394
|
-
D --> E[开发和生产消费矩阵]
|
|
395
|
-
E --> F[真实 Gate 多窗口验收]
|
|
396
|
-
F --> G[发布 latest]
|
|
397
|
-
G --> H[从 registry 干净安装并复测]
|
|
398
|
-
H --> I[业务试接入]
|
|
399
|
-
I --> J[记录结果及回退信息]
|
|
400
|
-
E -->|失败| C
|
|
401
|
-
F -->|SDK 问题| C
|
|
402
|
-
H -->|失败| C
|
|
403
|
-
```
|
|
404
|
-
|
|
405
|
-
| 关卡 | 交付物 | 谁负责 | 放行条件 |
|
|
406
|
-
| --- | --- | --- | --- |
|
|
407
|
-
| G0 范围确认 | 消费工程版本、旧入口 API 清单、资源方案选型记录 | SDK 维护者;业务接入者提供实际构建版本 | `PASS`:Vite 需要插件、Webpack 4 需要插件、Webpack 5 最小 production build 不需要 SDK 插件 |
|
|
408
|
-
| G1 本地候选包 | 构建、tarball 文件审计和安装 smoke test | 实施者 | `PASS`:`npm test` 中的本地源代码与 tarball 检查通过 |
|
|
409
|
-
| G2 消费工程 | dev/build/运行日志、浏览器记录、类型检查结果 | 实施者/测试 | `PARTIAL`:Vue 3、Vue 2.7、React + Vite,Vue 2 + Webpack 4 的本地消费构建通过;普通 HTML 浏览器已观察到自动 Worker 请求。此次新增框架 Demo 共用同一状态模型和 RTC 运行时适配层;三种框架的 production preview 页面和 credential 状态 API 均通过,三个框架的四窗口本地模拟也完成。框架运行生命周期、子目录/深层路由及真实 Gate 仍待测 |
|
|
410
|
-
| G3 真实业务链路 | Gate 环境标识、UID、连接/鉴权计数、消息与关闭记录 | 测试/联调人员 | `NOT_RUN`:本次没有使用真实 Gate 凭证 |
|
|
411
|
-
| G4 npm 发布 | registry、`latest` tag 和 integrity | 有发布权限的维护者 | `PASS`:registry `latest` 为 `1.0.0-cg.7`;三个 Vite Demo 均从 registry 安装并构建成功,lockfile 指向 npm tarball。registry integrity 与 npm `pack --dry-run` 已核对 |
|
|
412
|
-
| G5 业务验收 | 现代项目与目标旧项目结果、回退版本 | 业务接入者 + SDK 维护者 | `NOT_RUN` |
|
|
413
|
-
|
|
414
|
-
### 6.1 发布 latest 与线上安装复测
|
|
415
|
-
|
|
416
|
-
先确认实际 registry、当前 `latest` 指向和版本号策略;仓库构建本身不代表 npm 已发布。
|
|
417
|
-
|
|
418
|
-
发布一个新的包版本,并直接使用 `latest` 标签。项目不使用 `next` 等预发布 dist-tag;发布操作由有权限的维护者执行。
|
|
419
|
-
|
|
420
|
-
发布后在干净消费工程安装 `@cg-devcenter/rtc-fpnn-webjs-sdk@latest`,确认没有 yalc、源码 alias 或本地 tarball 残留。对比 registry integrity 与准备发布的包;若发布流程重新构建导致内容变化,应对实际发布包重新执行关卡 G1—G3,不能复用旧包的通过记录。
|
|
421
|
-
|
|
422
|
-
只有 registry 安装和入口 smoke check 通过后,才把该版本作为可接入版本对外说明。生产业务工程可通过锁文件固定已验收的依赖,避免自动升级干扰发布。
|
|
423
|
-
|
|
424
|
-
### 6.2 回退
|
|
425
|
-
|
|
426
|
-
更新标签前记录上一稳定版本、registry integrity 和已部署业务版本。出现旧入口回归、Worker 无法加载、共享连接被拆成多条或主包/Worker 版本错配时停止推广。
|
|
427
|
-
|
|
428
|
-
回退操作包括:将 `latest` 恢复到上一稳定版本;受影响业务恢复 SDK 精确版本与锁文件并重新构建;主脚本和 Worker 一起回退部署。单独回退 npm 标签不会自动改变已经安装或已经部署的应用。
|
|
429
|
-
|
|
430
|
-
旧页面可能仍持有新版本 Worker,需要刷新或按既有 detach/回收流程释放。不得通过删除发布包或强行跨版本合并会话来代替回退。
|
|
431
|
-
|
|
432
|
-
### 6.3 验收记录模板
|
|
433
|
-
|
|
434
|
-
在后续消费或发布验收时填写以下字段,状态使用 `PASS`、`PARTIAL`、`FAIL`、`BLOCKED`、`NOT_RUN`:
|
|
435
|
-
|
|
436
|
-
```text
|
|
437
|
-
源码 commit:
|
|
438
|
-
SDK 精确版本 / registry / tag:
|
|
439
|
-
tarball 文件 / integrity:
|
|
440
|
-
Node / npm / 浏览器版本:
|
|
441
|
-
消费工程 / 构建工具与完整版本 / 锁文件:
|
|
442
|
-
入口(根 ESM、CJS、UMD、旧 /vite):
|
|
443
|
-
构建配置(零额外配置或具体插件):
|
|
444
|
-
部署 origin / base / publicPath / 实际 Worker URL:
|
|
445
|
-
源码与分发检查状态:
|
|
446
|
-
开发 / 生产 / 类型检查矩阵状态:
|
|
447
|
-
真实 Gate 链路与多窗口连接计数:
|
|
448
|
-
失败复现 / 修复 commit / 对应重测证据:
|
|
449
|
-
上一稳定版本 / 回退操作记录:
|
|
450
|
-
业务试接入结论 / 验收人 / 日期:
|
|
451
|
-
```
|
|
452
|
-
|
|
453
|
-
任何必选项仍为 `FAIL`、`BLOCKED` 或 `NOT_RUN`,都不能写“整体完成”。验证失败后要覆盖同源的所有入口与变体,例如默认导入、具名导入、共享构造器和旧 `/vite`,并为实际缺陷补能复现问题的回归用例。
|
|
454
|
-
|
|
455
|
-
## 7. 参考依据与当前进度
|
|
456
|
-
|
|
457
|
-
以下官方文档说明构建能力和解析规则;它们不替代本 SDK 安装包在锁定版本下的实测:
|
|
458
|
-
|
|
459
|
-
- [Vite:Worker 构造器与静态选项要求](https://vite.dev/guide/features.html#web-workers)。
|
|
460
|
-
- [Vite:相对模块 URL 与资源处理](https://vite.dev/guide/assets.html#new-url-url-import-meta-url)。
|
|
461
|
-
- [Webpack 5:URL 资源自动输出](https://webpack.js.org/guides/asset-modules/#url-assets)。
|
|
462
|
-
- [Webpack:Worker 语法和静态分析限制](https://webpack.js.org/guides/web-workers/)。
|
|
463
|
-
- [Node:条件导出与双格式包](https://nodejs.org/api/packages.html#conditional-exports)。
|
|
464
|
-
|
|
465
|
-
本地实现与回归结果(2026-10-13):
|
|
466
|
-
|
|
467
|
-
- `npm test` 通过,包含协议、文档、Demo、UMD/CJS、ESM、tarball 导入、Webpack 4 插件与 NodeNext 类型检查。
|
|
468
|
-
- npm tarball 文件审计通过;安装到临时消费工程后,包根 ESM/CJS、Vite 插件、Webpack 4 插件及 ESM/CJS 类型导入通过。
|
|
469
|
-
- `1.0.0-cg.8` 本地 tarball 文件清单与内容已审计;未发现凭证、私钥、环境文件或开发机绝对路径。该检查不代表 npm 发布。
|
|
470
|
-
- 此前 Vue 3、Vue 2.7.16、React 18 Demo 的浏览器、preview 和四窗口 BroadcastChannel 模拟均通过,但当时使用 yalc 工作区包,属于本地改动验收。当前 npm `latest`(`1.0.0-cg.7`)已安装到三个 Vite Demo,Vue 3、Vue 2、React production build 均通过并输出独立 Worker;Vite 6.4.4 隔离 dev 对照实证不加 SDK 插件会把 Worker URL 指向错误目录,加 `/vite-plugin` 后 Worker 请求返回 200。Vue 2.7 + Webpack 4.47.0 yalc 消费工程 production build 通过并输出 Worker;Webpack 5.111.1 使用安装的 tarball 完成 production build。
|
|
471
|
-
- 普通 HTML 在浏览器中创建共享客户端后观察到同目录 Worker 请求。框架组件卸载、多窗口 RTC 连接复用、子目录/深层路由和真实 Gate 仍未验收。
|
|
472
|
-
|
|
473
|
-
本地验证环境为 Node 20.20.1、npm 10.8.2、TypeScript 5.8.3。
|
|
474
|
-
|
|
475
|
-
当前 registry `latest`(`1.0.0-cg.7`)已发布现代包入口;此前用该 registry 包完成三个框架 Demo 的生产构建,`npm pack --dry-run` 仅核对当时的文件清单。本轮工作区 `1.0.0-cg.8` 则对实际 `.tgz` 文件清单与内容做了审计。以上都不代表已完成真实 Gate 或多窗口 RTC 验收,也不代表 `cg.8` 已发布。开发接入示例与限制见 [USAGE.md](USAGE.md);四个 Demo 的源码仓库专用说明位于 `examples/README.md`。
|
|
@@ -1,115 +0,0 @@
|
|
|
1
|
-
# TLV v1 在线验证页面
|
|
2
|
-
|
|
3
|
-
验证页面位于 `test/e2e/live-tlv-suite.html`。它用于验证一个真实 TLV Gate 环境与 SDK 的联调结果,不替代本地协议测试或 npm 包 smoke test。页面只接受运行时输入,不内置环境参数、项目密钥或 credential。
|
|
4
|
-
|
|
5
|
-
## 前置条件
|
|
6
|
-
|
|
7
|
-
- 能访问目标 TLV WebSocket endpoint,并准备好对应的 RTC `pid`。
|
|
8
|
-
- 准备两个不同的、正整数 UID,以及服务端签发给这两个 UID 的有效 credential。
|
|
9
|
-
- 如需验证群组流程,准备一个已存在且 UID A 有成员管理权限的 Group ID。
|
|
10
|
-
- 如需把黑名单、文本审核和翻译作为强制能力验证,勾选页面上的“要求黑名单、文本审核和翻译能力通过”。
|
|
11
|
-
- 浏览器需要支持 WebSocket、`TextEncoder` 和 `TextDecoder`。
|
|
12
|
-
|
|
13
|
-
credential 应从服务端鉴权流程取得,不要把项目密钥放进浏览器页面、URL 或 `requestMetadata`。
|
|
14
|
-
|
|
15
|
-
## 启动页面
|
|
16
|
-
|
|
17
|
-
页面通过相对路径加载仓库内的 `dist/rtm.min.js`,所以应从仓库根目录启动 HTTP 服务,不能直接使用 `file://` 打开:
|
|
18
|
-
|
|
19
|
-
```bash
|
|
20
|
-
cd ~/Documents/code/origin/rtm-client-sdk-websocket
|
|
21
|
-
|
|
22
|
-
# 只有在 dist 需要由当前源码重新生成时才执行;依赖未安装时先执行 npm install
|
|
23
|
-
npm install
|
|
24
|
-
npm run build
|
|
25
|
-
|
|
26
|
-
python3 -m http.server 8000
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
然后打开:
|
|
30
|
-
|
|
31
|
-
```text
|
|
32
|
-
http://127.0.0.1:8000/test/e2e/live-tlv-suite.html
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
如果只是验证仓库当前已提交的 `dist`,可以跳过 `npm install` 和 `npm run build`,直接启动 HTTP 服务。若页面提示 `rtm` 未定义或脚本加载失败,先确认服务根目录是本仓库,而不是 `test/e2e` 目录。
|
|
36
|
-
|
|
37
|
-
## 执行顺序
|
|
38
|
-
|
|
39
|
-
推荐先执行仓库内的本地检查,再执行在线页面:
|
|
40
|
-
|
|
41
|
-
```bash
|
|
42
|
-
npm run test:unit # TLV 协议与文档链接/覆盖检查
|
|
43
|
-
npm run test:package # 重新构建 dist,并验证 CommonJS 与浏览器 UMD 包入口
|
|
44
|
-
npm test # 以上两组检查的合并入口
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
在线页面按以下顺序运行:
|
|
48
|
-
|
|
49
|
-
1. 点击“运行无凭证 `control.ping`”,确认 WebSocket、TLV frame header、Answer sequence,以及请求空 map 和应答 `{}` / `{ts}` 均正确。
|
|
50
|
-
2. 填写 endpoint、pid、两个 UID 和 credential,点击“运行业务覆盖套件”。
|
|
51
|
-
3. 页面先执行两个 `auth.login`,再执行系统、用户、存储、黑名单、群组、房间、消息、历史、未读、会话、重连和关闭流程。
|
|
52
|
-
4. 页面会清理本次运行写入的存储、黑名单、房间和群成员状态;仍建议使用专用测试账号和测试群组。
|
|
53
|
-
|
|
54
|
-
## 输入
|
|
55
|
-
|
|
56
|
-
| 字段 | 类型 | 必填 | 说明 |
|
|
57
|
-
| --- | --- | --- | --- |
|
|
58
|
-
| `endpoint` | `string` | 是 | TLV WebSocket URL。 |
|
|
59
|
-
| `pid` | `number` | 是 | RTC 项目 ID。 |
|
|
60
|
-
| `uidA` / `credentialA` | `string` | 是 | 第一个 Client 身份;UID 必须是正整数。 |
|
|
61
|
-
| `uidB` / `credentialB` | `string` | 是 | 第二个 Client 身份;必须与 A 不同。 |
|
|
62
|
-
| `groupId` | `string` | 否 | 已配置的群组 ID;填写时 UID A 必须有相应权限。 |
|
|
63
|
-
| `requireCapabilities` | `boolean` | 否 | 要求黑名单、审核、翻译 API 通过;未勾选时这些外部能力可以 `SKIP`。 |
|
|
64
|
-
|
|
65
|
-
## 覆盖范围
|
|
66
|
-
|
|
67
|
-
| 阶段 | 动作 | 协议/API 范围 |
|
|
68
|
-
| --- | --- | --- |
|
|
69
|
-
| P0 | `control.ping` | 无凭证 TLV frame、Answer sequence、请求空 map 和应答 `{}` / `{ts}`。 |
|
|
70
|
-
| A1 | 登录与连接 | `auth.login`、连接属性、`system.time`、自动重连与 `connection.close`。 |
|
|
71
|
-
| U1/B1 | 用户与基础数据 | 在线状态、用户资料、公开资料、语言、存储和黑名单。 |
|
|
72
|
-
| G1/R1 | 群组与房间 | 群组成员/资料/计数、房间加入/退出/成员/资料。配置缺失时群组流程会跳过。 |
|
|
73
|
-
| M1/M2 | 消息与 Push | 单发、批量、群组/房间消息、`event.direct`/`event.group`/`event.room`、ACK 与去重。 |
|
|
74
|
-
| H1/H2/S1 | 读取与会话 | 历史消息、计数、撤回、未读、Session 和 Conversation。 |
|
|
75
|
-
| X1/N1 | 能力与负向契约 | 黑名单能力、文本审核、翻译,以及保留 friend wire 的 `200020` 拒绝。 |
|
|
76
|
-
|
|
77
|
-
可靠 Push 会自动回复 `control.ack`;套件还会检查同一 `message_ref` 不被重复投递。页面使用带时间戳的 marker 写入测试数据,便于从结果中定位本次运行。
|
|
78
|
-
|
|
79
|
-
## 结果判定
|
|
80
|
-
|
|
81
|
-
| 状态 | 含义 |
|
|
82
|
-
| --- | --- |
|
|
83
|
-
| `PASS` | 接口返回、响应字段和协议校验符合契约。 |
|
|
84
|
-
| `FAIL` | 接口调用、响应、Push、协议或超时校验不符合预期;应先看该行错误码和浏览器控制台。 |
|
|
85
|
-
| `SKIP` | 可选群组未配置,或未勾选强制能力时服务没有开放相应外部能力。 |
|
|
86
|
-
|
|
87
|
-
未勾选强制能力时,页面允许以下环境差异产生 `SKIP`:
|
|
88
|
-
|
|
89
|
-
- 黑名单:`200060`。
|
|
90
|
-
- 文本审核或翻译:`200020` 或 `300001`。
|
|
91
|
-
- 未填写 `groupId` 时,群组相关覆盖也会明确标记为 `SKIP`。
|
|
92
|
-
|
|
93
|
-
勾选强制能力后,上述错误会变成 `FAIL`,用于验证目标环境是否真的提供这些能力。`N1 reserved friend wire` 预期收到 `200020`,它是负向协议检查,不是故障。
|
|
94
|
-
|
|
95
|
-
## 排障路径
|
|
96
|
-
|
|
97
|
-
| 现象 | 优先检查 |
|
|
98
|
-
| --- | --- |
|
|
99
|
-
| 页面空白、`rtm` 未定义或脚本 404 | 是否从仓库根目录运行 HTTP 服务;`dist/rtm.min.js` 是否存在;源码有改动时是否重新执行 `npm run build`。 |
|
|
100
|
-
| WebSocket error、`control.ping` 失败或超时 | endpoint 的 scheme/路径、TLS 或反向代理、浏览器网络连通性;在 DevTools 的 Network → WS 查看握手和二进制帧,在 Console 查看协议断开原因。 |
|
|
101
|
-
| `200022` | 请求在登录完成前发送,或连接鉴权状态已失效。先确认 `auth.login` 成功。 |
|
|
102
|
-
| `200024` / `200027` | credential 被拒绝、过期或与 pid/UID 不匹配;重新从服务端获取,不要在页面输出 credential。 |
|
|
103
|
-
| `200020` / `200021` | URI 未开放或权限不足;确认 TLV 能力开关、项目权限和测试账号角色。 |
|
|
104
|
-
| `200034`、`200030` | 字段名/类型/范围或 payload/extra 大小不符合契约;对照 [TLV v1 传输 API](TLV.md) 和 [TLV v1 Client API 契约](TLV_CONTRACT.md)。 |
|
|
105
|
-
| `200053` | `message_ref` 重复;确认测试 marker、重试策略和业务侧 message_ref 生成规则。 |
|
|
106
|
-
| `200999` | 连接、超时或服务端内部错误;结合 `ErrorRecorder`、`SessionClosed` 和浏览器 Network 日志判断发生阶段。 |
|
|
107
|
-
|
|
108
|
-
SDK 调试时可重点观察:
|
|
109
|
-
|
|
110
|
-
- `ErrorRecorder`:查看连接、协议和登录层的 `code/status/reason`,比 `login` 的布尔结果更适合定位环境问题;普通业务请求的 Gate 错误要检查对应 callback 或 Promise rejection。
|
|
111
|
-
- `ReloginCompleted`、`SessionClosed`:判断自动重连是成功、失败还是被服务端关闭。
|
|
112
|
-
- `requestMetadata`:为每个请求附加不含秘密的 `trace` 和 `sent_ms`,用于和 Gate 日志关联。
|
|
113
|
-
- 原始 URI、字段和 frame 编解码问题:对照 [TLV v1 传输 API](TLV.md) 与 [TLV v1 Client API 契约](TLV_CONTRACT.md)。
|
|
114
|
-
|
|
115
|
-
页面会尽量脱敏结果,不保存 UID、credential、项目密钥或运行结果;仍不要把结果页截图或浏览器 Network 导出直接发到公开渠道。
|