nexo/agent-ops/rules/project/domain/messaging-flutter/rules.md

domain	last_rule_review_commit	last_rule_updated_at
messaging-flutter	8a7115d9c8	2026-06-01

messaging-flutter

목적 / 책임

nexo의 메인 산출물인 메시징/알림 Flutter 플러그인 패키지를 담당한다. FCM 수신, 알림 표시, tap/open 이벤트, inline reply, dismiss 처리, ACK 전달, token/key 저장을 앱별 구현으로 흩어지지 않게 모아 여러 Flutter 앱이 재사용할 수 있게 한다.

포함 경로

• packages/messaging_flutter/lib/ — public Dart API와 Flutter-facing behavior
• packages/messaging_flutter/android/ — Android native plugin implementation
• packages/messaging_flutter/ios/, packages/messaging_flutter/macos/ — platform scaffold와 stub
• packages/messaging_flutter/test/ — Dart API contract tests
• packages/messaging_flutter/docs/ — plugin 개발 및 검증 문서
• packages/messaging_flutter/pubspec.yaml — plugin package metadata

제외 경로

• apps/flutter-test/ — plugin을 검증하는 테스트용 Flutter 앱 책임
• apps/mattermost/ — 원래 Mattermost 앱 repository clone 책임
• services/core/ — Mattermost 서버 repository clone 책임
• services/push-proxy/ — Mattermost push-proxy repository clone 책임
• docs/, root bin/ — workspace-level 문서와 command entrypoint 책임

주요 구성 요소

• NexoMessagingPlugin — singleton access, event stream, token/key action channel, host routing callback API
• NotificationOpenedEvent — notification open payload parsing
• NexoFirebaseMessagingService — Android FCM 수신, signature-before-ACK gate, foreground/background notification dispatch 진입점
• PayloadGate — signed payload verification과 ACK ordering을 testable하게 유지하는 acceptance gate
• NotificationReplyBroadcastReceiver, NotificationDismissService — Android action handling
• ReceiptDelivery — ACK delivery와 transient failure queueing 책임
• PendingNotificationActionStore, PendingNotificationActionDispatcher — ACK/reply/dismiss retry queue와 permanent failure event 책임
• NotificationHelper — Android notification id, grouping, clear, dismiss behavior 책임

유지할 패턴

• public package/import/native identifier는 nexo 계열 이름으로 전환하되, host app과 native 등록 지점을 같은 계획 안에서 함께 갱신한다.
• Android가 production target이며 iOS/macOS는 stub 상태임을 명확히 보고한다.
• host app이 해야 할 Firebase 초기화, token 등록, navigation 연결은 README의 Host App Responsibilities와 맞춘다.
• 패키지를 이 저장소의 제품 중심으로 보고, 앱별 제품 UI나 business logic은 소비 앱 책임으로 둔다.
• native event type은 Dart API의 PushNotificationType과 호환되게 유지한다.
• signed push payload는 ACK 전에 검증하고, invalid signature payload는 ACK 없이 drop한다.
• ACK/reply/dismiss의 offline 또는 transient failure는 plugin-owned pending action queue로 처리하고 permanent failure는 action_failure event로 노출한다.
• Android native behavior는 android/src/test/의 payload gate, receipt delivery, notification display, pending action store 테스트와 함께 유지한다.

다른 도메인과의 경계

• client-app: apps/flutter-test는 plugin 검증용 테스트 앱이며 plugin 내부 push 처리 로직을 복제하지 않는다.
• core-service: Mattermost 기반 runtime과의 계약은 payload, signing key, auth token, ACK/reply endpoint 수준으로 다룬다.
• push-proxy-service: push proxy는 APNs/FCM delivery server이고, device token 저장과 native notification action 처리는 plugin 책임이다.
• workspace-ops: 공통 bin/test, bin/lint가 plugin 검증을 호출하지만 plugin 세부 검증 기준은 이 도메인이 소유한다.

금지 사항

• package rename이나 public API breaking change는 현재 마일스톤의 nexo 전환 결정과 계획에 맞춰 수행한다.
• host app 전용 navigation, 화면 구성, 제품 UI 상태를 plugin 내부에 넣지 않는다.
• 이 저장소 안에 nexo 제품 앱을 만들기 위해 plugin 책임을 앱 책임으로 옮기지 않는다.
• iOS/macOS stub을 production-ready로 단정하지 않는다.