nexo/agent-task/m-flutter-web-notification/04+02,03_display/plan_local_G08_0.log

<!-- task=m-flutter-web-notification/04+02,03_display plan=0 tag=WEBDISPLAY -->

# 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<NexoMessagingWebNotificationDisplayResult>
showWebForegroundNotification(Map<String, dynamic> 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`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.