From 871c792128913466e041627537d38f089caa09bd Mon Sep 17 00:00:00 2001 From: toki Date: Sun, 7 Jun 2026 09:12:19 +0900 Subject: [PATCH] =?UTF-8?q?docs(roadmap):=20Flutter=20Web=20=EC=95=8C?= =?UTF-8?q?=EB=A6=BC=20=EB=A7=88=EC=9D=BC=EC=8A=A4=ED=86=A4=EC=9D=84=20?= =?UTF-8?q?=EC=B6=94=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 패키지 중심의 Chrome 웹 알림 적용 방향을 로드맵 최상단에 두고, 진행 중인 런타임 표준화 작업과 포트/환경 표준화 항목을 함께 반영한다. --- agent-roadmap/ROADMAP.md | 2 +- .../phase/messaging-runtime/PHASE.md | 8 +- .../milestones/flutter-web-notification.md | 82 +++++++++++++++++++ .../milestones/ios-notification-test.md | 8 +- .../workspace-port-env-standardization.md | 66 +++++++++++++++ 5 files changed, 161 insertions(+), 5 deletions(-) create mode 100644 agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md create mode 100644 agent-roadmap/phase/messaging-runtime/milestones/workspace-port-env-standardization.md diff --git a/agent-roadmap/ROADMAP.md b/agent-roadmap/ROADMAP.md index 3a763618..f5a660ee 100644 --- a/agent-roadmap/ROADMAP.md +++ b/agent-roadmap/ROADMAP.md @@ -22,7 +22,7 @@ nexo-owned 제품 표면은 Flutter SDK, compose, 운영 계약, 앱별 integrat - [검토중] 업스트림 런타임 운영화 - 경로: `agent-roadmap/phase/upstream-runtime/PHASE.md` - 요약: Mattermost server/webapp/push-proxy 업데이트를 계속 따라가기 위한 기준, CI/CD, 장애 대응 루프를 정리했고 Phase 완료 확인을 기다린다. -- [계획] 메시징 런타임 표준화 +- [진행중] 메시징 런타임 표준화 - 경로: `agent-roadmap/phase/messaging-runtime/PHASE.md` - 요약: nexo-owned Flutter SDK와 upstream runtime이 공유할 메시징/알림 계약, 테스트, 앱별 사용 채널 모델을 정리한다. diff --git a/agent-roadmap/phase/messaging-runtime/PHASE.md b/agent-roadmap/phase/messaging-runtime/PHASE.md index 2ee11829..01e2f048 100644 --- a/agent-roadmap/phase/messaging-runtime/PHASE.md +++ b/agent-roadmap/phase/messaging-runtime/PHASE.md @@ -2,7 +2,7 @@ ## 상태 -[계획] +[진행중] ## 목표 @@ -34,6 +34,12 @@ Mattermost server/webapp/push-proxy는 upstream-followable runtime으로 두고, - [완료] Linux 알림 선행 정리 - 경로: `agent-roadmap/archive/phase/messaging-runtime/milestones/linux-notification-preflight.md` - 요약: Linux 배포판/desktop environment 결정 없이 plugin 등록, notification daemon 후보, bridge 계약, fixture, evidence 기준을 먼저 정리했다. +- [진행중] 워크스페이스 포트/환경 표준화 + - 경로: `agent-roadmap/phase/messaging-runtime/milestones/workspace-port-env-standardization.md` + - 요약: Mattermost core, push-proxy, Flutter test/web surface, upstream dev services 포트를 workspace 공통 대역과 remote runtime 문서 기준으로 정리한다. +- [계획] Flutter Web 알림 + - 경로: `agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md` + - 요약: `packages/messaging_flutter`를 Flutter Web/Chrome foreground browser notification까지 확장하고, Full Web Push는 별도 후속 계약으로 분리한다. - [계획] iOS 알림 테스트 - 경로: `agent-roadmap/phase/messaging-runtime/milestones/ios-notification-test.md` - 요약: 선행 정리 후 iOS/APNs 권한, token, open routing, ACK/dismiss 계약을 실제 설정과 smoke 기준으로 검증한다. diff --git a/agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md b/agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md new file mode 100644 index 00000000..b9183c64 --- /dev/null +++ b/agent-roadmap/phase/messaging-runtime/milestones/flutter-web-notification.md @@ -0,0 +1,82 @@ +# Milestone: Flutter Web 알림 + +## 위치 + +- Roadmap: `agent-roadmap/ROADMAP.md` +- Phase: `agent-roadmap/phase/messaging-runtime/PHASE.md` + +## 목표 + +`packages/messaging_flutter`를 Flutter Web/Chrome 알림의 source of truth로 확장한다. +먼저 웹앱이 열려 있는 상태의 browser notification permission, 표시, click/open routing을 패키지 API로 제공하고, 브라우저가 닫힌 상태의 Full Web Push는 별도 후속 범위로 분리한다. + +## 상태 + +[계획] + +## 승격 조건 + +- 없음 + +## 구현 잠금 + +- 상태: 해제 +- 결정 필요: 없음 + +## 범위 + +- `packages/messaging_flutter`의 web platform 등록과 browser notification public API 추가 +- Chrome/Flutter Web foreground 알림 permission, 표시, click/open event를 기존 `onNotification`, `onNotificationOpened`, channel/thread callback 계약에 연결 +- `apps/flutter-test`에 Flutter Web 검증 host scaffold와 민감값 없는 smoke 기준 추가 +- Full Web Push에 필요한 `web_rn-v2` token, service worker, VAPID, core/push-proxy platform 확장은 후속 작업으로 경계화 + +## 기능 + +### Epic: [web-baseline] Web 플랫폼 기준선 + +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와 분리한다. + +### Epic: [foreground] Chrome foreground 알림 + +웹앱이 열려 있는 상태에서 Chrome browser notification을 패키지 책임으로 표시하고 routing event를 재사용한다. + +- [ ] [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으로 정규화한다. + +### Epic: [smoke] Web Smoke + +민감값 없이 반복 가능한 검증 기준을 만들고, Full Web Push는 별도 설계 항목으로 남긴다. + +- [ ] [test-host] `apps/flutter-test`에서 Flutter Web smoke scaffold와 permission/display/click 상태 표시를 제공한다. +- [ ] [auto-test] web interop을 직접 띄우지 않는 Dart API/mapper 단위 테스트를 추가한다. 검증: `bin/test` +- [ ] [push-follow-up] service worker, VAPID, `web_rn-v2` device token, core/push-proxy platform 분기 설계를 후속 Milestone 후보로 정리한다. + +## 완료 리뷰 + +- 상태: 없음 +- 요청일: 없음 +- 완료 근거: 없음 +- 리뷰 필요: + - [ ] 사용자가 완료 결과를 확인했다 + - [ ] archive 이동을 승인했다 +- 리뷰 코멘트: 없음 + +## 범위 제외 + +- 브라우저가 닫힌 상태에서도 수신되는 Full Web Push 구현 +- `services/core`의 push platform 상수 추가, session device id 마이그레이션, push-proxy web target 구현 +- Mattermost webapp UI/Redux 알림 구현 복제 +- 제품 앱 UI 또는 앱별 메시징 화면 구현 + +## 작업 컨텍스트 + +- 관련 경로: `packages/messaging_flutter/`, `apps/flutter-test/`, `services/core/server/public/model/push_notification.go`, `services/push-proxy/server/` +- 표준선(선택): 1차는 Flutter Web foreground browser notification으로 제한하고, Full Web Push는 `web_rn-v2` token 및 service worker 기반 후속 Milestone으로 분리한다. +- 선행 작업: 알림 파이프라인 고도화 +- 후속 작업: Full Web Push platform 계약 +- 확인 필요: 실제 Chrome smoke에 사용할 Firebase web config, VAPID key, private host 값은 tracked 문서에 기록하지 않고 host 환경 책임으로 둔다. diff --git a/agent-roadmap/phase/messaging-runtime/milestones/ios-notification-test.md b/agent-roadmap/phase/messaging-runtime/milestones/ios-notification-test.md index 79bef554..504cfe32 100644 --- a/agent-roadmap/phase/messaging-runtime/milestones/ios-notification-test.md +++ b/agent-roadmap/phase/messaging-runtime/milestones/ios-notification-test.md @@ -42,7 +42,7 @@ Android 중심으로 정리된 nexo 알림 계약을 iOS/APNs 환경에서 어 iOS 알림이 Android와 같은 계약으로 검증되기 전에 필요한 platform baseline을 확인한다. -- [ ] [platform-state] 선행 정리 결과를 바탕으로 `packages/messaging_flutter/ios`와 `apps/flutter-test/ios`의 scaffold, 등록 지점, 남은 no-op gap을 확인한다. +- [x] [platform-state] 선행 정리 결과를 바탕으로 `packages/messaging_flutter/ios`와 `apps/flutter-test/ios`의 scaffold, 등록 지점, 남은 no-op gap을 확인한다. - [ ] [permission-token] APNs entitlement, Firebase config, notification permission, APNs/FCM token 획득과 host handoff 조건을 정리한다. - [ ] [device-limits] simulator, physical device, CI/headless 환경에서 가능한 검증과 불가능한 검증을 구분한다. @@ -50,8 +50,8 @@ iOS 알림이 Android와 같은 계약으로 검증되기 전에 필요한 platf iOS native event가 Dart API와 host routing callback으로 연결되기 위한 계약을 구체화한다. -- [ ] [native-bridge] 선행 정리한 bridge 계약 대비 permission, token refresh, notification opened event를 Flutter method/event channel로 넘기는 iOS 구현 gap을 확인한다. -- [ ] [payload-map] 선행 fixture 계약을 실제 APNs/FCM payload의 `server_url`, `server_id`, `channel_id`, `root_id`, `ack_id` 매핑에 대조한다. +- [x] [native-bridge] 선행 정리한 bridge 계약 대비 permission, token refresh, notification opened event를 Flutter method/event channel로 넘기는 iOS 구현 gap을 확인한다. +- [x] [payload-map] 선행 fixture 계약을 실제 APNs/FCM payload의 `server_url`, `server_id`, `channel_id`, `root_id`, `ack_id` 매핑에 대조한다. - [ ] [ack-dismiss] iOS에서 ACK, dismiss, inline reply를 처리할 수 있는 native hook과 후속 구현이 필요한 gap을 분리한다. ### Epic: [smoke] iOS Smoke @@ -87,3 +87,5 @@ iOS native event가 Dart API와 host routing callback으로 연결되기 위한 - 선행 작업: 알림 파이프라인 고도화, iOS 알림 선행 정리 - 후속 작업: 멀티앱 채널 모델 - 확인 필요: 프로비저닝, APNs 인증, Firebase iOS 설정, 실제 기기/CI smoke 환경 결정 +- 현재 동기화(2026-06-05): `packages/messaging_flutter/ios/Classes/NexoMessagingPlugin.swift`와 `apps/flutter-test/ios/RunnerTests/RunnerTests.swift` 기준으로 최소 debug/action bridge, device token 저장/조회, auth/signing no-op bridge는 확인됐고, APNs 등록, Firebase token refresh, notification center delegate, ACK, dismiss, inline reply는 구현 gap으로 남아 있다. +- 현재 동기화(2026-06-05): `apps/flutter-test/ios/Runner/Runner.example.entitlements`, `apps/flutter-test/ios/Runner/GoogleService-Info.example.plist`, `apps/flutter-test/ios/Fixtures/*.apns`, `docs/ios-notification-test-guide.md` 기준으로 placeholder와 민감값 제외/evidence 경계는 확인됐고, 실제 Apple/Firebase/기기 smoke 결정은 아직 잠금 항목으로 남아 있다. diff --git a/agent-roadmap/phase/messaging-runtime/milestones/workspace-port-env-standardization.md b/agent-roadmap/phase/messaging-runtime/milestones/workspace-port-env-standardization.md new file mode 100644 index 00000000..e9fbe4e5 --- /dev/null +++ b/agent-roadmap/phase/messaging-runtime/milestones/workspace-port-env-standardization.md @@ -0,0 +1,66 @@ +# Milestone: 워크스페이스 포트/환경 표준화 + +## 위치 + +- Roadmap: `agent-roadmap/ROADMAP.md` +- Phase: `agent-roadmap/phase/messaging-runtime/PHASE.md` + +## 목표 + +Nexo의 upstream-followable Mattermost runtime, push-proxy, Flutter test host, web preview, remote runner 문서가 workspace 공통 포트 대역을 일관되게 말하도록 정리한다. 기존 core `18065`와 push-proxy `18066`은 외부 소비자가 있을 수 있으므로 즉시 변경하지 않고, 표준 대역과 호환성 메모를 먼저 남긴다. + +## 상태 + +[진행중] + +## 승격 조건 + +- 없음 + +## 구현 잠금 + +- 상태: 해제 +- 결정 필요: 없음 + +## 범위 + +- Mattermost core HTTP, push-proxy HTTP, Flutter test/web host, upstream dev service 포트 inventory +- 기존 외부 endpoint `18065/18066` 유지 여부와 workspace backend 대역 후보의 migration note +- upstream dev compose의 PostgreSQL, Redis, MinIO, mail, search, metrics, dashboard 포트를 nexo-owned runtime 포트와 분리해 문서화 +- Android/iOS/Web notification smoke에서 사용하는 host/base URL과 private Firebase/APNs 값의 기록 경계 정리 + +## 기능 + +### Epic: [inventory] Nexo runtime inventory + +Nexo가 소유한 runtime 포트와 upstream 개발 보조 포트를 분리해 정리한다. + +- [ ] [runtime-map] core HTTP, push-proxy, Flutter test host, web preview 포트를 host publish와 container/internal 기준으로 나눠 정리한다. +- [ ] [upstream-map] upstream Mattermost dev compose의 DB/cache/object/search/mail/metrics/dashboard 포트를 nexo-owned runtime과 구분해 충돌 후보를 표시한다. +- [ ] [slot-plan] Nexo 기본 후보를 frontend `13040`, backend `18065/18066` 유지, compose-internal DB/cache 우선으로 문서화하고 변경 필요 시 `18040` 계열 후보를 남긴다. +- [ ] [secret-boundary] Firebase, APNs, Mattermost token, private host 값은 tracked 문서에 쓰지 않고 evidence 위치와 책임 경계만 남긴다. + +## 완료 리뷰 + +- 상태: 없음 +- 요청일: 없음 +- 완료 근거: 없음 +- 리뷰 필요: + - [ ] 사용자가 완료 결과를 확인했다 + - [ ] archive 이동을 승인했다 +- 리뷰 코멘트: 없음 + +## 범위 제외 + +- 원격 runtime core/push-proxy 포트 즉시 변경 +- Mattermost upstream service 구조 변경 +- iOS/APNs, Firebase, Mattermost credential 기록 +- Flutter Web 알림 또는 iOS 알림 구현 + +## 작업 컨텍스트 + +- 관련 경로: `services/core/`, `services/push-proxy/`, `apps/flutter-test/`, `packages/messaging_flutter/`, `agent-test/local/` +- 표준선(선택): 외부 소비자가 있는 `18065/18066`은 compatibility baseline으로 유지하고, 신규 preview/test host publish만 workspace 대역으로 먼저 정렬한다. +- 선행 작업: workspace 공통 포트 inventory 정리 +- 후속 작업: compose/env/test smoke 갱신과 drift 방지 +- 확인 필요: 없음