diff --git a/apps/desktop-shell/scripts/check-config.mjs b/apps/desktop-shell/scripts/check-config.mjs index 55caa9b94..06132d429 100644 --- a/apps/desktop-shell/scripts/check-config.mjs +++ b/apps/desktop-shell/scripts/check-config.mjs @@ -2344,7 +2344,8 @@ for (const snippet of [ 'PermissionState::Granted', 'PermissionState::Denied', 'PermissionState::Prompt | PermissionState::PromptWithRationale', - 'ok(request.id.clone(), json!(true))', + 'desktop_notification_delivered_to_system_result', + '"delivered_to_system"', '"notification permission denied"', 'app.notification().builder()', ]) { diff --git a/apps/desktop-shell/src-tauri/src/host_bridge/notifications.rs b/apps/desktop-shell/src-tauri/src/host_bridge/notifications.rs index effa60605..e9ffab05e 100644 --- a/apps/desktop-shell/src-tauri/src/host_bridge/notifications.rs +++ b/apps/desktop-shell/src-tauri/src/host_bridge/notifications.rs @@ -84,6 +84,10 @@ fn desktop_notification_permission_action( } } +fn desktop_notification_delivered_to_system_result() -> serde_json::Value { + json!({"action": "delivered_to_system"}) +} + pub(crate) fn show_desktop_local_notification( app: &tauri::AppHandle, request: &HostBridgeRequest, @@ -125,7 +129,10 @@ pub(crate) fn show_desktop_local_notification( } match notification.show() { - Ok(()) => ok(request.id.clone(), json!(true)), + Ok(()) => ok( + request.id.clone(), + desktop_notification_delivered_to_system_result(), + ), Err(error) => failed(request.id.clone(), "host_error", error.to_string()), } } @@ -150,6 +157,14 @@ mod tests { assert_eq!(body.as_deref(), Some("作品已准备好 可以试玩")); } + #[test] + fn local_notification_success_result_reports_system_delivery() { + assert_eq!( + desktop_notification_delivered_to_system_result(), + json!({"action": "delivered_to_system"}) + ); + } + #[test] fn local_notification_payload_rejects_empty_and_control_text() { let mut empty = request("notification.showLocal"); diff --git a/apps/mobile-shell/scripts/check-config.mjs b/apps/mobile-shell/scripts/check-config.mjs index bde5255e6..7030d36b5 100644 --- a/apps/mobile-shell/scripts/check-config.mjs +++ b/apps/mobile-shell/scripts/check-config.mjs @@ -701,6 +701,7 @@ const sharedPayloadBoundaryImports = [ 'HOST_BRIDGE_IMPORT_DOCUMENT_MAX_BYTES', 'HOST_BRIDGE_IMPORT_IMAGE_MAX_BYTES', 'HOST_BRIDGE_IMPORT_TEXT_MAX_BYTES', + 'HOST_BRIDGE_LOCAL_NOTIFICATION_DELIVERED_TO_SYSTEM_RESULT', 'HOST_BRIDGE_MOBILE_LOCAL_NOTIFICATION_CHANNEL_ID', 'normalizeHostBridgeImportFileName', 'normalizeHostBridgeQrCodeValue', @@ -1576,7 +1577,8 @@ for (const notificationSnippet of [ 'normalizeHostBridgeLocalNotification(request.payload)', "invalidRequest('title is required')", 'showMobileLocalNotification(notification)', - 'ok(request, true)', + 'ok(request, await showMobileLocalNotification(notification))', + 'HOST_BRIDGE_LOCAL_NOTIFICATION_DELIVERED_TO_SYSTEM_RESULT', ]) { if (!notificationsSource.includes(notificationSnippet)) { throw new Error(`mobile shell notifications module is missing ${notificationSnippet}`); diff --git a/apps/mobile-shell/src/host-bridge/bridge.test.ts b/apps/mobile-shell/src/host-bridge/bridge.test.ts index e16988be1..9493ba19f 100644 --- a/apps/mobile-shell/src/host-bridge/bridge.test.ts +++ b/apps/mobile-shell/src/host-bridge/bridge.test.ts @@ -455,7 +455,7 @@ describe('handleMobileHostBridgeMessage', () => { }), ); - expectOk(response); + expect(expectOk(response).result).toBe(true); const openedUrl = new URL(openWebViewUrl.mock.calls[0]?.[0] as string); expect(openedUrl.origin).toBe('https://app.genarrative.world'); expect(openedUrl.pathname).toBe('/works/detail'); @@ -549,7 +549,7 @@ describe('handleMobileHostBridgeMessage', () => { const response = await send(request('app.reloadWebView')); - expectOk(response); + expect(expectOk(response).result).toBe(true); expect(reloadWebView).toHaveBeenCalledTimes(1); }); @@ -560,7 +560,7 @@ describe('handleMobileHostBridgeMessage', () => { }), ); - expectOk(response); + expect(expectOk(response).result).toBe(true); expect(Linking.canOpenURL).toHaveBeenCalledWith('https://example.com/path'); expect(Linking.openURL).toHaveBeenCalledWith('https://example.com/path'); }); @@ -702,7 +702,7 @@ describe('handleMobileHostBridgeMessage', () => { }), ); - expectOk(response); + expect(expectOk(response).result).toBe(true); expect(Clipboard.setStringAsync).toHaveBeenCalledWith('a'.repeat(100000)); }); @@ -724,7 +724,7 @@ describe('handleMobileHostBridgeMessage', () => { }), ); - expectOk(response); + expect(expectOk(response).result).toBe(true); expect(Haptics.impactAsync).toHaveBeenCalledWith( Haptics.ImpactFeedbackStyle.Heavy, ); @@ -758,7 +758,9 @@ describe('handleMobileHostBridgeMessage', () => { }), ); - expectOk(response); + expect(expectOk(response).result).toEqual({ + action: 'delivered_to_system', + }); expect(Notifications.getPermissionsAsync).toHaveBeenCalled(); expect(Notifications.requestPermissionsAsync).not.toHaveBeenCalled(); expect(Notifications.scheduleNotificationAsync).toHaveBeenCalledWith({ diff --git a/apps/mobile-shell/src/host-bridge/notifications.ts b/apps/mobile-shell/src/host-bridge/notifications.ts index 83ad682f9..7c219583e 100644 --- a/apps/mobile-shell/src/host-bridge/notifications.ts +++ b/apps/mobile-shell/src/host-bridge/notifications.ts @@ -2,6 +2,7 @@ import * as Notifications from 'expo-notifications'; import { Platform } from 'react-native'; import { + HOST_BRIDGE_LOCAL_NOTIFICATION_DELIVERED_TO_SYSTEM_RESULT, HOST_BRIDGE_MOBILE_LOCAL_NOTIFICATION_CHANNEL_ID, type HostBridgeError, type HostBridgeRequest, @@ -70,7 +71,7 @@ export async function showMobileLocalNotification( ? { channelId: HOST_BRIDGE_MOBILE_LOCAL_NOTIFICATION_CHANNEL_ID } : null, }); - return true; + return HOST_BRIDGE_LOCAL_NOTIFICATION_DELIVERED_TO_SYSTEM_RESULT; } export async function showMobileHostBridgeLocalNotification( @@ -81,6 +82,5 @@ export async function showMobileHostBridgeLocalNotification( throw invalidRequest('title is required'); } - await showMobileLocalNotification(notification); - return ok(request, true); + return ok(request, await showMobileLocalNotification(notification)); } diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index d6421e730..00de0cc7a 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -2798,6 +2798,13 @@ - 影响范围:`packages/shared/src/contracts/hostBridge.ts`、`packages/shared/src/contracts/hostBridge.test.ts`、`apps/mobile-shell/src/host-bridge/files.ts`、`apps/mobile-shell/scripts/check-config.mjs` 和宿主壳能力统一协议文档。 - 验证方式:`npm run mobile-shell:test`、`npm run mobile-shell:typecheck`、`npm run test -- packages/shared/src/contracts/hostBridge.test.ts`、`npm run check:native-shells`、`npm run check:encoding`、`git diff --check`。 +## 2026-06-20 本地通知结果语义收口 + +- 背景:Expo 和 Tauri 壳的 `notification.showLocal` 此前成功时返回裸 `true`,H5 只能理解为调用成功,容易被误读成“用户实际看见通知”;移动壳巡检也指出该能力真实语义应是系统调度 / 交付,而不是展示确认。 +- 决策:共享契约新增 `HOST_BRIDGE_LOCAL_NOTIFICATION_DELIVERED_TO_SYSTEM_RESULT`,结果为 `{ action: 'delivered_to_system' }`;Expo 和 Tauri 壳成功后返回该结构,H5 facade 接受结构化结果并暂兼容旧壳 `true`。该结果只表示通知已交给系统通知层,不承诺用户可见、点击或送达回执。 +- 影响范围:`packages/shared/src/contracts/hostBridge.ts`、`src/services/host-bridge/hostBridge.ts`、`apps/mobile-shell/src/host-bridge/notifications.ts`、`apps/desktop-shell/src-tauri/src/host_bridge/notifications.rs`、两端配置门禁、测试和宿主壳能力统一协议文档。 +- 验证方式:`npm run test -- packages/shared/src/contracts/hostBridge.test.ts src/services/host-bridge/hostBridge.test.ts`、`npm run mobile-shell:test`、`npm run desktop-shell:test`、`npm run check:native-shells`、`npm run check:encoding`、`git diff --check`。 + ## 2026-06-19 原生宿主二维码扫码超时单一来源 - 背景:二维码扫码属于真实相机交互,等待时间应长于普通宿主请求;此前 H5 `scanHostQrCode()` 直接手写 `timeoutMs: 60000`,会让扫码等待边界和共享 HostBridge 契约漂移。 diff --git a/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md b/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md index 3f8c7cdc5..4285cf3e1 100644 --- a/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md +++ b/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md @@ -65,7 +65,7 @@ Tauri 桌面壳启动时必须按 `label="main"` 解析 `tauri.conf.json` 主窗 - `readHostClipboardText()`:原生 App 宿主的受控剪贴板读取入口。H5 只能读取纯文本结果,宿主返回内容会按 HostBridge 契约限制到 100000 字符;Expo 移动壳通过 `expo-clipboard` 读取系统剪贴板文本,Tauri 桌面壳通过 Rust 侧 `clipboard-manager` 读取系统剪贴板文本。该能力不读取图片、HTML、文件列表或剪贴板监听事件,不把 Tauri / Expo 剪贴板插件 API 直接暴露给 H5;宿主未声明或读取失败时由 H5 视作失败并保留原流程。个人中心的邀请码和兑换码弹窗只在宿主声明 `clipboard.readText` 时显示“粘贴”,读取到的纯文本只填入现有输入框,不自动提交、不代表兑换成功。 - `requestHostHapticsImpact()`:原生 App 宿主的受控触觉反馈入口。Expo 移动壳通过 `haptics.impact` 调用 Expo Haptics,只接受 `light`、`medium`、`heavy` 三档 impact style,缺省为 `light`;H5 facade 发起请求前先按共享清单归一化 style,未知值不发往宿主,移动壳仍必须二次拒绝未知值且不触发设备反馈;H5 运行时点击反馈在 `native_app` 中优先请求宿主触觉,宿主不可用、拒绝或返回 unsupported 时继续回退到浏览器 `navigator.vibrate`。 移动壳的触觉反馈 payload 解析、style 归一、Expo style 映射和真实设备反馈调用都必须留在 `apps/mobile-shell/src/host-bridge/haptics.ts`,`dispatch.ts` 只把 `request.payload` 委托给该模块。 -- `showHostLocalNotification()`:原生 App 宿主的受控即时本地通知入口。H5 只能传必填 `title` 和可选 `body`,两者都会去除首尾空白、折叠普通空白、限制长度并拒绝控制字符;Expo 移动壳通过 `expo-notifications` 请求通知权限、创建 Android 本地通知 channel 并立刻调度本地通知,Android channel id 固定为共享契约 `HOST_BRIDGE_MOBILE_LOCAL_NOTIFICATION_CHANNEL_ID`;Tauri 桌面壳通过 Rust 侧 `tauri-plugin-notification` 先检查系统通知权限,处于 prompt 状态时只在 Rust 侧请求一次权限,最终授权后才发送系统通知。该能力不包含远程推送、token 注册、定时提醒、后台远程通知或任意通知插件透传,宿主未声明、权限拒绝或系统失败时由 H5 视作失败并继续主流程。当前 H5 只在现有草稿生成任务收口为完成或失败时请求即时本地通知;通知按草稿来源去重,同一草稿重新进入生成中后才允许再次通知,不改变队列状态、弹窗、作品架或后端裁决。平台壳同步层必须通过真实 `host_bridge_request` transport 测到 `notification.showLocal` 请求,不能只测模型文案或替换 facade。 +- `showHostLocalNotification()`:原生 App 宿主的受控即时本地通知入口。H5 只能传必填 `title` 和可选 `body`,两者都会去除首尾空白、折叠普通空白、限制长度并拒绝控制字符;Expo 移动壳通过 `expo-notifications` 请求通知权限、创建 Android 本地通知 channel 并立刻调度本地通知,Android channel id 固定为共享契约 `HOST_BRIDGE_MOBILE_LOCAL_NOTIFICATION_CHANNEL_ID`;Tauri 桌面壳通过 Rust 侧 `tauri-plugin-notification` 先检查系统通知权限,处于 prompt 状态时只在 Rust 侧请求一次权限,最终授权后才发送系统通知。成功结果统一为共享契约 `HOST_BRIDGE_LOCAL_NOTIFICATION_DELIVERED_TO_SYSTEM_RESULT`,只表示通知已交给系统通知层,不承诺用户一定看见或点击。该能力不包含远程推送、token 注册、定时提醒、后台远程通知或任意通知插件透传,宿主未声明、权限拒绝或系统失败时由 H5 视作失败并继续主流程。当前 H5 只在现有草稿生成任务收口为完成或失败时请求即时本地通知;通知按草稿来源去重,同一草稿重新进入生成中后才允许再次通知,不改变队列状态、弹窗、作品架或后端裁决。平台壳同步层必须通过真实 `host_bridge_request` transport 测到 `notification.showLocal` 请求,不能只测模型文案或替换 facade。 - `setHostAppTitle()`:原生 App 宿主的受控窗口标题入口。H5 主站会按当前平台阶段先同步 `document.title`,再通过 `app.setTitle` 请求宿主窗口标题同步;H5 facade 和 Tauri 桌面壳都必须按共享契约 `HOST_BRIDGE_APP_TITLE_MAX_LENGTH` 清洗标题,拒绝空值和控制字符,最多保留 80 个字符。Tauri 桌面壳支持该能力,Expo 移动壳不声明时静默忽略。 - `setHostAppBadgeCount()`:原生 App 宿主的受控应用角标入口。H5 只传 `0` 到共享契约 `HOST_BRIDGE_BADGE_COUNT_MAX` 之间的整数,`0` 表示清除角标;Expo 移动壳只在 iOS 声明 `app.setBadgeCount` 并通过 React Native `PushNotificationIOS` 设置应用图标角标,Android 不声明该能力;Tauri 桌面壳通过主窗口 `set_badge_count` 设置任务栏角标,底层平台不支持时返回明确错误,由 H5 视作失败并继续主流程。当前 H5 只把“可见作品架里未读的草稿生成完成更新”同步为角标数,同一个草稿有多个恢复 ID 时只计 1,已读、失败、生成中和不可见草稿不计入;宿主不支持或设置失败不改变 H5 红点、作品架或后端状态。平台壳同步层必须通过真实 `host_bridge_request` transport 测到 `app.setBadgeCount` 请求,保证未读计数模型和原生壳消费链路同时被门禁覆盖。 - `reloadHostWebView()`:原生 App 宿主的受控 WebView 刷新入口。H5 只能请求刷新当前承载主站的宿主 WebView;Expo 移动壳调用当前 `react-native-webview` 的 `reload()`,Tauri 桌面壳调用主 `WebviewWindow.reload()`。该能力不接受 payload,不开放任意 URL 导航、脚本执行、Tauri guest API 或 RN WebView ref;成功只表示宿主已发起刷新,刷新后当前 H5 上下文会卸载。`AuthGate` 在登录态从未登录变为已登录、或从已登录变为未登录时优先调用该能力刷新当前容器;宿主未声明、返回失败或不可用时再回退浏览器 `window.location.reload()`。 diff --git a/packages/shared/src/contracts/hostBridge.test.ts b/packages/shared/src/contracts/hostBridge.test.ts index f7c616685..f423b5582 100644 --- a/packages/shared/src/contracts/hostBridge.test.ts +++ b/packages/shared/src/contracts/hostBridge.test.ts @@ -21,6 +21,7 @@ import { HOST_BRIDGE_DESKTOP_NETWORK_CHECK_TIMEOUT_MS, HOST_BRIDGE_EVENTS, HOST_BRIDGE_IMPORT_DOCUMENT_MAX_BYTES, + HOST_BRIDGE_LOCAL_NOTIFICATION_DELIVERED_TO_SYSTEM_RESULT, HOST_BRIDGE_MAX_REQUEST_TIMEOUT_MS, HOST_BRIDGE_MOBILE_LOCAL_NOTIFICATION_CHANNEL_ID, HOST_BRIDGE_MOBILE_WEBVIEW_BLOCKED_DOWNLOAD_PROTOCOLS, @@ -512,6 +513,9 @@ describe('HostBridge shared contract helpers', () => { }); test('归一化宿主本地通知内容', () => { + expect(HOST_BRIDGE_LOCAL_NOTIFICATION_DELIVERED_TO_SYSTEM_RESULT).toEqual({ + action: 'delivered_to_system', + }); expect( normalizeHostBridgeLocalNotification({ title: ' 生成完成 ', diff --git a/packages/shared/src/contracts/hostBridge.ts b/packages/shared/src/contracts/hostBridge.ts index 19a4f646d..0da7a1385 100644 --- a/packages/shared/src/contracts/hostBridge.ts +++ b/packages/shared/src/contracts/hostBridge.ts @@ -1001,6 +1001,14 @@ export type LocalNotificationPayload = { body?: string; }; +export type LocalNotificationResult = { + action: 'delivered_to_system'; +}; + +export const HOST_BRIDGE_LOCAL_NOTIFICATION_DELIVERED_TO_SYSTEM_RESULT: LocalNotificationResult = { + action: 'delivered_to_system', +}; + export const HOST_BRIDGE_LOCAL_NOTIFICATION_TITLE_MAX_LENGTH = 80; export const HOST_BRIDGE_LOCAL_NOTIFICATION_BODY_MAX_LENGTH = 240; export const HOST_BRIDGE_MOBILE_LOCAL_NOTIFICATION_CHANNEL_ID = diff --git a/src/services/host-bridge/hostBridge.test.ts b/src/services/host-bridge/hostBridge.test.ts index 8e3bc4caf..0b5c59364 100644 --- a/src/services/host-bridge/hostBridge.test.ts +++ b/src/services/host-bridge/hostBridge.test.ts @@ -1464,6 +1464,46 @@ describe('hostBridge', () => { ).resolves.toBe(false); }); + test('原生 App 宿主本地通知接受结构化交付结果', async () => { + const invoke = vi.fn( + async (_command: string, args?: Record) => { + const request = (args as { request: { id: string } }).request; + return { + bridge: 'GenarrativeHostBridge', + version: 1, + id: request.id, + ok: true, + result: { action: 'delivered_to_system' }, + }; + }, + ); + window.history.replaceState( + null, + '', + nativeAppPath(['notification.showLocal']), + ); + window.__TAURI__ = { + core: { + invoke: asTauriInvoke(invoke), + }, + }; + + await expect( + showHostLocalNotification({ + title: '生成完成', + }), + ).resolves.toBe(true); + + expect(invoke).toHaveBeenCalledWith('host_bridge_request', { + request: expect.objectContaining({ + method: 'notification.showLocal', + payload: { + title: '生成完成', + }, + }), + }); + }); + test('原生 App 宿主拒绝非法本地通知 payload', async () => { const invoke = vi.fn(); window.history.replaceState( diff --git a/src/services/host-bridge/hostBridge.ts b/src/services/host-bridge/hostBridge.ts index 71644886e..a5125cd30 100644 --- a/src/services/host-bridge/hostBridge.ts +++ b/src/services/host-bridge/hostBridge.ts @@ -17,6 +17,7 @@ import type { HostBridgeMethod, HostBridgeRuntimeResult, LocalNotificationPayload, + LocalNotificationResult, NavigationCanGoBackEventPayload, NetworkStatusResult, OpenExternalUrlPayload, @@ -241,6 +242,34 @@ async function requestNativeHostBoolean( } } +function isLocalNotificationDeliveredToSystemResult( + result: unknown, +): result is LocalNotificationResult { + return ( + !!result && + typeof result === 'object' && + (result as Partial).action === + 'delivered_to_system' + ); +} + +async function requestNativeHostLocalNotification( + payload: LocalNotificationPayload, +) { + try { + const result = await requestNativeAppHostBridge( + 'notification.showLocal', + payload, + ); + return result === true || isLocalNotificationDeliveredToSystemResult(result); + } catch (error) { + if (isUnsupportedHostBridgeError(error)) { + return false; + } + throw error; + } +} + function resolveLocation(context: HostRuntimeContext) { return ( context.location ?? (typeof window !== 'undefined' ? window.location : null) @@ -1072,10 +1101,7 @@ export async function showHostLocalNotification( } try { - return await requestNativeHostBoolean( - 'notification.showLocal', - notification, - ); + return await requestNativeHostLocalNotification(notification); } catch { return false; }