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：19 个测试通过。
• bugcollect：5 个独立测试通过。
• xwebview：4 个独立测试通过。
• update CLI/Metro：11 个测试通过；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。
• update 的 withXuqmModuleConfig() 是多 Bundle 模块编号的唯一实现：日常 Metro 不变，CLI 构建时自动先生成 startup/common 共享模块表，并按配置序号为每个 app/buz 分配独立区间；宿主不再维护多份 Metro 配置或业务名硬编码 offset。
• 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；Android Snapshot、Bridge 编译和 App4 完整 debug 构建已通过，模拟器安装事务仍待验证。
• 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；common/xwebview/update 新 alpha 已发布，仍需增加依赖版本存在性与发布顺序硬校验。

4. 实施进度

工作项	状态	说明
基线审计与门禁	完成	2026-07-17 本地 validate 全通过
实时接管文档	进行中	本文件为唯一实施状态入口
common 公共上下文收敛	完成	公共基础、共享生命周期与安全 API 诊断 19 测试
bugcollect 依赖 common 与测试	完成	自动初始化、SHA、版本、策略与 HTTP 脱敏已统一，5 测试
xwebview 文件/权限能力与测试	完成	文件下沉 common，H5 摄像头/麦克风统一授权，4 测试通过
update release set 与原生事务	进行中	Android Snapshot、Bridge、App4 构建通过；待事务 E2E
package 内容校验	完成	update 包 42 个发布文件已校验
Jenkins alpha 发布	完成	#59/#60 已发布 common、xwebview、update
App4 接入	完成构建	精确 alpha 已接入，六 Hermes 插件与 debug APK 构建通过

5. 下一步操作

1. 在网络正常的 Android 设备验证自动初始化、登录及扩展共享会话。
2. 在 Android 宿主补充 release-set 安装、冷启动确认和崩溃回滚仪器测试。
3. 收敛 Jenkins 四包依赖发布顺序和 package 内容检查。
4. 后续租户平台实现 /api/v1/rn/release-set/check，服务端只返回目标入口与 common 的兼容闭包。
5. App4 当前使用相邻源码联调本轮未发布变更；验证完成后必须由 Jenkins 发布新 alpha，再恢复 Nexus 精确版本。禁止手改 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 / 网络诊断安全收敛

• rn-common 不再打印完整 Axios 响应、请求配置、headers 或完整 URL。
• 网络诊断的唯一实现位于 packages/common/src/api/diagnostics.ts，只保留 method、相对 path、HTTP 状态、错误码和 Zod 字段路径。
• 新增测试使用带手机号、sessionId、userId、token 的伪响应，强制验证 序列化后的诊断结果不包含这些敏感值。
• 全局 API 错误回调不再交付带 Axios cause 的 RequestError，只交付不可逆的安全诊断报告；宿主无法误把请求体、headers 或响应上传到采集平台。
• bugcollect 的全局 fetch 拦截器只上报 method、相对 path 和 HTTP status；完整 host、query、请求体、headers 及原始网络异常对象全部丢弃，测试覆盖敏感查询参数和鉴权头。

2026-07-18 / 多 Bundle Metro 能力下沉

• 新增公开入口 @xuqm/rn-update/metro，withXuqmModuleConfig() 内部复用 common 的 withXuqmConfig()，宿主只保留一份 Metro 配置。
• xuqm-rn build/embed/publish 为每个模块注入 id、type、配置序号和共享缓存位置；模块区间不再依赖 szyx/miniapp 等业务目录名称。
• 独立构建 app/buz 时 CLI 自动先构建 startup/common 依赖以重建共享模块表，但仍只发布用户选择的模块，适用于全新 Jenkins 工作区。
• 测试覆盖 0 号模块存在性、startup/common 去重、app/buz 唯一区间，以及单独构建 buz 的依赖顺序；update CLI/Metro 11 项、release-set 6 项和 42 文件包内容校验通过。

2026-07-18 / Jenkins #58—#60 与 App4 精确版本接入

• sdk-rn-publish #58 被 Windows Hermes 测试正确阻断：测试曾把文本写成 hermesc.exe，Windows spawnSync 无法执行；该构建未发布任何包。
• CLI 测试改为复制并执行 React Native 实际依赖的 Hermes 编译器，同一测试覆盖 Windows 可执行文件规则和真实字节码输出，不保留伪编译器兼容分支。
• sdk-rn-publish #59 成功发布 @xuqm/rn-common@0.6.0-alpha.15 与 @xuqm/rn-xwebview@0.3.0-alpha.11。
• sdk-rn-publish #60 成功发布包含 Hermes CLI 改造的 @xuqm/rn-update@0.5.0-alpha.13。
• App4 已使用上述精确版本；startup/common/app/szyx/miniapp/workbench 六模块均生成为 Hermes bytecode version 98，Gradle 自动嵌入后 debug APK 构建成功。
• 本仓库代码提交 aacfbf0 完成宿主运行时/XWebView 协议收敛，04fc964 修复 Windows 真实 Hermes 门禁；发布与 App4 构建证据均已取得，剩余仅为设备端 release-set 事务与网络场景验证。

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 插件。