xuqmGroup/XuqmGroup-RNSDK
0
0
派生 0
代码 工单 合并请求 版本发布 百科 动态
530e4503c4
XuqmGroup-RNSDK/docs/IMPLEMENTATION_HANDOFF.md

12 KiB
原始文件 Blame 文件历史

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. 常用验证命令

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 后编译通过；该失败不得通过关闭检查规避。