XuqmGroup-RNSDK/docs/IMPLEMENTATION_HANDOFF.md

RN SDK 重构实施接管文档

状态更新时间：2026-07-18 当前实施范围：@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：16 个测试通过。
• bugcollect：4 个独立测试通过。
• xwebview：4 个独立测试通过。
• update CLI：9 个测试通过；release-set：6 个测试通过。
• IM 现有测试：3 个通过；IM 不在本轮开发范围。
• 所有 workspace TypeScript typecheck：通过。

3.2 已存在能力

• common 已提供配置、共享会话、HTTP、日期、文件、加密和 XWebView bridge。
• common 已新增统一流式下载、SHA-256、RFC 文件名解析和 SemVer/版本范围能力；update/xwebview 后续必须复用，不再保留私有实现。
• common-only 宿主缺少配置文件时不会触发自动初始化，已有测试覆盖。
• 配置文件自动初始化遇到临时网络失败时会清理失败 Promise；扩展下一次等待初始化时使用同一加密配置重试，不要求宿主重新传 appKey/URL，也不会产生未处理 Promise 或重复错误日志。
• bugcollect、update、xwebview 通过 @xuqm/rn-common/internal 触发一次自动初始化入口。
• update CLI 已能从 schema v3 xuqm.config.json 构建 startup/common/app/buz，生成携带 SemVer 兼容范围和原生 API 等级的内嵌 manifest。
• Android bundle 引擎不在 xuqm.config.json 重复声明：CLI 直接读取宿主 android/gradle.properties 的 hermesEnabled。启用时所有插件统一编译为 Hermes bytecode、组合 source map，并在 manifest/上传表单记录 bundleFormat。
• common 的唯一 XWebView 契约新增实时导航状态；全屏与内嵌容器统一提供 canGoBack、canGoForward、当前标题和 URL，并支持宿主配置回调。Bridge 不再重复声明第二份 controller 类型。
• 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 公共上下文收敛	完成	公共基础与共享生命周期 16 测试
bugcollect 依赖 common 与测试	完成	自动初始化、SHA、版本与策略已统一，4 测试
xwebview 文件/权限能力与测试	完成	文件下沉 common，H5 摄像头/麦克风统一授权，4 测试通过
update release set 与原生事务	进行中	Android Snapshot 已发布；待 Bridge 编译和模拟器验证
package 内容校验	待实施	四包完成后执行
Jenkins alpha 发布	待实施	仅在全部门禁通过后触发
App4 接入	进行中	App4 已接入已发布 alpha；等待包含初始化重试的新 alpha

5. 下一步操作

1. 通过 Jenkins 发布包含 common 初始化重试的新 alpha；本地源码版本号不手工替代 Jenkins 的原子版本分配。
2. App4 使用新精确版本后，在网络正常的 Android 设备验证自动初始化、登录及扩展共享会话。
3. 用仓库内 native-test 编译 RN Java Bridge，再在 Android 宿主补充 release-set crash/recovery 仪器测试。
4. 收敛 Jenkins 四包依赖发布顺序和 package 内容检查。
5. 后续租户平台实现 /api/v1/rn/release-set/check，服务端只返回目标入口与 common 的兼容闭包。
6. Jenkins 下一版 @xuqm/rn-update 必须包含 Hermes 字节码构建改造；App4 不允许长期依赖手工修改的 node_modules。

6. 常用验证命令

pnpm validate
pnpm --dir packages/update pack:check
pnpm --dir packages/common test
pnpm --dir packages/update test

不得通过忽略错误、|| true 或跳过测试让 Jenkins 变绿。

7. 本轮变更记录

2026-07-18 / Android Hermes 插件产物

• xuqm-rn 从宿主 android/gradle.properties 读取唯一 hermesEnabled，不要求用户再维护插件引擎字段。
• Android Hermes 宿主在 Metro bundle 后统一调用与 React Native 版本匹配的 hermes-compiler；source map 使用 RN 官方组合脚本合并 Metro 与 Hermes 映射。
• 内嵌 manifest 与上传表单新增 bundleFormat，便于服务端和诊断工具识别 JavaScript/Hermes 产物。
• 新增独立 fixture，验证普通宿主保持 JavaScript、Hermes 宿主生成字节码；update CLI 9 测试、release-set 6 测试、typecheck、package 内容检查全部通过。
• App4 arm64 内嵌构建已真实生成六个 Hermes bytecode bundle 并安装启动；ARM64 软件模拟器启动仍慢，必须在真实 Android 设备补性能验收。

2026-07-18 / XWebView 鉴权 H5 首屏请求头

• XWebViewConfig 新增可选 headers: Record<string, string>；全屏与内联两种 XWebView 都只在 URL 首次加载的 source 上使用同一配置，不新增 App 专属桥接。
• App4 的签章详情使用该能力携带当前平台 userId/sessionId/currentClientId 和签名头；SDK 不理解也不保存医网信平台状态。
• common/xwebview 类型检查、4 项 xwebview 测试及整个 RN SDK pnpm validate 已通过。

2026-07-18 / common 自动初始化恢复

• Metro pre-main 自动初始化只负责提前发起任务并消费拒绝，不在 SDK 内重复打印宿主会处理的错误。
• common 保存构建期加密配置请求；临时失败会同时清理初始化 Promise 和配置初始化 Promise，下一次 awaitInitialization() 自动重试。
• 重试仍复用 startInitialization 的单 Promise 和配置一致性约束，没有增加第二套初始化入口或参数透传。
• 单元测试覆盖“第一次远程配置失败、第二次等待初始化成功”，common 16 个测试与 TypeScript 检查通过。
• 新增 formatNumericDateTime 作为 API 固定时间格式和跨项目数字日期布局的唯一通用实现；App4 已删除公告、消息、通知、日程和反馈中的重复年月日拼接。

2026-07-18 / 空目录收敛约束

• 删除无效文件时必须同步删除空父目录，不允许用 .gitkeep 维持没有职责的源码结构。
• 已删除 bugcollect 遗留的空 specs、ios、Android log 包以及根 src/shims；依赖和 Gradle 生成目录不属于源码结构。
• 该规则已写入仓库 AGENTS.md，后续文件迁移、模块删除和脚手架调整必须在同一次变更中完成目录收尾。
• 清理后 pnpm validate 通过：格式、六个 workspace 类型检查以及 common/bugcollect/update/im/xwebview 全部测试无回归。

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 写制品。
• #50 证明旧 Jenkins 工作树仍保留 CRLF；主检出由 CleanBeforeCheckout 改为 WipeWorkspace，确保 .gitattributes 在全新工作树生效。
• XuqmRuntime.activate 增加显式 reloadBundle：buz-only release 可替换旧定义并热加载；含 common 的 release 仍由宿主冷启动。
• #51 通过换行、格式和类型门禁后，暴露 pack 校验脚本硬编码 Unix npm；现改为 fileURLToPath 与 Windows cmd.exe/npm.cmd 分支。
• #52 通过 pack/typecheck 后发现 Metro 测试只接受 POSIX 路径分隔符；断言改为同时接受 Windows 与 POSIX 路径。

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、16 个测试、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 后编译通过；该失败不得通过关闭检查规避。
• Jenkins Windows 节点直接访问外部 Android 仓库会出现无输出的长时间依赖等待；native-test 的 plugin management 已与 AndroidSDK 对齐，统一优先使用 Nexus android 聚合仓库，再回退官方仓库。
• Windows CLI 测试路径统一使用 fileURLToPath，禁止把 file: URL 的 pathname 直接作为本机路径。
• native baseline 现在按 Android/iOS 分别计算，并覆盖全部运行时依赖的实际安装版本、平台原生源码/资源、src/assets 内会随安装包打入的图片、字体和媒体文件；这些内容变化后必须先发布完整 App，不能只发布 JS 插件。