# external-integrations 规范

## 目的

定义 TvT.js 与外部系统耦合或嵌入时的边界，包括 `qiankun` 宿主、小程序/`uni-app` WebView、`zone3Deditor` 导出链路，以及 `GoView` 低代码 UI 组合场景。

## 职责边界

### 本规范覆盖

- `qiankun` 子应用生命周期与宿主状态桥接
- `qiankun` 模式下的公共路径与容器感知约束
- `uni-app` 与小程序 WebView 的兼容预期
- 面向 `zone3Deditor` 的插件/导出友好性要求
- 与 `GoView` 相关、且会影响 TvT.js 插件开发的导入导出关系

### 本规范不覆盖

- 已由 `plugin-system` 负责的一般插件目录与配置约定
- 预览中心菜单逻辑
- 除非直接影响集成交付，否则不展开打包机制细节
- 外部产品自身的全部行为，只讨论 TvT.js 需要满足的契约部分

## 主要代码依据

- `.fes.js`
- `src/app.jsx`
- `src/components/forPreview/cardList.vue`
- `src/plugins/qiankunTvt/config.js`
- `src/plugins/uniAppView/config.js`
- `src/plugins/zone3Deditor/config.js`
- `src/plugins/goView/config.js`

## 要求

### Requirement: qiankun 硬性兼容要求

当 TvT.js 作为 `qiankun` 子应用运行时，系统 SHALL 兼容容器宿主模式，包括注入公共路径、暴露生命周期钩子，以及在需要时接收宿主全局状态。

#### Scenario: qiankun 公共路径注入

- GIVEN 当前运行环境由 `qiankun` 宿主驱动
- WHEN 子应用启动
- THEN 系统 SHALL 读取 `__INJECTED_PUBLIC_PATH_BY_QIANKUN__`
- AND SHALL 将该路径暴露给运行时使用

#### Scenario: qiankun 状态桥接

- GIVEN 宿主应用向子应用传递全局状态
- WHEN `mount` 生命周期执行
- THEN TvT.js SHALL 通过既有桥接逻辑接收状态变更

### Requirement: 嵌入式容器兼容基线

面向 `qiankun`、`uni-app` WebView、小程序 WebView 等嵌入式容器的页面与插件 SHALL 避免依赖会破坏容器宿主的全局假设，例如强依赖全屏、未防护的浏览器专属 API、不可控的全局副作用。

#### Scenario: WebView 中使用浏览器专属能力

- GIVEN 某插件计划在 WebView 或嵌入容器中运行
- WHEN 其需要访问浏览器专属全局对象或交互能力
- THEN 维护者 SHALL 先进行环境防护或降级处理

### Requirement: uni-app 与小程序接入要求

面向 `uni-app` 与小程序生态的预览跳转和页面接入 SHALL 通过稳定路由和显式桥接完成，不得默认假设桌面浏览器跳转语义总是成立。

#### Scenario: 小程序环境跳转

- GIVEN 当前页面运行在小程序容器中
- WHEN 预览中心跳转到具体案例
- THEN 系统 SHALL 使用适配小程序环境的跳转逻辑
- AND 不应直接假设 `window.open` 始终可用

### Requirement: zone3Deditor 友好性要求

当插件或场景目标包含 `zone3Deditor` 相关导出、再编辑或场景复用时，其实现 SHALL 尽量保持组件化、配置驱动、资源路径稳定。开源仓库中的 `zone3Deditor` 条目应被视为编辑器接入点与配置说明，而不是完整源码镜像。

#### Scenario: 面向编辑器的场景实现

- GIVEN 某场景未来需要进入区域场景编辑器链路
- WHEN 维护者设计其结构
- THEN 该场景 SHALL 优先采用可复用组件与配置驱动方式组织

### Requirement: GoView 集成归属

当前 `GoView` 相关能力 SHALL 继续归属在外部集成规范内，而不单独拆分为独立 spec。只有当其集成面明显扩大、已形成独立约束集合时，才应考虑拆出单独规范。

#### Scenario: 当前 GoView 规范归属

- GIVEN 维护者需要查阅 `GoView` 相关边界
- WHEN 当前集成面仍以导入导出和组合接入为主
- THEN 该边界 SHALL 继续由 `external-integrations` 管理