151 行
12 KiB
Markdown
151 行
12 KiB
Markdown
# RN SDK 重构实施接管文档
|
||
|
||
> 状态更新时间：2026-07-17
|
||
> 当前实施范围：`@xuqm/rn-common`、`@xuqm/rn-bugcollect`、`@xuqm/rn-update`、`@xuqm/rn-xwebview`
|
||
> 发布约束：所有 XuqmGroup npm/Maven 制品和服务部署只能通过 `https://jenkins.xuqinmin.com/` 的 Jenkins 完成。
|
||
|
||
## 1. 本轮目标
|
||
|
||
1. `rn-common` 可以完全独立使用公共工具，不要求初始化或登录。
|
||
2. 使用 bugcollect、update、xwebview 等扩展时，只执行一次共享 SDK 初始化和一次共享登录。
|
||
3. 配置文件放入约定位置后由构建工具自动接入初始化，不要求宿主逐个初始化子 SDK。
|
||
4. common、update、bugcollect、xwebview 之间只保留一份网络、文件、时间、配置、会话和错误定义。
|
||
5. update SDK 统一承担插件 manifest、兼容性、原子激活、启动确认、崩溃回滚和内嵌恢复；宿主不得再实现平行版本管理器。
|
||
6. Android 整包更新必须具备应用内下载、SHA-256 校验、安装权限处理、进度、取消、重试和确定性错误码。
|
||
7. 宿主通过最少配置完成插件创建、开发运行、打包、随 APK 内嵌、发布和回滚。
|
||
|
||
## 2. 已冻结的设计约束
|
||
|
||
- `startup` 是内嵌恢复入口，只随完整安装包更新。
|
||
- `common`、`app`、`buz` 可以作为插件版本管理对象；common/app 更新必须冷启动生效。
|
||
- 插件声明 `appVersionRange`、`commonVersionRange` 和 `minNativeApiLevel`；完整包登记 `nativeBaselineId`，插件记录 `builtAgainstNativeBaselineId`。不能只靠一个最大 App 版本或最低 common 字段推断兼容性；配置 schema 已统一为 v3。
|
||
- 一次依赖更新必须作为一个 release set：全部下载、全部校验、全部 staging、原子激活、整组确认或整组回滚。
|
||
- common 同一主版本遵守向后兼容；破坏性 API 变更必须提升主版本。
|
||
- 插件版本比较必须使用 SemVer；“不相等”不能等价为“需要升级”。
|
||
- 远程 Bundle 和 manifest 使用 SHA-256，并预留签名 manifest；MD5 不作为最终安全校验。
|
||
- 现阶段不扩展 `@xuqm/rn-push`，医网信宿主继续使用腾讯 Push。
|
||
- 差分 APK 本轮只保留协议扩展位，不实现差分生成与合并。
|
||
- 启动更新顺序固定为：准备/恢复未确认 release set → 整包检查 → 无整包更新时检查 `app + common` 依赖闭包。
|
||
- buz 只在进入前检查“当前 buz + common”依赖闭包，不扫描或顺带更新其它 buz；common 不作为业务入口独立检查。
|
||
|
||
## 3. 当前可信基线
|
||
|
||
### 3.1 质量门禁
|
||
|
||
- Android SDK Jenkins `sdk-android-publish #152`：成功，已发布
|
||
`com.xuqm:sdk-core:1.1.6-SNAPSHOT` 与 `com.xuqm:sdk-update:2.0.0-SNAPSHOT`。
|
||
- `native-test` 是 RN update Android Bridge 的唯一 Gradle 编译夹具；Jenkins 发布 update 前必须执行
|
||
`:updateBridge:compileDebugJavaWithJavac`。
|
||
- 本地已使用 JDK 21 + Gradle 9.3.1 编译通过；RN Bridge 明确输出 Java 17 字节码，不再隐式回落到 Java 8。
|
||
- RN 包不再内置第二份 AGP buildscript；宿主负责插件版本，独立夹具使用与 Android SDK 一致的 AGP 9.1.0。
|
||
- `pnpm validate`：通过。
|
||
- common：15 个测试通过。
|
||
- bugcollect：4 个独立测试通过。
|
||
- xwebview：2 个独立测试通过。
|
||
- update CLI：6 个测试通过；release-set：6 个测试通过。
|
||
- IM 现有测试：3 个通过；IM 不在本轮开发范围。
|
||
- 所有 workspace TypeScript typecheck：通过。
|
||
|
||
### 3.2 已存在能力
|
||
|
||
- common 已提供配置、共享会话、HTTP、日期、文件、加密和 XWebView bridge。
|
||
- common 已新增统一流式下载、SHA-256、RFC 文件名解析和 SemVer/版本范围能力；update/xwebview 后续必须复用，不再保留私有实现。
|
||
- common-only 宿主缺少配置文件时不会触发自动初始化，已有测试覆盖。
|
||
- bugcollect、update、xwebview 通过 `@xuqm/rn-common/internal` 触发一次自动初始化入口。
|
||
- update CLI 已能从 schema v3 `xuqm.config.json` 构建 startup/common/app/buz，生成携带 SemVer 兼容范围和原生 API 等级的内嵌 manifest。
|
||
- RN update 已有 release-set 纯领域规划器；Android 原生模块已改为整组 staging/激活/确认/回滚，并从 APK assets 恢复内嵌基线。
|
||
|
||
### 3.3 已确认缺口
|
||
|
||
- RN update 已编码 `XuqmAppUpdateModule`，只桥接 XuqmGroup Android `sdk-update:2.0.0-SNAPSHOT`；待 Jenkins 发布 Android Snapshot 后完成宿主 Gradle 编译和模拟器验证。
|
||
- release-set 已统一使用 SHA-256，但签名 manifest 尚待实现。
|
||
- 原生 state 已成为 Bundle 版本与事务状态唯一真相；App 更新提示缓存仍可使用 AsyncStorage，但不保存 Bundle 版本。
|
||
- 客户端已改为 `/api/v1/rn/release-set/check` 单次请求目标入口依赖闭包；租户平台服务端接口尚待同步实现。
|
||
- `nativeBaselineId` 已自动计算并进入内嵌 manifest/插件上传：覆盖 Android 原生源码、Gradle 配置、RN 与含原生代码的 npm 依赖，普通业务 JS 不影响指纹；Jenkins/服务端登记校验尚待实现。
|
||
- 插件 API 已拆分为纯检查 `checkPluginRelease`、确认后安装 `installPluginRelease` 和自动场景 `checkAndInstallPlugin`；检查阶段不下载、不写本地状态。
|
||
- bugcollect 的采样、限频、fatal 绕过采样和 fatal/error 持久化策略已有纯逻辑测试覆盖。
|
||
- xwebview 的相册保存仍是可选宿主能力；其余文件下载能力已经下沉到 common。
|
||
- Jenkins 发布参数已收敛到 common、update、bugcollect、xwebview；仍需增加依赖版本存在性与发布顺序硬校验。
|
||
|
||
## 4. 实施进度
|
||
|
||
| 工作项 | 状态 | 说明 |
|
||
| ----------------------------- | ------ | --------------------------------------------------- |
|
||
| 基线审计与门禁 | 完成 | 2026-07-17 本地 validate 全通过 |
|
||
| 实时接管文档 | 进行中 | 本文件为唯一实施状态入口 |
|
||
| common 公共上下文收敛 | 完成 | 公共基础与共享生命周期 15 测试 |
|
||
| bugcollect 依赖 common 与测试 | 完成 | 自动初始化、SHA、版本与策略已统一，4 测试 |
|
||
| xwebview 文件能力与测试 | 完成 | 文件能力下沉 common，2 测试通过 |
|
||
| update release set 与原生事务 | 进行中 | Android Snapshot 已发布；待 Bridge 编译和模拟器验证 |
|
||
| package 内容校验 | 待实施 | 四包完成后执行 |
|
||
| Jenkins alpha 发布 | 待实施 | 仅在全部门禁通过后触发 |
|
||
| App4 接入 | 暂缓 | 用户要求先完成 RN SDK |
|
||
|
||
## 5. 下一步操作
|
||
|
||
1. 用仓库内 `native-test` 编译 RN Java Bridge，再在 Android 宿主补充 release-set crash/recovery 仪器测试。
|
||
2. Jenkins 发布 RN 四个 alpha 包后，执行模拟器整包更新与插件更新验证。
|
||
3. 收敛 Jenkins 四包依赖发布顺序和 package 内容检查。
|
||
4. 后续租户平台实现 `/api/v1/rn/release-set/check`，服务端只返回目标入口与 common 的兼容闭包。
|
||
|
||
## 6. 常用验证命令
|
||
|
||
```bash
|
||
pnpm validate
|
||
pnpm --dir packages/update pack:check
|
||
pnpm --dir packages/common test
|
||
pnpm --dir packages/update test
|
||
```
|
||
|
||
不得通过忽略错误、`|| true` 或跳过测试让 Jenkins 变绿。
|
||
|
||
## 7. 本轮变更记录
|
||
|
||
### 2026-07-17 / Jenkins #48 失败修复
|
||
|
||
- `sdk-rn-publish #48` 在 Windows 棡出后因 8 个文件换行不一致被 Prettier 正确阻断，未发布任何包。
|
||
- 新增 `.gitattributes`，源码统一以 LF 检出；仅 `.bat` 保持 CRLF。
|
||
- alpha 版本号改为取源码现有序号与 Nexus 远端序号的最大值后加一，禁止版本倒退和重复发布。
|
||
- `#49` 被 Jenkins CPS 的不可序列化正则 Matcher 阻断；算法改为只保留整数，并从 Nexus group 读标签、向 hosted 写制品。
|
||
|
||
### 2026-07-17 / common 第一轮
|
||
|
||
- 引入 `semver@7.8.5` 与 `@types/semver@7.7.1`，不自行重复实现版本算法。
|
||
- 新增 `downloadBytes`、`downloadText`、`DownloadError` 和统一下载进度结构。
|
||
- 新增 `sha256Hex`，作为后续 Bundle/APK 校验的公共实现。
|
||
- 新增纯 JS 文件名模块，Node/CI 测试不会加载 `react-native` 原生模块。
|
||
- 新增格式化硬门禁，范围限定为本轮四个 SDK 包，避免改动不在范围内的 IM/Push。
|
||
- 验证：common typecheck、15 个测试、Prettier 全部通过。
|
||
|
||
### 2026-07-17 / bugcollect 与 xwebview 第一轮
|
||
|
||
- common 增加扩展初始化订阅；所有扩展共享同一次配置初始化。
|
||
- bugcollect 在远程配置启用后自动启动采集，不要求宿主第二次初始化或手工启动。
|
||
- bugcollect 删除私有 SHA-256 实现并复用 common；SDK 版本改为读取发布包版本。
|
||
- xwebview 删除重复的 Content-Disposition/URL 文件名实现并复用 common。
|
||
- xwebview 删除直接的 blob-util 依赖，大文件下载、进度、取消和 Android 下载登记统一下沉 common。
|
||
- bugcollect 的采样/限频窗口、fatal 绕过采样和 fatal/error 持久化策略抽成纯领域逻辑，避免采集器与队列各自重复判断。
|
||
- 验证：bugcollect typecheck + 4 测试、xwebview typecheck + 2 测试通过。
|
||
|
||
### 2026-07-17 / update release-set 第一轮
|
||
|
||
- 删除 Bundle 版本的 AsyncStorage 副本和 MD5 实现，原生 state 为唯一版本真相，远程 Bundle 强制 SHA-256。
|
||
- 新增 release-set 规划器，验证 SemVer 升级、common 范围、原生 API 等级和最终已安装集合兼容性。
|
||
- Android 原生模块使用单一事务日志完成整组 staging/激活/确认/回滚；首次运行可从 APK `assets/rn-bundles` 恢复内嵌版本。
|
||
- 未确认 release set 首次启动获得一次确认机会；再次启动仍未确认才整组回滚，避免冷启动更新在加载前被误回滚。
|
||
- 更新检查改为按入口依赖闭包：启动时整包优先，其后 app+common；buz 进入前只检查当前 buz+common。
|
||
- SDK 不决定宿主 UI：整包与插件均提供独立检查/安装 API；App4 进入 buz 使用 `checkAndInstallPlugin`，需要弹窗的宿主使用 `checkPluginRelease` 后再调用 `installPluginRelease`。
|
||
- release-set 记录检查时的全部本地基线版本；弹窗停留期间状态变化会触发 `StaleReleaseSetError`，不会安装过期计划。
|
||
- `xuqm.config.json` 统一升级到 schema v3：`commonVersionRange` + `minNativeApiLevel`，删除 `minCommonVersion`/`minNativeVersion` 双重语义。
|
||
- 验证：update typecheck、CLI 6 测试、release-set 6 测试通过；Android 原生代码尚待宿主工程编译验证。
|
||
|
||
### 2026-07-17 / Android 整包安装桥接
|
||
|
||
- 新增 `XuqmAppUpdateModule`，桥接 AndroidSDK 的唯一 APK 更新实现，不在 RN 包重复下载、哈希或 FileProvider 逻辑。
|
||
- 原生事件提供下载字节数、总字节数和百分比；支持 AbortSignal 取消、有限重试及确定错误码。
|
||
- SHA-256 为安装硬门禁；缺失哈希直接拒绝，不降级为未校验安装。
|
||
- 增加 `openInstallPermissionSettings()`，宿主收到 `INSTALL_PERMISSION_REQUIRED` 后可自行展示 UI 并跳转授权。
|
||
- Android SDK Jenkins `#152` 已发布 `com.xuqm:sdk-update:2.0.0-SNAPSHOT`。
|
||
- 新增 `native-test` 最小 Gradle 工程；Jenkins 发布 update 前必须真实编译 Java Bridge，不允许只做 TypeScript/打包校验。
|
||
- 首次门禁发现独立工程未启用 AndroidX，补充 `native-test/gradle.properties` 后编译通过；该失败不得通过关闭检查规避。
|
