锁定移动壳生命周期映射门禁

移动壳配置检查反查生命周期映射函数和四类 AppState 测试

共享决策日志记录生命周期映射门禁约束

apps/mobile-shell/scripts/check-config.mjs

@@ -150,6 +150,10 @@ const loadFailureTestPath = new URL(
 const loadFailureTestSource = fs.readFileSync(loadFailureTestPath, 'utf8');
 const runtimePath = new URL('../src/shell/runtime.ts', import.meta.url);
 const runtimeSource = fs.readFileSync(runtimePath, 'utf8');
+const lifecyclePath = new URL('../src/shell/lifecycle.ts', import.meta.url);
+const lifecycleSource = fs.readFileSync(lifecyclePath, 'utf8');
+const lifecycleTestPath = new URL('../src/shell/lifecycle.test.ts', import.meta.url);
+const lifecycleTestSource = fs.readFileSync(lifecycleTestPath, 'utf8');
 const safeAreaTestPath = new URL('../src/shell/safeArea.test.ts', import.meta.url);
 const safeAreaTestSource = fs.readFileSync(safeAreaTestPath, 'utf8');
 const sharedContractPath = new URL(
@@ -1397,6 +1401,39 @@ for (const snippet of [
   }
 }
 
+for (const snippet of [
+  'lifecyclePayloadFromAppState',
+  "state === 'active'",
+  "state === 'background'",
+  "? 'background'",
+  ": 'inactive'",
+  'focused: state === \'active\'',
+  'nativeState: state',
+]) {
+  if (!lifecycleSource.includes(snippet)) {
+    throw new Error(`mobile shell lifecycle mapper missing ${snippet}`);
+  }
+}
+
+for (const snippet of [
+  "describe('lifecycle'",
+  "test('把 React Native AppState 映射为统一 HostBridge 生命周期状态'",
+  "lifecyclePayloadFromAppState('active')",
+  "lifecyclePayloadFromAppState('background')",
+  "lifecyclePayloadFromAppState('inactive')",
+  "lifecyclePayloadFromAppState('unknown')",
+  "state: 'active'",
+  "state: 'background'",
+  "state: 'inactive'",
+  'focused: true',
+  'focused: false',
+  "nativeState: 'unknown'",
+]) {
+  if (!lifecycleTestSource.includes(snippet)) {
+    throw new Error(`mobile shell lifecycle tests missing ${snippet}`);
+  }
+}
+
 for (const snippet of [
   'type HostBridgeEventName',
   'isHostBridgeEventName',

docs/project-memory/shared-memory/decision-log.md

@@ -2930,6 +2930,13 @@
 - 影响范围：`apps/mobile-shell/src/shell/ShellApp.tsx`、`apps/mobile-shell/src/shell/ShellApp.test.tsx`、`apps/mobile-shell/scripts/check-config.mjs`、宿主壳能力统一协议文档。
 - 验证方式：`npm run mobile-shell:test -- src/shell/ShellApp.test.tsx`、`npm run mobile-shell:typecheck`、`npm run check:native-shells`、`npm run check:encoding`、`git diff --check`。
 
+## 2026-06-20 移动壳生命周期映射门禁
+
+- 背景：Expo `AppState` 的 `active`、`background`、`inactive` 以及未知状态都会进入 `app.lifecycle` 事件；如果归一化映射漂移，H5 游戏循环、背景音乐和固定玩法音频会错误恢复或暂停。
+- 决策：`apps/mobile-shell/src/shell/lifecycle.test.ts` 必须直接覆盖 `active`、`background`、`inactive` 和未知状态到统一 `state`、`focused`、`nativeState` 的映射；`apps/mobile-shell/scripts/check-config.mjs` 反查映射函数和测试片段，确保未知状态继续归为 `inactive` 且只有 `active` 视为 focused。
+- 影响范围：`apps/mobile-shell/src/shell/lifecycle.ts`、`apps/mobile-shell/src/shell/lifecycle.test.ts`、`apps/mobile-shell/scripts/check-config.mjs`。
+- 验证方式：`npm run mobile-shell:test -- src/shell/lifecycle.test.ts`、`npm run mobile-shell:config`、`npm run check:native-shells`、`npm run check:encoding`、`git diff --check`。
+
 ## 2026-06-20 移动分享单测边界
 
 - 背景：Expo 移动壳 `share.open` / `share.setTarget` 已经由 `share.ts` 承接共享 HostBridge 分享 URL 归一和缓存目标，但关键边界主要压在巨型 `bridge.test.ts` 中，后续拆分桥接 helper 时容易遗漏非法显式 payload 不回退缓存、空分享拒绝和缓存目标保留语义。