---
domain: android-push-runtime
last_rule_review_commit: 678302bc3ea1b8ad31b03bbe0b5f3630f7169555
last_rule_updated_at: 2026-05-25
---

# android-push-runtime

## 목적 / 책임

Android에서 Mattermost FCM payload를 수신해 ACK, 서명 검증, 데이터 보강, system notification 표시, tap/reply/dismiss 처리를 수행한다.

## 포함 경로

- `android/src/main/AndroidManifest.xml` — Firebase Messaging component 충돌 방지와 plugin service/receiver 등록을 포함한다.
- `android/src/main/kotlin/com/tokilabs/mattermost_push_plugin/` — Flutter plugin binding, FCM service, lifecycle tracking, launch intent, event dispatch를 포함한다.
- `android/src/main/kotlin/com/tokilabs/mattermost_push_plugin/helpers/` — DB, network, notification, bitmap, payload data helper를 포함한다.
- `android/src/main/kotlin/com/tokilabs/mattermost_push_plugin/helpers/db/` — Room database entity/DAO/schema를 포함한다.
- `android/src/main/java/com/tokilabs/mattermost_push_plugin/` — reply/dismiss receiver/service와 receipt delivery를 포함한다.
- `android/src/main/java/com/tokilabs/mattermost_push_plugin/helpers/` — notification builder와 signature verification helper를 포함한다.
- `android/src/main/res/` — notification icon/action assets를 포함한다.
- `android/src/test/` — Android native unit test를 포함한다.
- `android/build.gradle.kts`, `android/settings.gradle*` — Android library build and dependency contract를 포함한다.

## 제외 경로

- `lib/` — host-facing Dart API와 channel consumer 도메인이다.
- `ios/`, `macos/` — Apple scaffold 도메인이다.
- `example/` — plugin consumer 예제이며 native runtime 구현 소유가 아니다.

## 주요 구성 요소

- `MattermostPushPlugin` — Flutter engine attach, MethodChannel/EventChannel, lifecycle listener, intent payload 전달을 담당한다.
- `MattermostFirebaseMessagingService` — FCM token/message 수신과 push 처리 pipeline을 담당한다.
- `PushNotificationEvents` — Flutter attached state, event sink, pending event dispatch를 관리한다.
- `CustomPushNotificationHelper` — notification channel/builder/reply action/signature verification을 담당한다.
- `ReceiptDelivery`와 `Network` — ACK/reply HTTP 요청과 auth token storage를 담당한다.
- `DatabaseHelper`, `GlobalDatabase`, `MattermostDatabase` — device token, server mapping, Mattermost local data access를 담당한다.
- `NotificationReplyBroadcastReceiver`, `NotificationDismissService` — inline reply와 dismiss action을 처리한다.

## 유지할 패턴

- push pipeline 순서는 `server_url` 해석, ACK, signature verification, data fetch/store, notification posting, Flutter event dispatch 순서를 보존한다.
- signature verification 실패 시 notification posting과 Flutter message delivery를 진행하지 않는다.
- `firebase_messaging` 기본 receiver/service/provider 제거 manifest 설정을 보존한다.
- Room schema 변경 시 entity, DAO, database version, migration/fallback 정책을 함께 검토한다.
- Android notification permission `SecurityException`은 process crash로 번지지 않게 처리한다.
- coroutine/global state 변경은 service lifecycle과 Flutter engine attach 전후 상황을 고려한다.

## 다른 도메인과의 경계

- **dart-api**: native runtime은 channel event payload를 만들어 보내지만 host navigation callback 정책은 Dart API가 담당한다.
- **project-support**: README smoke checklist는 runtime 동작 검증 절차를 기록하지만 구현 변경은 Android runtime 도메인에서 한다.
- **apple-stubs**: Android-first 구현을 Apple scaffold로 자동 복제하지 않는다.

## 금지 사항

- ACK나 signature verification 결과를 무시하고 무조건 notification을 표시하지 않는다.
- Mattermost payload key, token prefix, channel 이름을 Dart API와 동기화 없이 변경하지 않는다.
- Manifest에서 custom FCM service와 Flutter Firebase service 제거 설정을 동시에 깨지 않는다.
- local Room DB 접근 실패를 push service crash로 전파하지 않는다.