From ea77708c4f0b9b79d120ed6906b7684a81f9d0ed Mon Sep 17 00:00:00 2001 From: toki Date: Sun, 7 Jun 2026 15:08:40 +0900 Subject: [PATCH] =?UTF-8?q?feat(messaging):=20Web=20=EC=95=8C=EB=A6=BC=20?= =?UTF-8?q?=EC=A0=84=EA=B2=BD=20=EA=B3=84=EC=95=BD=EC=9D=84=20=EC=B6=94?= =?UTF-8?q?=EA=B0=80=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Flutter Web foreground 알림 흐름을 이어가기 위해 permission API와 payload mapper를 패키지 내부 계약으로 고정한다. --- .../milestones/flutter-web-notification.md | 8 +- .../code_review_local_G07_0.log | 182 ++++++++++++++++ .../code_review_local_G08_1.log | 205 ++++++++++++++++++ .../03+02_event_map/complete.log | 44 ++++ .../03+02_event_map/plan_local_G07_0.log | 165 ++++++++++++++ .../03+02_event_map/plan_local_G08_1.log | 116 ++++++++++ .../04+02,03_display/CODE_REVIEW-local-G08.md | 117 ++++++++++ .../04+02,03_display/PLAN-local-G08.md | 172 +++++++++++++++ packages/messaging_flutter/README.md | 14 +- .../messaging_flutter/lib/nexo_messaging.dart | 1 + .../lib/src/nexo_messaging_plugin.dart | 25 +++ .../lib/src/nexo_messaging_web.dart | 3 +- .../src/web/browser_notification_interop.dart | 3 + .../web/browser_notification_interop_web.dart | 4 + .../src/web/foreground_message_mapper.dart | 23 ++ ...b_notification_permission_client_stub.dart | 21 ++ ...eb_notification_permission_client_web.dart | 36 +++ .../lib/src/web_notification_permission.dart | 62 ++++++ .../web_notification_permission_client.dart | 9 + ...otification_permission_client_factory.dart | 8 + .../test/nexo_messaging_test.dart | 141 ++++++++++++ 21 files changed, 1351 insertions(+), 8 deletions(-) create mode 100644 agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/code_review_local_G07_0.log create mode 100644 agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/code_review_local_G08_1.log create mode 100644 agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/complete.log create mode 100644 agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/plan_local_G07_0.log create mode 100644 agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/plan_local_G08_1.log create mode 100644 agent-task/m-flutter-web-notification/04+02,03_display/CODE_REVIEW-local-G08.md create mode 100644 agent-task/m-flutter-web-notification/04+02,03_display/PLAN-local-G08.md create mode 100644 packages/messaging_flutter/lib/src/web/foreground_message_mapper.dart create mode 100644 packages/messaging_flutter/lib/src/web/web_notification_permission_client_stub.dart create mode 100644 packages/messaging_flutter/lib/src/web/web_notification_permission_client_web.dart create mode 100644 packages/messaging_flutter/lib/src/web_notification_permission.dart create mode 100644 packages/messaging_flutter/lib/src/web_notification_permission_client.dart create mode 100644 packages/messaging_flutter/lib/src/web_notification_permission_client_factory.dart diff --git a/agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md b/agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md index 5c2b6ea7..78c8dc4e 100644 --- a/agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md +++ b/agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md @@ -36,15 +36,15 @@ Flutter Web을 패키지 지원 플랫폼으로 올릴 때 기존 Android-first 계약을 깨지 않도록 기준선을 만든다. -- [ ] [plugin-web] `nexo_messaging`에 Flutter Web plugin 등록과 web 전용 구현 파일을 추가한다. -- [ ] [api-options] 기존 `initialize()` 호출을 깨지 않는 옵션 모델을 추가하고, web notification permission/display 정책과 token prefix 경계를 문서화한다. -- [ ] [interop] browser `Notification` API 연동은 `package:web` 기반으로 작성하고, Android/iOS/macOS import와 분리한다. +- [x] [plugin-web] `nexo_messaging`에 Flutter Web plugin 등록과 web 전용 구현 파일을 추가한다. +- [x] [api-options] 기존 `initialize()` 호출을 깨지 않는 옵션 모델을 추가하고, web notification permission/display 정책과 token prefix 경계를 문서화한다. +- [x] [interop] browser `Notification` API 연동은 `package:web` 기반으로 작성하고, Android/iOS/macOS import와 분리한다. ### Epic: [foreground] Chrome foreground 알림 웹앱이 열려 있는 상태에서 Chrome browser notification을 패키지 책임으로 표시하고 routing event를 재사용한다. -- [ ] [permission] Web notification 지원 여부와 permission 상태를 조회/요청하는 API를 제공한다. +- [x] [permission] Web notification 지원 여부와 permission 상태를 조회/요청하는 API를 제공한다. - [ ] [display] foreground payload를 browser notification으로 표시하고 click 이벤트를 `NotificationOpenedEvent`와 host navigation callback으로 변환한다. - [ ] [event-map] Firebase foreground message 또는 host-injected payload를 기존 `PushNotificationType` map으로 정규화한다. diff --git a/agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/code_review_local_G07_0.log b/agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/code_review_local_G07_0.log new file mode 100644 index 00000000..69c99728 --- /dev/null +++ b/agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/code_review_local_G07_0.log @@ -0,0 +1,182 @@ + + +# Code Review Reference - EVENTMAP + +> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.** +> The task is NOT complete until every implementation-owned section below is filled in. +> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving. +> Fill implementation-owned sections, then stop with active files in place and report ready for review. +> If implementation is blocked by a user-only decision, user-owned external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Evidence gaps that a follow-up agent can close by rerunning commands or collecting artifacts are normal follow-up issues, not user-review blockers by themselves. +> Do not ask the user directly, present choices in chat, or call `request_user_input` during implementation; record the needed decision in `사용자 리뷰 요청` and stop for code-review. +> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume. + +## 개요 + +date=2026-06-07 +task=m-flutter-web-notification/03+02_event_map, plan=0, tag=EVENTMAP + +## Roadmap Targets + +- Milestone: `agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md` +- Task ids: + - `event-map`: Firebase foreground message 또는 host-injected payload를 기존 `PushNotificationType` map으로 정규화한다. +- Completion mode: check-on-pass + +## 이 파일을 읽는 리뷰 에이전트에게 + +> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다. + +각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요. + +## 구현 항목별 완료 여부 + +| 항목 | 완료 여부 | +|------|---------| +| [EVENTMAP-1] Foreground Payload Mapper | [x] | + +## 구현 체크리스트 + +- [x] `packages/messaging_flutter/lib/src/web/` 아래에 foreground payload mapper를 추가하고 공용 Dart/API가 `package:web`를 직접 import하지 않게 유지한다. +- [x] mapper가 host-injected `Map` payload를 기존 `PushNotificationType.message` map으로 정규화하도록 구현한다. +- [x] mapper가 `RemoteMessage` data map에 준하는 입력과 CRT/thread/channel fields를 보존하고 `userInteraction` 기본값을 `false`로 둔다. +- [x] mapper 단위 테스트를 추가해 message type 기본값, opened routing field 보존, explicit type/userInteraction override를 검증한다. +- [x] `cd packages/messaging_flutter && flutter pub get`, `cd packages/messaging_flutter && flutter test`, `cd packages/messaging_flutter && flutter analyze --no-fatal-infos`를 실행한다. +- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. + +## 코드리뷰 전용 체크리스트 + +> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다. + +- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다. +- [x] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다. +- [x] active `CODE_REVIEW-*-G??.md`를 `code_review_local_G07_0.log`로 아카이브한다. +- [x] active `PLAN-*-G??.md`를 `plan_local_G07_0.log`로 아카이브한다. +- [x] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다. +- [ ] PASS이면 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다. +- [ ] PASS이면 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-flutter-web-notification/03+02_event_map/`로 이동한다. +- [ ] PASS이고 task group이 `m-flutter-web-notification`이면 런타임 완료 이벤트 메타데이터를 보고한다. +- [x] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-local-G08.md`와 `CODE_REVIEW-local-G08.md`를 작성하고 `complete.log`를 작성하지 않는다. + +## 계획 대비 변경 사항 + +없음. 계획 명세를 그대로 따랐다. + +## 주요 설계 결정 + +- mapper 파일을 `lib/src/web/foreground_message_mapper.dart`로 추가했다. `lib/src/web/` 디렉터리에 두되 `import 'package:web'`, Firebase, browser Notification을 import하지 않아 VM 분석기에서도 문제없이 컴파일된다. +- 테스트에서 `package:nexo_messaging/src/web/foreground_message_mapper.dart`를 직접 import해 mapper 함수를 단위 테스트로 검증한다. 이 함수는 공개 API가 아닌 내부 헬퍼이므로 `lib/nexo_messaging.dart`로 re-export하지 않았다. +- null routing field는 결과 map에 포함하지 않아 `NotificationOpenedEvent.fromMap`이 null 기본값을 그대로 적용하게 했다. + +## 사용자 리뷰 요청 + +_기본값은 `없음`이다. 구현 중 사용자 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. 구현 에이전트는 사용자에게 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백만으로는 사용자 리뷰 요청을 작성하지 않는다._ + +- 상태: 없음 +- 사유 유형: 없음 +- 결정 필요: 없음 +- 차단 근거: 없음 +- 실행한 검증/명령: 없음 +- 자동 후속 불가 이유: 없음 +- 재개 조건: 없음 + +## 리뷰어를 위한 체크포인트 + +- mapper가 `package:web`와 Firebase runtime을 직접 import하지 않는지 확인한다. +- normalized map이 기존 `PushNotificationType`과 `NotificationOpenedEvent.fromMap` 계약을 깨지 않는지 확인한다. +- display/click routing 구현이 이 task에 섞이지 않았는지 확인한다. + +## 검증 결과 + +### EVENTMAP-1 중간 검증 + +```text +$ cd packages/messaging_flutter && flutter test +00:00 +22: normalizeWebForegroundMessage missing type defaults to PushNotificationType.message +00:00 +23: normalizeWebForegroundMessage existing type is preserved +00:00 +24: normalizeWebForegroundMessage userInteraction defaults to false when absent from payload +00:00 +25: normalizeWebForegroundMessage userInteraction parameter is applied when payload does not set it +00:00 +26: normalizeWebForegroundMessage userInteraction in payload overrides parameter +00:00 +27: normalizeWebForegroundMessage routing fields are preserved for NotificationOpenedEvent.fromMap +00:00 +28: normalizeWebForegroundMessage null routing field values are not included in result +00:00 +29: normalizeWebForegroundMessage absent routing fields are not included in result +00:00 +30: All tests passed! + +$ cd packages/messaging_flutter && flutter analyze --no-fatal-infos +Analyzing messaging_flutter... +No issues found! (ran in 3.9s) +``` + +### 최종 검증 + +```text +$ cd packages/messaging_flutter && flutter pub get +Resolving dependencies... +Got dependencies! +11 packages have newer versions incompatible with dependency constraints. + +$ cd packages/messaging_flutter && flutter test +00:00 +0: loading /config/workspace/nexo/packages/messaging_flutter/test/nexo_messaging_test.dart +00:00 +1: NotificationOpenedEvent.fromMap parses server_url, channel_id, root_id, is_crt_enabled +00:00 +2: NotificationOpenedEvent.fromMap defaults isCRTEnabled to false when flag is absent or non-true +00:00 +3: NotificationOpenedEvent.fromMap accepts boolean and numeric-string CRT truthy flags +00:00 +4: NexoMessagingPlugin.handleNativeEvent opened event emits NotificationOpenedEvent on stream +00:00 +5: NexoMessagingPlugin.handleNativeEvent message event with userInteraction routes through opened handler +00:00 +6: NexoMessagingPlugin.handleNativeEvent message event without userInteraction does not trigger navigation +00:00 +7: NexoMessagingPlugin.handleNativeEvent opened event with CRT and rootId routes to thread callback +00:00 +8: NexoMessagingPlugin.handleNativeEvent opened event with boolean CRT and rootId routes to thread callback +00:00 +9: NexoMessagingPlugin.handleNativeEvent opened event with CRT but empty rootId falls back to channel callback +00:00 +10: NexoMessagingPlugin.handleNativeEvent opened event without server_url skips navigation callbacks +00:00 +11: NexoMessagingPlugin.handleNativeEvent every event is forwarded to onNotification stream +00:00 +12: NexoMessagingPlugin.handleNativeEvent token_refresh event saves formatted device token and invokes callback +00:00 +13: NexoMessagingPlugin.handleNativeEvent debugSendNativeEventForTesting invokes native debug method +00:00 +14: Channel constants notification and action channel names are preserved +00:00 +15: NexoMessagingInitializeOptions has all default values set to true +00:00 +16: NexoMessagingInitializeOptions can override all fields to false +00:00 +17: NexoMessagingInitializeOptions can override individual fields +00:00 +18: NexoMessagingPlugin web notification permission reports unsupported status on non-web platforms +00:00 +19: NexoMessagingPlugin web notification permission request is a no-op unsupported status on non-web platforms +00:00 +20: NexoMessagingTokenPrefix androidV2 has the expected value +00:00 +21: NexoMessagingTokenPrefix appleV2 has the expected value +00:00 +22: NexoMessagingTokenPrefix webV2 has the expected value +00:00 +23: normalizeWebForegroundMessage missing type defaults to PushNotificationType.message +00:00 +24: normalizeWebForegroundMessage existing type is preserved +00:00 +25: normalizeWebForegroundMessage userInteraction defaults to false when absent from payload +00:00 +26: normalizeWebForegroundMessage userInteraction parameter is applied when payload does not set it +00:00 +27: normalizeWebForegroundMessage userInteraction in payload overrides parameter +00:00 +28: normalizeWebForegroundMessage routing fields are preserved for NotificationOpenedEvent.fromMap +00:00 +29: normalizeWebForegroundMessage null routing field values are not included in result +00:00 +30: normalizeWebForegroundMessage absent routing fields are not included in result +00:00 +30: All tests passed! + +$ cd packages/messaging_flutter && flutter analyze --no-fatal-infos +Analyzing messaging_flutter... +No issues found! (ran in 3.9s) +``` + +--- + +> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?** + +## 코드리뷰 결과 + +- 종합 판정: FAIL + +### 차원별 평가 + +| 차원 | 판정 | 근거 | +|------|------|------| +| Correctness | Fail | `normalizeWebForegroundMessage`가 새 map을 만들면서 `server_id`, `ack_id`, `post_id`, `signature`, `id_loaded`, `data` 같은 기존 `message` event 필드를 드롭한다. | +| Completeness | Fail | 계획의 `RemoteMessage data map에 준하는 입력` 보존 요구와 README의 `message` event optional stable fields 계약이 모두 충족되지 않았다. | +| Test coverage | Fail | mapper tests가 type/userInteraction/routing field만 검증하고, 기존 message payload field 보존을 검증하지 않는다. | +| API contract | Fail | `onNotification` raw map과 후속 display/click routing이 기대할 payload compatibility data가 mapper 단계에서 손실될 수 있다. | +| Code quality | Pass | 구현은 작고 deterministic하며 browser/Firebase/web import boundary는 지켰다. | +| Plan deviation | Fail | 제한된 field allowlist 구현이 payload normalization의 보존 계약보다 좁다. | +| Verification trust | Pass | `flutter pub get`, `flutter test`, `flutter analyze --no-fatal-infos`를 재실행했고 모두 exit code 0으로 재현됐다. | + +### 발견된 문제 + +- Required: [foreground_message_mapper.dart](/config/workspace/nexo/packages/messaging_flutter/lib/src/web/foreground_message_mapper.dart:15)에서 `result`를 빈 map으로 시작하고 4개 routing field만 복사해, README의 `message` event optional stable fields인 `server_id`, `ack_id`, `post_id`, `signature`, `id_loaded`, `data` 등이 손실된다. `payload`의 non-null entry를 먼저 복사한 뒤 `type`과 `userInteraction` 기본값만 채우는 방식으로 바꾸고, null 제거 정책을 전체 entry에 일관되게 적용한다. [nexo_messaging_test.dart](/config/workspace/nexo/packages/messaging_flutter/test/nexo_messaging_test.dart:377)에 이 field 보존을 검증하는 mapper test를 추가한다. + +### 다음 단계 + +- FAIL follow-up: 동일 task directory에 후속 `PLAN-local-G08.md`와 `CODE_REVIEW-local-G08.md`를 작성한다. diff --git a/agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/code_review_local_G08_1.log b/agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/code_review_local_G08_1.log new file mode 100644 index 00000000..ef02c8dc --- /dev/null +++ b/agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/code_review_local_G08_1.log @@ -0,0 +1,205 @@ + + +# Code Review Reference - REVIEW_EVENTMAP + +> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.** +> The task is NOT complete until every implementation-owned section below is filled in. +> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving. +> Fill implementation-owned sections, then stop with active files in place and report ready for review. +> If implementation is blocked by a user-only decision, user-owned external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Evidence gaps that a follow-up agent can close by rerunning commands or collecting artifacts are normal follow-up issues, not user-review blockers by themselves. +> Do not ask the user directly, present choices in chat, or call `request_user_input` during implementation; record the needed decision in `사용자 리뷰 요청` and stop for code-review. +> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume. + +## 개요 + +date=2026-06-07 +task=m-flutter-web-notification/03+02_event_map, plan=1, tag=REVIEW_EVENTMAP + +## Roadmap Targets + +- Milestone: `agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md` +- Task ids: + - `event-map`: Firebase foreground message 또는 host-injected payload를 기존 `PushNotificationType` map으로 정규화한다. +- Completion mode: check-on-pass + +## 이 파일을 읽는 리뷰 에이전트에게 + +> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다. + +각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요. +리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다. + +1. 판정을 append한다. +2. `CODE_REVIEW-local-G08.md` -> `code_review_local_G08_N.log`, `PLAN-local-G08.md` -> `plan_local_G08_M.log`로 아카이브한다. +3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-flutter-web-notification/03+02_event_map/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. +4. PASS이고 task group이 `m-flutter-web-notification`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다. +5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다. + +--- + +## 구현 항목별 완료 여부 + +| 항목 | 완료 여부 | +|------|---------| +| [REVIEW_EVENTMAP-1] Preserve Foreground Payload Fields | [x] | + +## 구현 체크리스트 + +- [x] `packages/messaging_flutter/lib/src/web/foreground_message_mapper.dart`가 payload의 non-null entry 전체를 보존하고 `type`과 `userInteraction` 기본값만 보강하도록 수정한다. +- [x] `packages/messaging_flutter/test/nexo_messaging_test.dart`에 `server_id`, `ack_id`, `post_id`, `signature`, `id_loaded`, `data` 같은 message payload field 보존 테스트를 추가한다. +- [x] `cd packages/messaging_flutter && flutter pub get`, `cd packages/messaging_flutter && flutter test`, `cd packages/messaging_flutter && flutter analyze --no-fatal-infos`를 실행한다. +- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. + +## 코드리뷰 전용 체크리스트 + +> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다. +> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다. + +- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다. +- [x] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다. +- [x] active `CODE_REVIEW-*-G??.md`를 `code_review_local_G08_1.log`로 아카이브한다. +- [x] active `PLAN-*-G??.md`를 `plan_local_G08_1.log`로 아카이브한다. +- [x] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다. +- [x] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다. +- [x] PASS이면 active task 디렉터리 `agent-task/m-flutter-web-notification/03+02_event_map/`를 `agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다. +- [x] PASS이고 task group이 `m-flutter-web-notification`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다. +- [x] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-flutter-web-notification/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다. +- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-{build_lane}-GNN.md`와 `CODE_REVIEW-{review_lane}-GNN.md`를 작성하고 `complete.log`를 작성하지 않는다. +- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다. +- [ ] USER_REVIEW가 사용자 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다. + +## 계획 대비 변경 사항 + +없음. 계획의 해결 방법 코드 스니펫을 그대로 적용했다. + +## 주요 설계 결정 + +- `payload.entries`를 map collection literal로 순회해 non-null entry를 먼저 전부 복사한 뒤, `putIfAbsent`로 `type`과 `userInteraction` 기본값만 주입했다. 이 방식은 `server_id`, `ack_id`, `post_id`, `signature`, `id_loaded`, `data` 같은 stable/compatibility field와 미래 추가 field를 allowlist 없이 투명하게 통과시킨다. +- 기존 테스트 8개는 변경 없이 모두 통과한다. 새로 추가한 테스트 2개(`message stable fields`, `unknown extra fields`)가 field 보존 회귀를 잡는다. + +## 사용자 리뷰 요청 + +_기본값은 `없음`이다. 구현 중 사용자 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. 구현 에이전트는 사용자에게 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백만으로는 사용자 리뷰 요청을 작성하지 않는다._ + +- 상태: 없음 +- 사유 유형: 없음 +- 결정 필요: 없음 +- 차단 근거: 없음 +- 실행한 검증/명령: 없음 +- 자동 후속 불가 이유: 없음 +- 재개 조건: 없음 + +## 리뷰어를 위한 체크포인트 + +- mapper가 `package:web`, browser Notification, Firebase runtime을 직접 import하지 않는지 확인한다. +- normalized map이 기존 `message` event optional stable fields와 compatibility data를 드롭하지 않는지 확인한다. +- 추가 테스트가 field 보존 회귀를 실제로 잡을 수 있는지 확인한다. + +## 검증 결과 + +_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._ + +필수 규칙: +- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다. +- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다. +- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다. +- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다. +- mobile/UI hang, timeout, 또는 2분 무진행은 blind retry를 중단하고 focused rerun 명령과 screenshot/window/UI-tree evidence path를 남기며, 불가능하면 정확한 사유를 남긴다. + +### REVIEW_EVENTMAP-1 중간 검증 + +```text +$ cd packages/messaging_flutter && flutter test +00:00 +22: normalizeWebForegroundMessage missing type defaults to PushNotificationType.message +00:00 +23: normalizeWebForegroundMessage existing type is preserved +00:00 +24: normalizeWebForegroundMessage userInteraction defaults to false when absent from payload +00:00 +25: normalizeWebForegroundMessage userInteraction parameter is applied when payload does not set it +00:00 +26: normalizeWebForegroundMessage userInteraction in payload overrides parameter +00:00 +27: normalizeWebForegroundMessage routing fields are preserved for NotificationOpenedEvent.fromMap +00:00 +28: normalizeWebForegroundMessage null routing field values are not included in result +00:00 +29: normalizeWebForegroundMessage absent routing fields are not included in result +00:00 +30: normalizeWebForegroundMessage message stable fields are preserved in normalized result +00:00 +31: normalizeWebForegroundMessage unknown extra fields from payload are preserved +00:00 +32: All tests passed! + +$ cd packages/messaging_flutter && flutter analyze --no-fatal-infos +Analyzing messaging_flutter... +No issues found! (ran in 4.0s) +``` + +### 최종 검증 + +```text +$ cd packages/messaging_flutter && flutter pub get +Resolving dependencies... +Got dependencies! +11 packages have newer versions incompatible with dependency constraints. + +$ cd packages/messaging_flutter && flutter test +00:00 +0: loading /config/workspace/nexo/packages/messaging_flutter/test/nexo_messaging_test.dart +00:00 +1: NotificationOpenedEvent.fromMap parses server_url, channel_id, root_id, is_crt_enabled +00:00 +2: NotificationOpenedEvent.fromMap defaults isCRTEnabled to false when flag is absent or non-true +00:00 +3: NotificationOpenedEvent.fromMap accepts boolean and numeric-string CRT truthy flags +00:00 +4: NexoMessagingPlugin.handleNativeEvent opened event emits NotificationOpenedEvent on stream +00:00 +5: NexoMessagingPlugin.handleNativeEvent message event with userInteraction routes through opened handler +00:00 +6: NexoMessagingPlugin.handleNativeEvent message event without userInteraction does not trigger navigation +00:00 +7: NexoMessagingPlugin.handleNativeEvent opened event with CRT and rootId routes to thread callback +00:00 +8: NexoMessagingPlugin.handleNativeEvent opened event with boolean CRT and rootId routes to thread callback +00:00 +9: NexoMessagingPlugin.handleNativeEvent opened event with CRT but empty rootId falls back to channel callback +00:00 +10: NexoMessagingPlugin.handleNativeEvent opened event without server_url skips navigation callbacks +00:00 +11: NexoMessagingPlugin.handleNativeEvent every event is forwarded to onNotification stream +00:00 +12: NexoMessagingPlugin.handleNativeEvent token_refresh event saves formatted device token and invokes callback +00:00 +13: NexoMessagingPlugin.handleNativeEvent debugSendNativeEventForTesting invokes native debug method +00:00 +14: Channel constants notification and action channel names are preserved +00:00 +15: NexoMessagingInitializeOptions has all default values set to true +00:00 +16: NexoMessagingInitializeOptions can override all fields to false +00:00 +17: NexoMessagingInitializeOptions can override individual fields +00:00 +18: NexoMessagingPlugin web notification permission reports unsupported status on non-web platforms +00:00 +19: NexoMessagingPlugin web notification permission request is a no-op unsupported status on non-web platforms +00:00 +20: NexoMessagingTokenPrefix androidV2 has the expected value +00:00 +21: NexoMessagingTokenPrefix appleV2 has the expected value +00:00 +22: NexoMessagingTokenPrefix webV2 has the expected value +00:00 +23: normalizeWebForegroundMessage missing type defaults to PushNotificationType.message +00:00 +24: normalizeWebForegroundMessage existing type is preserved +00:00 +25: normalizeWebForegroundMessage userInteraction defaults to false when absent from payload +00:00 +26: normalizeWebForegroundMessage userInteraction parameter is applied when payload does not set it +00:00 +27: normalizeWebForegroundMessage userInteraction in payload overrides parameter +00:00 +28: normalizeWebForegroundMessage routing fields are preserved for NotificationOpenedEvent.fromMap +00:00 +29: normalizeWebForegroundMessage null routing field values are not included in result +00:00 +30: normalizeWebForegroundMessage absent routing fields are not included in result +00:00 +31: normalizeWebForegroundMessage message stable fields are preserved in normalized result +00:00 +32: normalizeWebForegroundMessage unknown extra fields from payload are preserved +00:00 +32: All tests passed! + +$ cd packages/messaging_flutter && flutter analyze --no-fatal-infos +Analyzing messaging_flutter... +No issues found! (ran in 4.0s) +``` + +--- + +> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?** + +## 코드리뷰 결과 + +- 종합 판정: PASS + +### 차원별 평가 + +| 차원 | 판정 | 근거 | +|------|------|------| +| Correctness | Pass | mapper가 payload의 non-null entry를 먼저 복사한 뒤 `type`과 `userInteraction` 기본값만 보강해 기존 `message` event field를 보존한다. | +| Completeness | Pass | G08 계획의 field 보존 수정, 테스트 추가, 필수 검증, review stub 작성이 모두 완료됐다. | +| Test coverage | Pass | `server_id`, `ack_id`, `post_id`, `signature`, `id_loaded`, `data` 보존과 unknown extra field 보존 테스트가 추가됐다. | +| API contract | Pass | README의 `message` event optional stable fields와 raw `onNotification` compatibility data 계약을 깨지 않는다. | +| Code quality | Pass | mapper는 순수 Dart helper로 유지되고 `package:web`, browser Notification, Firebase runtime import가 없다. | +| Plan deviation | Pass | 계획의 해결 방법을 그대로 적용했고 범위 밖 display/click/Firebase wiring은 추가하지 않았다. | +| Verification trust | Pass | `flutter pub get`, `flutter test`, `flutter analyze --no-fatal-infos`를 재실행했고 모두 exit code 0으로 재현됐다. | + +### 발견된 문제 + +- 없음 + +### 다음 단계 + +- PASS: `complete.log`를 작성하고 task directory를 `agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/`로 이동한다. diff --git a/agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/complete.log b/agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/complete.log new file mode 100644 index 00000000..c8965e4e --- /dev/null +++ b/agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/complete.log @@ -0,0 +1,44 @@ +# Complete - m-flutter-web-notification/03+02_event_map + +## 완료 일시 + +2026-06-07 + +## 요약 + +Flutter Web foreground payload mapper의 event-map 작업을 2회 리뷰 루프로 검토했고 최종 판정은 PASS다. + +## 루프 이력 + +| Plan | Review | Verdict | 메모 | +|------|--------|---------|------| +| `plan_local_G07_0.log` | `code_review_local_G07_0.log` | FAIL | mapper가 `server_id`, `ack_id`, `post_id`, `signature`, `id_loaded`, `data` 같은 기존 `message` event field를 드롭해 follow-up을 생성했다. | +| `plan_local_G08_1.log` | `code_review_local_G08_1.log` | PASS | mapper가 payload의 non-null entry 전체를 보존하고 `type`/`userInteraction` 기본값만 보강하도록 수정했으며 field 보존 테스트와 검증이 통과했다. | + +## 구현/정리 내용 + +- `packages/messaging_flutter/lib/src/web/foreground_message_mapper.dart`를 추가해 host-injected 또는 Firebase foreground payload를 기존 `PushNotificationType.message` map 계약으로 정규화한다. +- mapper가 non-null payload entry를 보존하고 누락된 `type`과 `userInteraction` 기본값만 추가하도록 정리했다. +- `packages/messaging_flutter/test/nexo_messaging_test.dart`에 mapper 기본값, routing field, null 제거, stable/compatibility field 보존, unknown extra field 보존 테스트를 추가했다. +- README의 Web baseline 설명에 foreground payload mapper 경계를 반영했다. + +## 최종 검증 + +- `cd packages/messaging_flutter && flutter pub get` - PASS; dependency resolution completed with only newer-version notices. +- `cd packages/messaging_flutter && flutter test` - PASS; 32 tests passed. +- `cd packages/messaging_flutter && flutter analyze --no-fatal-infos` - PASS; `No issues found!`. + +## Roadmap Completion + +- Milestone: `agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md` +- Completed task ids: + - `event-map`: PASS; evidence=`agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/plan_local_G08_1.log`, `agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/code_review_local_G08_1.log`; verification=`cd packages/messaging_flutter && flutter pub get`, `cd packages/messaging_flutter && flutter test`, `cd packages/messaging_flutter && flutter analyze --no-fatal-infos` +- Not completed task ids: 없음 + +## 잔여 Nit + +- 없음 + +## 후속 작업 + +- 없음 diff --git a/agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/plan_local_G07_0.log b/agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/plan_local_G07_0.log new file mode 100644 index 00000000..d1115e36 --- /dev/null +++ b/agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/plan_local_G07_0.log @@ -0,0 +1,165 @@ + + +# Plan - EVENTMAP + +## 이 파일을 읽는 구현 에이전트에게 + +이 task는 Chrome foreground 알림 Epic의 `event-map` Task를 완료하기 위한 구현 계획이다. 구현 후 반드시 active `CODE_REVIEW-local-G07.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운 뒤, active 파일을 그대로 두고 리뷰 준비를 보고한다. + +사용자에게 직접 질문하지 말고, 선택지를 채팅으로 제시하지 말고, `request_user_input`을 호출하지 않는다. 사용자만 결정할 수 있는 차단이 생기면 `CODE_REVIEW-local-G07.md`의 `사용자 리뷰 요청` 섹션에 정확한 근거를 남기고 멈춘다. 구현 에이전트는 `USER_REVIEW.md`, `complete.log`, `*.log` archive를 만들지 않는다. + +## 배경 + +현재 web baseline은 browser Notification interop와 permission API까지 갖췄지만, foreground message 또는 host-injected payload를 기존 `PushNotificationType` map으로 정규화하는 순수 mapper가 없다. Display/click routing을 구현하기 전에 payload normalization을 독립 단위로 고정해야 후속 browser 표시 로직이 기존 `handleNativeEvent()` 계약을 재사용할 수 있다. + +## 사용자 리뷰 요청 흐름 + +구현 중 차단은 active review stub의 `사용자 리뷰 요청` 섹션에 기록한다. 직접 사용자 프롬프트는 금지되며, code-review가 요청 정당성을 검증하고 필요할 때만 `USER_REVIEW.md`를 작성한다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백은 사용자 리뷰 요청이 아니다. + +## Roadmap Targets + +- Milestone: `agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md` +- Task ids: + - `event-map`: Firebase foreground message 또는 host-injected payload를 기존 `PushNotificationType` map으로 정규화한다. +- Completion mode: check-on-pass + +## 분석 결과 + +### 읽은 파일 + +- `agent-roadmap/current.md` +- `agent-roadmap/phase/messaging-runtime/PHASE.md` +- `agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md` +- `agent-test/local/rules.md` +- `agent-test/local/messaging-flutter-smoke.md` +- `packages/messaging_flutter/pubspec.yaml` +- `packages/messaging_flutter/lib/nexo_messaging.dart` +- `packages/messaging_flutter/lib/src/nexo_messaging_options.dart` +- `packages/messaging_flutter/lib/src/nexo_messaging_plugin.dart` +- `packages/messaging_flutter/lib/src/nexo_messaging_web.dart` +- `packages/messaging_flutter/lib/src/notification_opened_event.dart` +- `packages/messaging_flutter/lib/src/push_notification_type.dart` +- `packages/messaging_flutter/lib/src/web/browser_notification_interop.dart` +- `packages/messaging_flutter/lib/src/web/browser_notification_interop_web.dart` +- `packages/messaging_flutter/lib/src/web_notification_permission.dart` +- `packages/messaging_flutter/lib/src/web_notification_permission_client.dart` +- `packages/messaging_flutter/lib/src/web_notification_permission_client_factory.dart` +- `packages/messaging_flutter/test/nexo_messaging_test.dart` +- `packages/messaging_flutter/README.md` +- `agent-task/archive/2026/06/m-flutter-web-notification/02+01_web_plugin_baseline/complete.log` + +### 테스트 환경 규칙 + +- `test_env=local`. +- 적용 profile: `agent-test/local/messaging-flutter-smoke.md`. +- 적용 명령: + - `cd packages/messaging_flutter && flutter pub get` + - `cd packages/messaging_flutter && flutter test` + - `cd packages/messaging_flutter && flutter analyze --no-fatal-infos` +- 이 task는 package-internal mapper와 unit tests만 다루므로 client-app smoke는 범위 밖이다. + +### 테스트 커버리지 공백 + +- 기존 tests는 native event handling과 web permission unsupported path를 다루지만, web foreground payload normalization은 다루지 않는다. +- 이 plan은 mapper 단위 테스트를 추가해 `PushNotificationType.message`, `server_url`, `channel_id`, `root_id`, `is_crt_enabled`, `userInteraction` 기본값과 override를 검증한다. +- 실제 browser Notification 표시/click은 후속 `04+02,03_display` 계획 대상이다. + +### 심볼 참조 + +- renamed/removed symbol: none. +- 새 mapper는 기존 `PushNotificationType`과 `NotificationOpenedEvent.fromMap` 계약을 보존해야 한다. + +### 분할 판단 + +- split decision policy를 평가했다. +- shared task group: `m-flutter-web-notification`. +- predecessor `02`는 `agent-task/archive/2026/06/m-flutter-web-notification/02+01_web_plugin_baseline/complete.log`로 충족됐다. +- sibling plans: + - `03+02_event_map`: foreground payload mapper와 tests. + - `04+02,03_display`: browser Notification 표시/click routing. 이 plan의 PASS 후 진행해야 한다. +- mapper는 순수 Dart 단위로 검증 가능하고 display는 browser interop와 event routing을 포함하므로 분리한다. + +### 범위 결정 근거 + +- 포함: package-internal web foreground payload mapper, mapper tests, 필요한 README의 짧은 계약 설명. +- 제외: `Notification` 표시, click listener, Firebase `onMessage` 구독 wiring, `apps/flutter-test` UI, Full Web Push/service worker/VAPID. +- 제외 이유: event-map은 후속 display가 소비할 normalized map 계약을 만드는 선행 단위다. + +### 빌드 등급 + +- `local-G07`: public event contract와 후속 display dependency가 있지만 범위는 pure mapper와 tests로 제한되고 deterministic Flutter commands로 검증 가능하다. + +## 구현 체크리스트 + +- [ ] `packages/messaging_flutter/lib/src/web/` 아래에 foreground payload mapper를 추가하고 공용 Dart/API가 `package:web`를 직접 import하지 않게 유지한다. +- [ ] mapper가 host-injected `Map` payload를 기존 `PushNotificationType.message` map으로 정규화하도록 구현한다. +- [ ] mapper가 `RemoteMessage` data map에 준하는 입력과 CRT/thread/channel fields를 보존하고 `userInteraction` 기본값을 `false`로 둔다. +- [ ] mapper 단위 테스트를 추가해 message type 기본값, opened routing field 보존, explicit type/userInteraction override를 검증한다. +- [ ] `cd packages/messaging_flutter && flutter pub get`, `cd packages/messaging_flutter && flutter test`, `cd packages/messaging_flutter && flutter analyze --no-fatal-infos`를 실행한다. +- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. + +## [EVENTMAP-1] Foreground Payload Mapper + +### 문제 + +[NexoMessagingPlugin.handleNativeEvent](/config/workspace/nexo/packages/messaging_flutter/lib/src/nexo_messaging_plugin.dart:150)는 이미 `PushNotificationType` map을 처리하지만, Web foreground payload를 이 map으로 변환하는 package-owned helper가 없다. 후속 display 작업이 browser click을 기존 opened routing으로 연결하려면 먼저 normalized map 계약이 필요하다. + +### 해결 방법 + +`packages/messaging_flutter/lib/src/web/foreground_message_mapper.dart` 같은 내부 파일을 추가한다. 함수명은 구현자가 코드 맥락에 맞게 정하되, 다음 계약을 만족해야 한다. + +```dart +Map normalizeWebForegroundMessage( + Map payload, { + bool userInteraction = false, +}) +``` + +요구 사항: + +- `type`이 없으면 `PushNotificationType.message`를 넣는다. +- `userInteraction`이 없으면 인자 기본값을 넣는다. +- `server_url`, `channel_id`, `root_id`, `is_crt_enabled`는 기존 key 이름 그대로 보존한다. +- null value는 normalized map에 억지로 넣지 않는다. +- `package:web`, browser `Notification`, Firebase runtime을 import하지 않는다. + +### 수정 파일 및 체크리스트 + +- [ ] `packages/messaging_flutter/lib/src/web/foreground_message_mapper.dart` 또는 동등한 내부 mapper 파일 추가 +- [ ] `packages/messaging_flutter/test/nexo_messaging_test.dart` 또는 focused test file에 mapper tests 추가 +- [ ] 필요하면 README에 mapper/display 경계 한 줄 보강 + +### 테스트 작성 + +- type 누락 payload가 `PushNotificationType.message`로 정규화되는지 검증한다. +- existing type과 `userInteraction`이 있는 경우 보존되는지 검증한다. +- CRT/thread/channel routing fields가 `NotificationOpenedEvent.fromMap`과 호환되게 남는지 검증한다. + +### 중간 검증 + +```sh +cd packages/messaging_flutter && flutter test +cd packages/messaging_flutter && flutter analyze --no-fatal-infos +``` + +기대 결과: tests와 analyzer가 통과한다. + +## 수정 파일 요약 + +| 파일 | 항목 | +| --- | --- | +| `packages/messaging_flutter/lib/src/web/foreground_message_mapper.dart` | EVENTMAP-1 | +| `packages/messaging_flutter/test/nexo_messaging_test.dart` 또는 focused test file | EVENTMAP-1 | +| `packages/messaging_flutter/README.md` | EVENTMAP-1 | + +## 최종 검증 + +```sh +cd packages/messaging_flutter && flutter pub get +cd packages/messaging_flutter && flutter test +cd packages/messaging_flutter && flutter analyze --no-fatal-infos +``` + +기대 결과: 세 명령 모두 exit code `0`. + +모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다. diff --git a/agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/plan_local_G08_1.log b/agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/plan_local_G08_1.log new file mode 100644 index 00000000..80532036 --- /dev/null +++ b/agent-task/archive/2026/06/m-flutter-web-notification/03+02_event_map/plan_local_G08_1.log @@ -0,0 +1,116 @@ + + +# Plan - REVIEW_EVENTMAP + +## 이 파일을 읽는 구현 에이전트에게 + +이 task는 이전 `EVENTMAP` 리뷰의 Required 문제만 고치는 후속 계획이다. 구현 후 반드시 active `CODE_REVIEW-local-G08.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운 뒤, active 파일을 그대로 두고 리뷰 준비를 보고한다. + +사용자에게 직접 질문하지 말고, 선택지를 채팅으로 제시하지 말고, `request_user_input`을 호출하지 않는다. 사용자만 결정할 수 있는 차단이 생기면 `CODE_REVIEW-local-G08.md`의 `사용자 리뷰 요청` 섹션에 정확한 근거를 남기고 멈춘다. 구현 에이전트는 `USER_REVIEW.md`, `complete.log`, `*.log` archive를 만들지 않는다. + +## Roadmap Targets + +- Milestone: `agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md` +- Task ids: + - `event-map`: Firebase foreground message 또는 host-injected payload를 기존 `PushNotificationType` map으로 정규화한다. +- Completion mode: check-on-pass + +## 이전 리뷰 요약 + +- 이전 plan: `agent-task/m-flutter-web-notification/03+02_event_map/plan_local_G07_0.log` +- 이전 review: `agent-task/m-flutter-web-notification/03+02_event_map/code_review_local_G07_0.log` +- 이전 판정: FAIL +- Required: `normalizeWebForegroundMessage`가 `server_id`, `ack_id`, `post_id`, `signature`, `id_loaded`, `data` 같은 기존 `message` event field를 드롭한다. 기존 payload의 non-null entry를 보존하고 `type`/`userInteraction` 기본값만 보강해야 한다. + +## 범위 결정 근거 + +- 포함: mapper의 field 보존 방식 수정, mapper 단위 테스트 보강, 기존 검증 명령 재실행. +- 제외: browser Notification 표시, click listener, Firebase `onMessage` 구독 wiring, public API export 변경, README 추가 확장. +- 이유: 이전 구현은 browser/Firebase import boundary와 기본값 로직은 통과했으므로, follow-up은 payload 손실 문제만 고친다. + +## 빌드 등급 + +- `local-G08`: 실패 원인이 명확하고 deterministic unit test로 재현 가능하다. 기존 `local-G07`보다 한 단계 높여 payload contract와 test coverage를 더 엄격히 확인한다. + +## 구현 체크리스트 + +- [ ] `packages/messaging_flutter/lib/src/web/foreground_message_mapper.dart`가 payload의 non-null entry 전체를 보존하고 `type`과 `userInteraction` 기본값만 보강하도록 수정한다. +- [ ] `packages/messaging_flutter/test/nexo_messaging_test.dart`에 `server_id`, `ack_id`, `post_id`, `signature`, `id_loaded`, `data` 같은 message payload field 보존 테스트를 추가한다. +- [ ] `cd packages/messaging_flutter && flutter pub get`, `cd packages/messaging_flutter && flutter test`, `cd packages/messaging_flutter && flutter analyze --no-fatal-infos`를 실행한다. +- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. + +## [REVIEW_EVENTMAP-1] Preserve Foreground Payload Fields + +### 문제 + +현재 mapper는 다음처럼 빈 map을 만들고 allowlist field만 복사한다. + +```dart +final result = {}; +result['type'] = payload['type'] ?? PushNotificationType.message; +result['userInteraction'] = payload['userInteraction'] ?? userInteraction; +``` + +이 방식은 README의 `message` event optional stable fields인 `server_id`, `ack_id`, `post_id`, `signature`, `id_loaded`, `data`를 foreground normalization 단계에서 잃어버린다. 후속 display/click routing과 raw `onNotification` compatibility data가 같은 map을 소비할 수 있으므로, mapper는 필드를 축소하지 말아야 한다. + +### 해결 방법 + +`payload`의 non-null entry를 먼저 복사하고, 누락된 기본 field만 추가한다. + +```dart +final result = { + for (final entry in payload.entries) + if (entry.value != null) entry.key: entry.value, +}; +result.putIfAbsent('type', () => PushNotificationType.message); +result.putIfAbsent('userInteraction', () => userInteraction); +``` + +유지할 계약: + +- `type`이 없으면 `PushNotificationType.message`를 넣는다. +- `type`이 이미 있으면 그대로 둔다. +- `userInteraction`이 없으면 인자 기본값을 넣는다. +- `userInteraction`이 이미 있으면 그대로 둔다. +- null value는 normalized map에 넣지 않는다. +- 기존 stable/compatibility payload field는 값이 null이 아닌 한 보존한다. +- `package:web`, browser `Notification`, Firebase runtime을 import하지 않는다. + +### 수정 파일 및 체크리스트 + +- [ ] `packages/messaging_flutter/lib/src/web/foreground_message_mapper.dart` +- [ ] `packages/messaging_flutter/test/nexo_messaging_test.dart` + +### 테스트 작성 + +- `server_id`, `ack_id`, `post_id`, `signature`, `id_loaded`, `data`가 normalize 결과에 그대로 남는지 검증한다. +- null field가 제거되는 기존 테스트가 계속 통과하는지 확인한다. +- type/userInteraction 기본값과 override 테스트가 계속 통과하는지 확인한다. + +### 중간 검증 + +```sh +cd packages/messaging_flutter && flutter test +cd packages/messaging_flutter && flutter analyze --no-fatal-infos +``` + +기대 결과: tests와 analyzer가 통과한다. + +## 수정 파일 요약 + +| 파일 | 항목 | +| --- | --- | +| `packages/messaging_flutter/lib/src/web/foreground_message_mapper.dart` | REVIEW_EVENTMAP-1 | +| `packages/messaging_flutter/test/nexo_messaging_test.dart` | REVIEW_EVENTMAP-1 | + +## 최종 검증 + +```sh +cd packages/messaging_flutter && flutter pub get +cd packages/messaging_flutter && flutter test +cd packages/messaging_flutter && flutter analyze --no-fatal-infos +``` + +기대 결과: 세 명령 모두 exit code `0`. + +모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다. diff --git a/agent-task/m-flutter-web-notification/04+02,03_display/CODE_REVIEW-local-G08.md b/agent-task/m-flutter-web-notification/04+02,03_display/CODE_REVIEW-local-G08.md new file mode 100644 index 00000000..3cb68338 --- /dev/null +++ b/agent-task/m-flutter-web-notification/04+02,03_display/CODE_REVIEW-local-G08.md @@ -0,0 +1,117 @@ + + +# Code Review Reference - WEBDISPLAY + +> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.** +> The task is NOT complete until every implementation-owned section below is filled in. +> Do not start until predecessor `03+02_event_map` has `complete.log`. +> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving. +> Fill implementation-owned sections, then stop with active files in place and report ready for review. +> If implementation is blocked by a user-only decision, user-owned external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. +> Do not ask the user directly, present choices in chat, or call `request_user_input` during implementation. +> Finalization is review-agent-only. + +## 개요 + +date=2026-06-07 +task=m-flutter-web-notification/04+02,03_display, plan=0, tag=WEBDISPLAY + +## Roadmap Targets + +- Milestone: `agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md` +- Task ids: + - `display`: foreground payload를 browser notification으로 표시하고 click 이벤트를 `NotificationOpenedEvent`와 host navigation callback으로 변환한다. +- Completion mode: check-on-pass + +## 이 파일을 읽는 리뷰 에이전트에게 + +> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다. + +각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요. + +## 구현 항목별 완료 여부 + +| 항목 | 완료 여부 | +|------|---------| +| [WEBDISPLAY-1] Browser Foreground Display And Click Routing | [ ] | + +## 구현 체크리스트 + +- [ ] 구현 시작 전 predecessor `03+02_event_map` complete.log가 active 또는 archive 경로에 있는지 확인한다. +- [ ] browser Notification 표시를 담당하는 web-only interop method를 추가하되 공용 Dart/API가 `package:web`를 직접 import하지 않게 유지한다. +- [ ] `NexoMessagingPlugin`에 foreground web notification display public method를 추가하고 permission이 granted가 아니거나 unsupported면 표시하지 않는 결과를 반환한다. +- [ ] display click event가 normalized payload를 `PushNotificationType.opened`/`userInteraction=true` map으로 변환해 기존 `handleNativeEvent()` routing을 재사용하게 한다. +- [ ] fake interop/client 기반 unit test로 unsupported/permission denied/granted display/click routing을 검증한다. +- [ ] `cd packages/messaging_flutter && flutter pub get`, `cd packages/messaging_flutter && flutter test`, `cd packages/messaging_flutter && flutter analyze --no-fatal-infos`를 실행한다. +- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. + +## 코드리뷰 전용 체크리스트 + +> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다. + +- [ ] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다. +- [ ] predecessor `03+02_event_map` complete.log가 실제로 있었는지 확인한다. +- [ ] active `CODE_REVIEW-*-G??.md`를 `code_review_local_G08_N.log`로 아카이브한다. +- [ ] active `PLAN-*-G??.md`를 `plan_local_G08_M.log`로 아카이브한다. +- [ ] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다. +- [ ] PASS이면 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다. +- [ ] PASS이면 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-flutter-web-notification/04+02,03_display/`로 이동한다. +- [ ] PASS이고 task group이 `m-flutter-web-notification`이면 런타임 완료 이벤트 메타데이터를 보고한다. + +## 계획 대비 변경 사항 + +_구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._ + +## 주요 설계 결정 + +_구현 에이전트가 주요 설계 결정 사항을 기록한다._ + +## 사용자 리뷰 요청 + +_기본값은 `없음`이다. 구현 중 사용자 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. 구현 에이전트는 사용자에게 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백만으로는 사용자 리뷰 요청을 작성하지 않는다._ + +- 상태: 없음 +- 사유 유형: 없음 +- 결정 필요: 없음 +- 차단 근거: 없음 +- 실행한 검증/명령: 없음 +- 자동 후속 불가 이유: 없음 +- 재개 조건: 없음 + +## 리뷰어를 위한 체크포인트 + +- `03+02_event_map` predecessor 완료가 확인됐는지 확인한다. +- public display API가 unsupported/permission denied/granted 결과를 구분하는지 확인한다. +- click callback이 기존 `handleNativeEvent()` routing을 재사용하는지 확인한다. +- 실제 browser prompt/OS tray evidence를 이 task의 필수 검증으로 요구하지 않았는지 확인한다. + +## 검증 결과 + +_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._ + +### WEBDISPLAY-1 중간 검증 + +```text +$ cd packages/messaging_flutter && flutter test +(output) + +$ cd packages/messaging_flutter && flutter analyze --no-fatal-infos +(output) +``` + +### 최종 검증 + +```text +$ cd packages/messaging_flutter && flutter pub get +(output) + +$ cd packages/messaging_flutter && flutter test +(output) + +$ cd packages/messaging_flutter && flutter analyze --no-fatal-infos +(output) +``` + +--- + +> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?** diff --git a/agent-task/m-flutter-web-notification/04+02,03_display/PLAN-local-G08.md b/agent-task/m-flutter-web-notification/04+02,03_display/PLAN-local-G08.md new file mode 100644 index 00000000..b5820306 --- /dev/null +++ b/agent-task/m-flutter-web-notification/04+02,03_display/PLAN-local-G08.md @@ -0,0 +1,172 @@ + + +# Plan - WEBDISPLAY + +## 이 파일을 읽는 구현 에이전트에게 + +이 task는 Chrome foreground 알림 Epic의 `display` Task를 완료하기 위한 구현 계획이다. `03+02_event_map`이 PASS되어 `complete.log`가 생긴 뒤 구현한다. 구현 후 반드시 active `CODE_REVIEW-local-G08.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운 뒤, active 파일을 그대로 두고 리뷰 준비를 보고한다. + +사용자에게 직접 질문하지 말고, 선택지를 채팅으로 제시하지 말고, `request_user_input`을 호출하지 않는다. 사용자만 결정할 수 있는 차단이 생기면 `CODE_REVIEW-local-G08.md`의 `사용자 리뷰 요청` 섹션에 정확한 근거를 남기고 멈춘다. 구현 에이전트는 `USER_REVIEW.md`, `complete.log`, `*.log` archive를 만들지 않는다. + +## 배경 + +Permission API와 foreground mapper가 준비되면 Web foreground payload를 browser notification으로 표시하고 click/open routing을 기존 Dart stream/callback 계약으로 연결할 수 있다. 이 작업은 browser interop, public method, click event bridge가 함께 필요하므로 바로 구현하지 않고 독립 계획으로 남긴다. + +## 사용자 리뷰 요청 흐름 + +구현 중 차단은 active review stub의 `사용자 리뷰 요청` 섹션에 기록한다. 직접 사용자 프롬프트는 금지되며, code-review가 요청 정당성을 검증하고 필요할 때만 `USER_REVIEW.md`를 작성한다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백은 사용자 리뷰 요청이 아니다. + +## Roadmap Targets + +- Milestone: `agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md` +- Task ids: + - `display`: foreground payload를 browser notification으로 표시하고 click 이벤트를 `NotificationOpenedEvent`와 host navigation callback으로 변환한다. +- Completion mode: check-on-pass + +## 분석 결과 + +### 읽은 파일 + +- `agent-roadmap/current.md` +- `agent-roadmap/phase/messaging-runtime/PHASE.md` +- `agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md` +- `agent-test/local/rules.md` +- `agent-test/local/messaging-flutter-smoke.md` +- `agent-test/local/client-app-smoke.md` +- `packages/messaging_flutter/pubspec.yaml` +- `packages/messaging_flutter/lib/nexo_messaging.dart` +- `packages/messaging_flutter/lib/src/nexo_messaging_plugin.dart` +- `packages/messaging_flutter/lib/src/nexo_messaging_web.dart` +- `packages/messaging_flutter/lib/src/notification_opened_event.dart` +- `packages/messaging_flutter/lib/src/push_notification_type.dart` +- `packages/messaging_flutter/lib/src/web/browser_notification_interop.dart` +- `packages/messaging_flutter/lib/src/web/browser_notification_interop_web.dart` +- `packages/messaging_flutter/lib/src/web_notification_permission.dart` +- `packages/messaging_flutter/test/nexo_messaging_test.dart` +- `apps/flutter-test/lib/main.dart` +- `apps/flutter-test/test/widget_test.dart` +- `agent-task/archive/2026/06/m-flutter-web-notification/02+01_web_plugin_baseline/complete.log` + +### 테스트 환경 규칙 + +- `test_env=local`. +- 적용 profile: + - `agent-test/local/messaging-flutter-smoke.md` + - `agent-test/local/client-app-smoke.md`는 app host가 변경될 경우에만 적용한다. +- 기본 적용 명령: + - `cd packages/messaging_flutter && flutter pub get` + - `cd packages/messaging_flutter && flutter test` + - `cd packages/messaging_flutter && flutter analyze --no-fatal-infos` +- `apps/flutter-test/**`를 수정하면 추가로 `cd apps/flutter-test && flutter pub get`, `cd apps/flutter-test && flutter test`, `cd apps/flutter-test && flutter analyze --no-fatal-infos`를 실행한다. + +### 테스트 커버리지 공백 + +- 기존 tests는 native opened event routing을 검증하지만 browser Notification display/click을 검증하지 않는다. +- 이 plan은 browser interop를 fake 가능한 boundary로 두고, display call과 click callback이 `handleNativeEvent()`로 이어지는지 Dart unit test로 검증해야 한다. +- 실제 Chrome permission prompt와 OS notification tray 표시는 local unit test 대상이 아니다. + +### 심볼 참조 + +- renamed/removed symbol: none. +- 새 display API는 `NexoMessagingPlugin` public API와 web-only interop boundary를 함께 확인해야 한다. +- `apps/flutter-test` host UI는 smoke Epic의 `test-host` Task가 별도라 기본 범위에서 제외한다. + +### 분할 판단 + +- split decision policy를 평가했다. +- shared task group: `m-flutter-web-notification`. +- predecessor `02`는 `agent-task/archive/2026/06/m-flutter-web-notification/02+01_web_plugin_baseline/complete.log`로 충족됐다. +- predecessor `03`은 `agent-task/m-flutter-web-notification/03+02_event_map/complete.log` 또는 archive의 matching complete.log가 생겨야 충족된다. +- 이 task directory `04+02,03_display`는 `02` baseline과 `03` mapper에 의존한다. +- display는 browser interop, public API, stream/callback routing을 포함하므로 `event-map`과 분리한다. + +### 범위 결정 근거 + +- 포함: package public display method, browser Notification display/click interop, click -> existing opened routing bridge, focused tests. +- 제외: Firebase `onMessage` subscription wiring, `apps/flutter-test` web UI scaffold, Full Web Push/service worker/VAPID, server/push-proxy changes. +- 제외 이유: display Task는 foreground payload를 표시하고 click routing으로 변환하는 package contract까지이며, Firebase source wiring과 host smoke UI는 별도 Task다. + +### 빌드 등급 + +- `local-G08`: browser interop와 public routing이 함께 바뀌지만 deterministic fake interop tests로 검증 가능하고 scope는 package 내부로 제한된다. + +## 구현 체크리스트 + +- [ ] 구현 시작 전 predecessor `03+02_event_map` complete.log가 active 또는 archive 경로에 있는지 확인한다. +- [ ] browser Notification 표시를 담당하는 web-only interop method를 추가하되 공용 Dart/API가 `package:web`를 직접 import하지 않게 유지한다. +- [ ] `NexoMessagingPlugin`에 foreground web notification display public method를 추가하고 permission이 granted가 아니거나 unsupported면 표시하지 않는 결과를 반환한다. +- [ ] display click event가 normalized payload를 `PushNotificationType.opened`/`userInteraction=true` map으로 변환해 기존 `handleNativeEvent()` routing을 재사용하게 한다. +- [ ] fake interop/client 기반 unit test로 unsupported/permission denied/granted display/click routing을 검증한다. +- [ ] `cd packages/messaging_flutter && flutter pub get`, `cd packages/messaging_flutter && flutter test`, `cd packages/messaging_flutter && flutter analyze --no-fatal-infos`를 실행한다. +- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. + +## [WEBDISPLAY-1] Browser Foreground Display And Click Routing + +### 문제 + +현재 [NexoMessagingPlugin](/config/workspace/nexo/packages/messaging_flutter/lib/src/nexo_messaging_plugin.dart:17)은 native event stream과 web permission API를 제공하지만, Web foreground payload를 browser notification으로 표시하는 public method가 없다. click/open routing도 `NotificationOpenedEvent`와 host navigation callback으로 이어지지 않는다. + +### 해결 방법 + +구현자는 `03+02_event_map`의 mapper를 사용해 payload를 normalized map으로 만든 뒤, web-only display interop와 public plugin method를 연결한다. + +권장 public method 예시: + +```dart +Future +showWebForegroundNotification(Map payload) +``` + +요구 사항: + +- unsupported 또는 permission not granted 상태에서는 browser notification을 만들지 않고 testable result를 반환한다. +- granted 상태에서는 title/body/tag/data 등 최소 fields를 browser Notification API에 전달한다. +- click callback은 normalized map을 opened event로 변환하고 기존 `handleNativeEvent()`를 호출한다. +- Android/iOS/macOS common code는 `package:web`를 직접 import하지 않는다. + +### 수정 파일 및 체크리스트 + +- [ ] `packages/messaging_flutter/lib/src/nexo_messaging_plugin.dart` public method 추가 +- [ ] `packages/messaging_flutter/lib/src/web/browser_notification_interop.dart` display/click boundary 추가 +- [ ] `packages/messaging_flutter/lib/src/web/browser_notification_interop_web.dart` browser implementation 추가 +- [ ] 필요 시 result/status value object 추가 및 `lib/nexo_messaging.dart` export +- [ ] `packages/messaging_flutter/test/`에 fake 기반 unit tests 추가 +- [ ] README의 Web foreground 상태를 display API에 맞게 갱신 + +### 테스트 작성 + +- unsupported/non-granted 상태에서 display가 no-op result를 반환하는지 검증한다. +- granted 상태에서 fake interop가 notification display call을 받는지 검증한다. +- fake click callback이 기존 `onNotificationOpened`, `onNotification`, `onNavigateToChannel`/`onNavigateToThread` 경로로 이어지는지 검증한다. + +### 중간 검증 + +```sh +cd packages/messaging_flutter && flutter test +cd packages/messaging_flutter && flutter analyze --no-fatal-infos +``` + +기대 결과: tests와 analyzer가 통과한다. + +## 수정 파일 요약 + +| 파일 | 항목 | +| --- | --- | +| `packages/messaging_flutter/lib/src/nexo_messaging_plugin.dart` | WEBDISPLAY-1 | +| `packages/messaging_flutter/lib/src/web/browser_notification_interop.dart` | WEBDISPLAY-1 | +| `packages/messaging_flutter/lib/src/web/browser_notification_interop_web.dart` | WEBDISPLAY-1 | +| `packages/messaging_flutter/lib/src/web/**` | WEBDISPLAY-1 | +| `packages/messaging_flutter/test/**` | WEBDISPLAY-1 | +| `packages/messaging_flutter/README.md` | WEBDISPLAY-1 | + +## 최종 검증 + +```sh +cd packages/messaging_flutter && flutter pub get +cd packages/messaging_flutter && flutter test +cd packages/messaging_flutter && flutter analyze --no-fatal-infos +``` + +기대 결과: 세 명령 모두 exit code `0`. + +모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다. diff --git a/packages/messaging_flutter/README.md b/packages/messaging_flutter/README.md index de3af50d..4e632e79 100644 --- a/packages/messaging_flutter/README.md +++ b/packages/messaging_flutter/README.md @@ -53,7 +53,7 @@ copying upstream mobile code. | iOS | Stub | Plugin scaffold exists, behavior is not implemented yet | | macOS | Stub | Plugin scaffold exists; user-provided signing, machine, APNs/Firebase scope, and evidence handoff requirements are documented in [`../../docs/macos-notification-test-guide.md`](../../docs/macos-notification-test-guide.md) | | Windows | Not registered | No Flutter plugin scaffold yet; user-provided Windows runner, packaging, identity, signing, and evidence handoff requirements are documented in [`../../docs/windows-notification-test-guide.md`](../../docs/windows-notification-test-guide.md) | -| Web | Baseline | Plugin registration (`NexoMessagingWeb.registerWith()`), `package:web` dependency, and browser Notification interop boundary (`BrowserNotificationInterop`) are in place. Public permission/request/display APIs are reserved for a future Epic. Full Web Push (service worker, VAPID, server device-token registration) follows. | +| Web | Baseline | Plugin registration (`NexoMessagingWeb.registerWith()`), `package:web` dependency, browser Notification interop boundary (`BrowserNotificationInterop`), and foreground payload mapper (`normalizeWebForegroundMessage`) are in place. The mapper normalizes host-injected payloads to the `PushNotificationType` map contract; browser Notification display and click routing follow in a subsequent Epic. Full Web Push (service worker, VAPID, server device-token registration) follows. | ## Repository Layout @@ -305,9 +305,17 @@ registration. Remaining for the foreground Epic: -- Public permission / display / click routing APIs. +- Public display / click routing APIs. - Notification event forwarding through the main plugin stream. +Foreground browser permission APIs are available on the plugin singleton: + +- `getWebNotificationPermissionStatus()` returns support and current browser + permission state. +- `requestWebNotificationPermission()` requests browser notification permission + on Flutter Web and returns the resulting state. On non-web platforms it + returns an unsupported status without touching native permission APIs. + ## Public API Contract Apps should import only `package:nexo_messaging/nexo_messaging.dart`. The @@ -663,7 +671,7 @@ Evidence to capture: - iOS and macOS are scaffolded but no-op. - Web baseline (`NexoMessagingWeb.registerWith()`, `BrowserNotificationInterop`, `package:web` dependency) is implemented. However: - - Public permission / display / click routing APIs are not yet exposed. + - Public display / click routing APIs are not yet exposed. - Notification events are not yet forwarded through the main plugin stream. - Full Web Push (service worker, VAPID, server device-token registration) is not implemented. diff --git a/packages/messaging_flutter/lib/nexo_messaging.dart b/packages/messaging_flutter/lib/nexo_messaging.dart index a93c7c1a..0121150e 100644 --- a/packages/messaging_flutter/lib/nexo_messaging.dart +++ b/packages/messaging_flutter/lib/nexo_messaging.dart @@ -1,4 +1,5 @@ export 'src/nexo_messaging_options.dart'; export 'src/nexo_messaging_plugin.dart'; +export 'src/web_notification_permission.dart'; export 'src/notification_opened_event.dart'; export 'src/push_notification_type.dart'; diff --git a/packages/messaging_flutter/lib/src/nexo_messaging_plugin.dart b/packages/messaging_flutter/lib/src/nexo_messaging_plugin.dart index 27577e4a..5296eb06 100644 --- a/packages/messaging_flutter/lib/src/nexo_messaging_plugin.dart +++ b/packages/messaging_flutter/lib/src/nexo_messaging_plugin.dart @@ -7,6 +7,9 @@ import 'package:flutter/services.dart'; import 'nexo_messaging_options.dart'; import 'notification_opened_event.dart'; import 'push_notification_type.dart'; +import 'web_notification_permission.dart'; +import 'web_notification_permission_client.dart'; +import 'web_notification_permission_client_factory.dart'; const String _kNotificationChannelName = 'com.tokilabs.nexo.messaging/notifications'; @@ -41,6 +44,9 @@ class NexoMessagingPlugin { Stream get onNotificationOpened => _openedController.stream; + final WebNotificationPermissionClient _webPermissionClient = + createWebNotificationPermissionClient(); + void Function(String serverUrl, String channelId)? onNavigateToChannel; void Function(String serverUrl, String rootId)? onNavigateToThread; void Function(String deviceToken)? onDeviceTokenReady; @@ -114,6 +120,25 @@ class NexoMessagingPlugin { ); } + /// Returns whether browser notifications are supported and the current + /// browser permission state. + /// + /// On non-web platforms this returns an unsupported status without touching + /// native notification permission APIs. + Future + getWebNotificationPermissionStatus() { + return _webPermissionClient.currentStatus(); + } + + /// Requests browser notification permission when running on Flutter Web. + /// + /// On non-web platforms this returns an unsupported status without prompting + /// the user or touching native notification permission APIs. + Future + requestWebNotificationPermission() { + return _webPermissionClient.requestPermission(); + } + /// Reads the current FCM/APNs token and saves it via [_saveDeviceToken]. /// Called during [initialize] when [NexoMessagingInitializeOptions.registerDeviceToken] is `true`. Future _saveCurrentDeviceToken() async { diff --git a/packages/messaging_flutter/lib/src/nexo_messaging_web.dart b/packages/messaging_flutter/lib/src/nexo_messaging_web.dart index 99847ede..f7091b10 100644 --- a/packages/messaging_flutter/lib/src/nexo_messaging_web.dart +++ b/packages/messaging_flutter/lib/src/nexo_messaging_web.dart @@ -15,7 +15,8 @@ import 'web/browser_notification_interop_web.dart'; class NexoMessagingWeb { /// The browser notification interop instance used by this plugin. /// On web builds this resolves to [BrowserNotificationInteropImpl]. - static BrowserNotificationInterop interop = const BrowserNotificationInteropImpl(); + static BrowserNotificationInterop interop = + const BrowserNotificationInteropImpl(); /// Register this plugin for web platforms. static void registerWith(Registrar registrar) { diff --git a/packages/messaging_flutter/lib/src/web/browser_notification_interop.dart b/packages/messaging_flutter/lib/src/web/browser_notification_interop.dart index 42b0348b..f10ada8d 100644 --- a/packages/messaging_flutter/lib/src/web/browser_notification_interop.dart +++ b/packages/messaging_flutter/lib/src/web/browser_notification_interop.dart @@ -10,6 +10,9 @@ abstract class BrowserNotificationInterop { const BrowserNotificationInterop(); + /// Whether the browser exposes the Notification API. + bool get isSupported; + /// Current browser notification permission state (`granted`, `denied`, or /// `default`). String get permission; diff --git a/packages/messaging_flutter/lib/src/web/browser_notification_interop_web.dart b/packages/messaging_flutter/lib/src/web/browser_notification_interop_web.dart index 2459f071..4f37fa0a 100644 --- a/packages/messaging_flutter/lib/src/web/browser_notification_interop_web.dart +++ b/packages/messaging_flutter/lib/src/web/browser_notification_interop_web.dart @@ -1,4 +1,5 @@ import 'dart:js_interop'; +import 'dart:js_interop_unsafe'; import 'package:web/web.dart' as web; @@ -11,6 +12,9 @@ import 'browser_notification_interop.dart'; class BrowserNotificationInteropImpl extends BrowserNotificationInterop { const BrowserNotificationInteropImpl(); + @override + bool get isSupported => globalContext.has('Notification'); + @override String get permission => web.Notification.permission.toString(); diff --git a/packages/messaging_flutter/lib/src/web/foreground_message_mapper.dart b/packages/messaging_flutter/lib/src/web/foreground_message_mapper.dart new file mode 100644 index 00000000..1b0ccc79 --- /dev/null +++ b/packages/messaging_flutter/lib/src/web/foreground_message_mapper.dart @@ -0,0 +1,23 @@ +import '../push_notification_type.dart'; + +/// Normalizes a host-injected or Firebase foreground message payload into the +/// canonical [PushNotificationType] map contract consumed by +/// [NexoMessagingPlugin.handleNativeEvent]. +/// +/// Copies all non-null entries from [payload], then fills in defaults for +/// `type` and `userInteraction` if absent. No other fields are added or +/// removed. +/// +/// Does NOT import `package:web`, browser Notification, or Firebase runtime. +Map normalizeWebForegroundMessage( + Map payload, { + bool userInteraction = false, +}) { + final result = { + for (final entry in payload.entries) + if (entry.value != null) entry.key: entry.value, + }; + result.putIfAbsent('type', () => PushNotificationType.message); + result.putIfAbsent('userInteraction', () => userInteraction); + return result; +} diff --git a/packages/messaging_flutter/lib/src/web/web_notification_permission_client_stub.dart b/packages/messaging_flutter/lib/src/web/web_notification_permission_client_stub.dart new file mode 100644 index 00000000..ecce384f --- /dev/null +++ b/packages/messaging_flutter/lib/src/web/web_notification_permission_client_stub.dart @@ -0,0 +1,21 @@ +import '../web_notification_permission.dart'; +import '../web_notification_permission_client.dart'; + +class UnsupportedWebNotificationPermissionClient + extends WebNotificationPermissionClient { + const UnsupportedWebNotificationPermissionClient(); + + @override + Future currentStatus() async { + return const NexoMessagingWebNotificationStatus.unsupported(); + } + + @override + Future requestPermission() async { + return const NexoMessagingWebNotificationStatus.unsupported(); + } +} + +WebNotificationPermissionClient createWebNotificationPermissionClient() { + return const UnsupportedWebNotificationPermissionClient(); +} diff --git a/packages/messaging_flutter/lib/src/web/web_notification_permission_client_web.dart b/packages/messaging_flutter/lib/src/web/web_notification_permission_client_web.dart new file mode 100644 index 00000000..d3e97d75 --- /dev/null +++ b/packages/messaging_flutter/lib/src/web/web_notification_permission_client_web.dart @@ -0,0 +1,36 @@ +import '../web_notification_permission.dart'; +import '../web_notification_permission_client.dart'; +import 'browser_notification_interop.dart'; +import 'browser_notification_interop_web.dart'; + +class BrowserWebNotificationPermissionClient + extends WebNotificationPermissionClient { + const BrowserWebNotificationPermissionClient({ + BrowserNotificationInterop interop = const BrowserNotificationInteropImpl(), + }) : _interop = interop; + + final BrowserNotificationInterop _interop; + + @override + Future currentStatus() async { + if (!_interop.isSupported) { + return const NexoMessagingWebNotificationStatus.unsupported(); + } + return NexoMessagingWebNotificationStatus.fromBrowserPermission( + _interop.permission, + ); + } + + @override + Future requestPermission() async { + if (!_interop.isSupported) { + return const NexoMessagingWebNotificationStatus.unsupported(); + } + final permission = await _interop.requestPermission(); + return NexoMessagingWebNotificationStatus.fromBrowserPermission(permission); + } +} + +WebNotificationPermissionClient createWebNotificationPermissionClient() { + return const BrowserWebNotificationPermissionClient(); +} diff --git a/packages/messaging_flutter/lib/src/web_notification_permission.dart b/packages/messaging_flutter/lib/src/web_notification_permission.dart new file mode 100644 index 00000000..a87edff2 --- /dev/null +++ b/packages/messaging_flutter/lib/src/web_notification_permission.dart @@ -0,0 +1,62 @@ +/// Browser notification permission states exposed by [NexoMessagingPlugin]. +enum NexoMessagingWebNotificationPermission { + /// Browser Notification API is not available on this platform/runtime. + unsupported, + + /// Browser permission has not been granted or denied yet. + defaultPermission, + + /// Browser permission was denied. + denied, + + /// Browser permission was granted. + granted, + + /// Browser returned an unknown permission string. + unknown, +} + +/// Current browser notification support and permission status. +class NexoMessagingWebNotificationStatus { + const NexoMessagingWebNotificationStatus({ + required this.isSupported, + required this.permission, + this.rawPermission, + }); + + /// Creates an unsupported status for non-web or unsupported web runtimes. + const NexoMessagingWebNotificationStatus.unsupported() + : isSupported = false, + permission = NexoMessagingWebNotificationPermission.unsupported, + rawPermission = null; + + /// Creates a supported status from a browser `Notification.permission` value. + factory NexoMessagingWebNotificationStatus.fromBrowserPermission( + String permission, + ) { + final normalized = permission.trim().toLowerCase(); + return NexoMessagingWebNotificationStatus( + isSupported: true, + permission: switch (normalized) { + 'default' => NexoMessagingWebNotificationPermission.defaultPermission, + 'denied' => NexoMessagingWebNotificationPermission.denied, + 'granted' => NexoMessagingWebNotificationPermission.granted, + _ => NexoMessagingWebNotificationPermission.unknown, + }, + rawPermission: permission, + ); + } + + /// Whether the current runtime exposes browser notifications. + final bool isSupported; + + /// Normalized browser notification permission. + final NexoMessagingWebNotificationPermission permission; + + /// Raw browser permission string, when available. + final String? rawPermission; + + /// Whether browser notification display is currently allowed. + bool get isGranted => + permission == NexoMessagingWebNotificationPermission.granted; +} diff --git a/packages/messaging_flutter/lib/src/web_notification_permission_client.dart b/packages/messaging_flutter/lib/src/web_notification_permission_client.dart new file mode 100644 index 00000000..362c7cf0 --- /dev/null +++ b/packages/messaging_flutter/lib/src/web_notification_permission_client.dart @@ -0,0 +1,9 @@ +import 'web_notification_permission.dart'; + +abstract class WebNotificationPermissionClient { + const WebNotificationPermissionClient(); + + Future currentStatus(); + + Future requestPermission(); +} diff --git a/packages/messaging_flutter/lib/src/web_notification_permission_client_factory.dart b/packages/messaging_flutter/lib/src/web_notification_permission_client_factory.dart new file mode 100644 index 00000000..73926ea2 --- /dev/null +++ b/packages/messaging_flutter/lib/src/web_notification_permission_client_factory.dart @@ -0,0 +1,8 @@ +import 'web/web_notification_permission_client_stub.dart' + if (dart.library.js_interop) 'web/web_notification_permission_client_web.dart' + as impl; +import 'web_notification_permission_client.dart'; + +WebNotificationPermissionClient createWebNotificationPermissionClient() { + return impl.createWebNotificationPermissionClient(); +} diff --git a/packages/messaging_flutter/test/nexo_messaging_test.dart b/packages/messaging_flutter/test/nexo_messaging_test.dart index 609a14f8..45432644 100644 --- a/packages/messaging_flutter/test/nexo_messaging_test.dart +++ b/packages/messaging_flutter/test/nexo_messaging_test.dart @@ -3,6 +3,7 @@ import 'dart:async'; import 'package:flutter/services.dart'; import 'package:flutter_test/flutter_test.dart'; import 'package:nexo_messaging/nexo_messaging.dart'; +import 'package:nexo_messaging/src/web/foreground_message_mapper.dart'; void main() { TestWidgetsFlutterBinding.ensureInitialized(); @@ -325,6 +326,40 @@ void main() { }); }); + group('NexoMessagingPlugin web notification permission', () { + late NexoMessagingPlugin plugin; + + setUp(() { + plugin = NexoMessagingPlugin.instance; + }); + + test('reports unsupported status on non-web platforms', () async { + final status = await plugin.getWebNotificationPermissionStatus(); + + expect(status.isSupported, isFalse); + expect( + status.permission, + NexoMessagingWebNotificationPermission.unsupported, + ); + expect(status.rawPermission, isNull); + expect(status.isGranted, isFalse); + }); + + test( + 'request is a no-op unsupported status on non-web platforms', + () async { + final status = await plugin.requestWebNotificationPermission(); + + expect(status.isSupported, isFalse); + expect( + status.permission, + NexoMessagingWebNotificationPermission.unsupported, + ); + expect(status.rawPermission, isNull); + }, + ); + }); + group('NexoMessagingTokenPrefix', () { test('androidV2 has the expected value', () { expect(NexoMessagingTokenPrefix.androidV2, 'android_rn-v2'); @@ -338,4 +373,110 @@ void main() { expect(NexoMessagingTokenPrefix.webV2, 'web_rn-v2'); }); }); + + group('normalizeWebForegroundMessage', () { + test('missing type defaults to PushNotificationType.message', () { + final result = normalizeWebForegroundMessage({ + 'server_url': 'https://nexo.example.com', + 'channel_id': 'ch-1', + }); + + expect(result['type'], PushNotificationType.message); + }); + + test('existing type is preserved', () { + final result = normalizeWebForegroundMessage({ + 'type': PushNotificationType.clear, + }); + + expect(result['type'], PushNotificationType.clear); + }); + + test('userInteraction defaults to false when absent from payload', () { + final result = normalizeWebForegroundMessage({}); + + expect(result['userInteraction'], isFalse); + }); + + test('userInteraction parameter is applied when payload does not set it', () { + final result = normalizeWebForegroundMessage({}, userInteraction: true); + + expect(result['userInteraction'], isTrue); + }); + + test('userInteraction in payload overrides parameter', () { + final result = normalizeWebForegroundMessage( + {'userInteraction': true}, + userInteraction: false, + ); + + expect(result['userInteraction'], isTrue); + }); + + test('routing fields are preserved for NotificationOpenedEvent.fromMap', () { + final result = normalizeWebForegroundMessage({ + 'server_url': 'https://nexo.example.com', + 'channel_id': 'ch-1', + 'root_id': 'root-99', + 'is_crt_enabled': 'true', + }); + + final event = NotificationOpenedEvent.fromMap(result); + expect(event.serverUrl, 'https://nexo.example.com'); + expect(event.channelId, 'ch-1'); + expect(event.rootId, 'root-99'); + expect(event.isCRTEnabled, isTrue); + }); + + test('null routing field values are not included in result', () { + final result = normalizeWebForegroundMessage({ + 'server_url': null, + 'channel_id': 'ch-1', + }); + + expect(result.containsKey('server_url'), isFalse); + expect(result['channel_id'], 'ch-1'); + }); + + test('absent routing fields are not included in result', () { + final result = normalizeWebForegroundMessage({'type': PushNotificationType.message}); + + expect(result.containsKey('server_url'), isFalse); + expect(result.containsKey('channel_id'), isFalse); + expect(result.containsKey('root_id'), isFalse); + expect(result.containsKey('is_crt_enabled'), isFalse); + }); + + test('message stable fields are preserved in normalized result', () { + final result = normalizeWebForegroundMessage({ + 'server_url': 'https://nexo.example.com', + 'channel_id': 'ch-1', + 'server_id': 'srv-99', + 'ack_id': 'ack-42', + 'post_id': 'post-77', + 'signature': 'sig-abc', + 'id_loaded': 'true', + 'data': {'key': 'value'}, + }); + + expect(result['server_url'], 'https://nexo.example.com'); + expect(result['channel_id'], 'ch-1'); + expect(result['server_id'], 'srv-99'); + expect(result['ack_id'], 'ack-42'); + expect(result['post_id'], 'post-77'); + expect(result['signature'], 'sig-abc'); + expect(result['id_loaded'], 'true'); + expect(result['data'], {'key': 'value'}); + }); + + test('unknown extra fields from payload are preserved', () { + final result = normalizeWebForegroundMessage({ + 'custom_field': 'custom_value', + 'another': 123, + }); + + expect(result['custom_field'], 'custom_value'); + expect(result['another'], 123); + }); + }); }