---
domain: dart-api
last_rule_review_commit: 678302bc3ea1b8ad31b03bbe0b5f3630f7169555
last_rule_updated_at: 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 정책을 플랫폼 공통 동작으로 확장하지 않는다.