mattermost-push-plugin/agent-ops/rules/project/domain/dart-api/rules.md

domain	last_rule_review_commit	last_rule_updated_at
dart-api	678302bc3e	2026-05-25

dart-api

목적 / 책임

Flutter host app이 사용하는 public API, native channel 계약, notification/opened event parsing, token callback 흐름을 담당한다.

포함 경로

• lib/ — package export, singleton API, EventChannel/MethodChannel, event model, push type 상수를 포함한다.
• test/ — Dart API와 event parsing, channel contract 테스트를 포함한다.

제외 경로

• android/ — native FCM 수신, 알림 표시, Room/OkHttp/JJWT 처리는 Android runtime 도메인이다.
• ios/, macos/ — 현재 no-op Swift scaffold 도메인이다.
• example/ — host integration 예제와 manual smoke 지원 도메인이다.

주요 구성 요소

• MattermostPushPlugin — singleton public API, native event stream, action method channel, navigation/device-token callback을 관리한다.
• NotificationOpenedEvent — native payload를 host navigation에 필요한 Dart model로 변환한다.
• PushNotificationType — native와 공유하는 event type 문자열 상수를 제공한다.

유지할 패턴

• channel 이름은 native Android MattermostPushPlugin companion object 상수와 동일해야 한다.
• native payload key는 snake_case를 유지하고 Dart model에서 임의로 camelCase key로 바꾸지 않는다.
• token refresh는 저장 channel 호출 후 onDeviceTokenReady에 android_rn-v2: prefix 포함 값을 전달한다.
• onNotification raw stream은 처리된 모든 native event를 host app에 전달한다.

다른 도메인과의 경계

• android-push-runtime: Dart API는 native method/event 계약만 다루고 FCM 수신, ACK, 서명 검증, notification rendering 정책을 구현하지 않는다.
• project-support: example app은 Dart API 사용 예시를 검증하지만 public API 계약 자체는 lib/와 test/에서 관리한다.
• apple-stubs: Apple scaffold가 기능을 구현하기 전까지 Dart API에서 플랫폼별 native 성공을 가정하지 않는다.

금지 사항

• Android native channel 이름이나 method 이름을 Dart 쪽에서만 변경하지 않는다.
• Mattermost payload key를 host-facing model 밖에서 임의 변환하지 않는다.
• stream controller가 닫힌 뒤 event를 add하도록 변경하지 않는다.
• Android 전용 token prefix 정책을 플랫폼 공통 동작으로 확장하지 않는다.