diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 237a41f32..ee13cd14f 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -16,6 +16,14 @@ --- +## 2026-06-21 原生壳依赖版本门禁不可移除 + +- 背景：Expo / React Native / Tauri 的依赖版本会影响 WebView、权限、capability、构建产物和宿主桥接行为；两端单端配置检查已经锁定 package、lockfile 和 Cargo 解析版本，但根级总验收也需要防止未来重构时把这些锁版本检查从单端脚本中移除。 +- 决策：`npm run check:native-shells` 必须反查移动壳 `check-config.mjs` 继续校验 Expo SDK、React Native、WebView、EAS CLI 和 `package-lock.json` 解析版本；桌面壳 `check-config.mjs` 必须继续校验 Tauri CLI、Cargo manifest、`Cargo.lock` 解析版本和直接依赖关系。升级原生壳底层依赖必须同步更新单端配置检查、锁文件和宿主壳方案文档。 +- 影响范围：`scripts/check-native-shells.mjs`、`apps/mobile-shell/scripts/check-config.mjs`、`apps/desktop-shell/scripts/check-config.mjs`、原生壳依赖升级流程。 +- 验证方式：`npm run check:native-shells`、`npm run check:encoding`、`git diff --check`。 +- 关联文档：`docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md`。 + ## 2026-06-20 移动 HostBridge 消息注入失败边界 - 背景：Expo 移动壳通过 WebView `injectJavaScript` 把 HostBridge response 以及 `app.lifecycle`、`network.statusChanged`、`navigation.canGoBack` 等宿主事件回放给 H5；如果 WebView 进程切换、页面卸载或注入同步失败，壳层不能因为响应或事件回灌异常而崩溃。 diff --git a/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md b/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md index 8b67b8c1d..6e85eff41 100644 --- a/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md +++ b/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md @@ -72,6 +72,8 @@ src/ 生产替身词扫描只覆盖上述壳源码、分发配置、共享 HostBridge 契约和已接入真实宿主能力的 H5 调用链；Expo export、Tauri `target/`、Cargo / Metro 缓存和 release 构建产物不进入扫描范围，避免本地或 CI 生成文件污染源码门禁。 +根级原生壳检查还会反查两端单端配置检查的依赖版本门禁：移动壳必须继续锁定 Expo SDK、React Native、WebView、EAS CLI 和 `package-lock.json` 实际解析版本；桌面壳必须继续锁定 Tauri CLI、Cargo manifest、`Cargo.lock` 解析版本和直接依赖关系。升级 Expo / React Native / Tauri 不能只改 `package.json` 或 `Cargo.toml`，必须同时更新单端配置检查、锁文件和本文档里的宿主能力假设。 + 结构门禁按完整相对路径反查文档和目录：微信桥接层为 `miniprogram/host-bridge/dispatch.js`、`miniprogram/host-bridge/payment.js`、`miniprogram/host-bridge/protocol.js`、`miniprogram/host-bridge/shareGrid.js`、`miniprogram/host-bridge/subscribeMessage.js`、`miniprogram/host-bridge/webView.js`；微信 shell 层为 `miniprogram/shell/payment.js`、`miniprogram/shell/shareGrid.js`、`miniprogram/shell/subscribeMessage.js`、`miniprogram/shell/webView.js`；微信页面包装层为 `miniprogram/pages/share-grid/index.js`、`miniprogram/pages/share-grid/index.json`、`miniprogram/pages/share-grid/index.wxml`、`miniprogram/pages/share-grid/index.wxss`、`miniprogram/pages/subscribe-message/index.js`、`miniprogram/pages/subscribe-message/index.json`、`miniprogram/pages/subscribe-message/index.wxml`、`miniprogram/pages/subscribe-message/index.wxss`、`miniprogram/pages/web-view/index.js`、`miniprogram/pages/web-view/index.json`、`miniprogram/pages/web-view/index.wxml`、`miniprogram/pages/web-view/index.wxss`、`miniprogram/pages/wechat-pay/index.js`、`miniprogram/pages/wechat-pay/index.json`、`miniprogram/pages/wechat-pay/index.wxml`、`miniprogram/pages/wechat-pay/index.wxss`；移动源码根为 `apps/mobile-shell/src/env.d.ts`；移动桥接层为 `apps/mobile-shell/src/host-bridge/appearance.test.ts`、`apps/mobile-shell/src/host-bridge/appearance.ts`、`apps/mobile-shell/src/host-bridge/badge.test.ts`、`apps/mobile-shell/src/host-bridge/badge.ts`、`apps/mobile-shell/src/host-bridge/bridge.ts`、`apps/mobile-shell/src/host-bridge/capabilities.test.ts`、`apps/mobile-shell/src/host-bridge/capabilities.ts`、`apps/mobile-shell/src/host-bridge/clipboard.test.ts`、`apps/mobile-shell/src/host-bridge/clipboard.ts`、`apps/mobile-shell/src/host-bridge/dispatch.ts`、`apps/mobile-shell/src/host-bridge/filePayloads.test.ts`、`apps/mobile-shell/src/host-bridge/filePayloads.ts`、`apps/mobile-shell/src/host-bridge/files.test.ts`、`apps/mobile-shell/src/host-bridge/files.ts`、`apps/mobile-shell/src/host-bridge/haptics.test.ts`、`apps/mobile-shell/src/host-bridge/haptics.ts`、`apps/mobile-shell/src/host-bridge/navigation.test.ts`、`apps/mobile-shell/src/host-bridge/navigation.ts`、`apps/mobile-shell/src/host-bridge/network.test.ts`、`apps/mobile-shell/src/host-bridge/network.ts`、`apps/mobile-shell/src/host-bridge/notifications.test.ts`、`apps/mobile-shell/src/host-bridge/notifications.ts`、`apps/mobile-shell/src/host-bridge/protocol.test.ts`、`apps/mobile-shell/src/host-bridge/protocol.ts`、`apps/mobile-shell/src/host-bridge/runtime.test.ts`、`apps/mobile-shell/src/host-bridge/runtime.ts`、`apps/mobile-shell/src/host-bridge/scanner.test.ts`、`apps/mobile-shell/src/host-bridge/scanner.ts`、`apps/mobile-shell/src/host-bridge/share.test.ts`、`apps/mobile-shell/src/host-bridge/share.ts`；移动 shell 层为 `apps/mobile-shell/src/shell/QrScannerOverlay.test.tsx`、`apps/mobile-shell/src/shell/QrScannerOverlay.tsx`、`apps/mobile-shell/src/shell/ShellApp.tsx`、`apps/mobile-shell/src/shell/deepLink.ts`、`apps/mobile-shell/src/shell/lifecycle.ts`、`apps/mobile-shell/src/shell/loadFailure.ts`、`apps/mobile-shell/src/shell/navigation.ts`、`apps/mobile-shell/src/shell/network.ts`、`apps/mobile-shell/src/shell/runtime.ts`、`apps/mobile-shell/src/shell/safeArea.ts`、`apps/mobile-shell/src/shell/url.ts`、`apps/mobile-shell/src/shell/webViewGlobals.d.ts`、`apps/mobile-shell/src/shell/webViewHistory.ts`、`apps/mobile-shell/src/shell/webViewPolicy.ts`；桌面入口为 `apps/desktop-shell/src-tauri/src/app.rs`、`apps/desktop-shell/src-tauri/src/main.rs`；桌面桥接层为 `apps/desktop-shell/src-tauri/src/host_bridge/appearance.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/badge.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/capabilities.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/clipboard.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/dispatch.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/file_payloads.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/files.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/mod.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/navigation.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/network.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/notifications.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/protocol.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/runtime.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/share.rs`、`apps/desktop-shell/src-tauri/src/host_bridge/title.rs`；桌面 shell 层为 `apps/desktop-shell/src-tauri/src/shell/deep_link.rs`、`apps/desktop-shell/src-tauri/src/shell/events.rs`、`apps/desktop-shell/src-tauri/src/shell/file_drop.rs`、`apps/desktop-shell/src-tauri/src/shell/lifecycle.rs`、`apps/desktop-shell/src-tauri/src/shell/menu.rs`、`apps/desktop-shell/src-tauri/src/shell/mod.rs`、`apps/desktop-shell/src-tauri/src/shell/navigation.rs`、`apps/desktop-shell/src-tauri/src/shell/network.rs`、`apps/desktop-shell/src-tauri/src/shell/runtime.rs`、`apps/desktop-shell/src-tauri/src/shell/tray.rs`、`apps/desktop-shell/src-tauri/src/shell/url.rs`、`apps/desktop-shell/src-tauri/src/shell/webview.rs`、`apps/desktop-shell/src-tauri/src/shell/window_state.rs`。这些目录不得新增未登记子目录或生产入口；移动端和桌面端单端配置检查同样会拒绝未登记生产模块。 ## HostBridge 消息协议 diff --git a/scripts/check-native-shells.mjs b/scripts/check-native-shells.mjs index c11327b07..e390ba7b1 100644 --- a/scripts/check-native-shells.mjs +++ b/scripts/check-native-shells.mjs @@ -14,6 +14,14 @@ const developmentWorkflowDocPath = 'docs/project-memory/shared-memory/development-workflow.md'; const decisionLogDocPath = 'docs/project-memory/shared-memory/decision-log.md'; const rootPackageJson = JSON.parse(fs.readFileSync('package.json', 'utf8')); +const mobileShellConfigCheckSource = fs.readFileSync( + 'apps/mobile-shell/scripts/check-config.mjs', + 'utf8', +); +const desktopShellConfigCheckSource = fs.readFileSync( + 'apps/desktop-shell/scripts/check-config.mjs', + 'utf8', +); const productionShellScanRoots = [ 'apps/mobile-shell', @@ -74,6 +82,44 @@ function assertRootNativeShellCheckScripts() { } assertRootNativeShellCheckScripts(); +function assertNativeShellDependencyVersionGuardrails() { + for (const snippet of [ + "const rootPackageLockPath = new URL('../../../package-lock.json', import.meta.url)", + 'function assertPackageDependencyVersion(', + 'function assertPackageLockVersion(', + "'@expo/metro-runtime': '^56.0.15'", + "expo: '^56.0.12'", + "'react-native': '^0.86.0'", + "'react-native-webview': '^13.16.1'", + "'eas-cli': '^20.3.0'", + "assertPackageLockVersion('eas-cli', '20.3.0')", + ]) { + if (!mobileShellConfigCheckSource.includes(snippet)) { + throw new Error(`mobile shell dependency guardrail drifted: missing ${snippet}`); + } + } + + for (const snippet of [ + "const rootPackageLockPath = new URL('../../../package-lock.json', import.meta.url)", + "const cargoLockPath = new URL('../src-tauri/Cargo.lock', import.meta.url)", + 'function assertPackageDependencyVersion(', + 'function assertPackageLockVersion(', + 'function assertCargoDependencyLine(', + 'function assertCargoLockPackageVersion(', + 'function assertCargoLockDirectDependency(', + "'@tauri-apps/cli': '^2.11.2'", + "'@tauri-apps/cli': '2.11.2'", + 'tauri = { version = "2.11.2", features = ["tray-icon"] }', + "['tauri', '2.11.2']", + 'tauri-plugin-single-instance = { version = "2.4.2", features = ["deep-link"] }', + ]) { + if (!desktopShellConfigCheckSource.includes(snippet)) { + throw new Error(`desktop shell dependency guardrail drifted: missing ${snippet}`); + } + } +} + +assertNativeShellDependencyVersionGuardrails(); const h5HostBridgeCallChainWrapperFiles = [ 'src/hooks/useHostLifecycleActive.ts', 'src/hooks/useHostNavigationCanGoBack.ts',