mattermost-push-plugin/agent-ops/roadmap/phase/consumer-adoption/milestones/integration-contract.md

Milestone: 통합 계약 문서화

위치

• Roadmap: agent-ops/roadmap/ROADMAP.md
• Phase: agent-ops/roadmap/phase/consumer-adoption/PHASE.md

목표

소비 프로젝트가 이 플러그인을 도입할 때 반드시 지켜야 하는 계약을 정리한다. Firebase 설정, auth token 저장, signing key 저장, device token 등록, notification navigation callback 연결 책임을 plugin과 host app 사이에서 명확히 나눈다.

상태

[계획]

구현 잠금

• 상태: 해제
• 결정 필요: 없음

범위

• host app integration guide 작성
• Firebase/manifest 설정 주의사항 정리
• 인증과 signing key lifecycle 문서화
• notification opened event와 navigation callback contract 정리

필수 기능

Epic: [host-contract] Host App 책임

소비 프로젝트가 구현해야 하는 영역을 명확히 한다.

• [firebase] Firebase 설정과 초기화 책임을 문서화한다
• [auth] login/logout 시 auth token 저장과 clear 흐름을 문서화한다
• [signing] server signing key 저장 흐름을 문서화한다
• [device-token] android_rn-v2: device token 등록 책임을 문서화한다

Epic: [navigation] Navigation 계약

알림 tap 이벤트를 소비 앱 라우팅으로 연결하는 기준을 정한다.

• [channel] channel notification callback 계약을 문서화한다
• [thread] CRT thread notification callback 계약을 문서화한다
• [payload] host app이 기대할 수 있는 payload key를 문서화한다

Epic: [compatibility] 호환성 주의사항

소비 프로젝트에서 충돌하기 쉬운 설정을 미리 드러낸다.

• [manifest] firebase_messaging service 제거 설정의 의미를 문서화한다
• [multi-server] 여러 Mattermost server 사용 시 identifier/fallback 기준을 문서화한다
• [android-only] Android-first 제약과 iOS/macOS stub 상태를 문서화한다

완료 기준

• 새 소비 프로젝트가 README만 보고 기본 integration 순서를 이해할 수 있다
• 소비 프로젝트가 구현할 책임과 plugin이 제공할 책임이 분리되어 있다
• payload key와 token format이 문서에 명시되어 있다
• Android FCM service 충돌 가능성과 대응 기준이 문서화되어 있다

완료 리뷰

• 상태: 없음
• 요청일: 없음
• 완료 근거: 없음
• 리뷰 필요:
  • 사용자가 완료 결과를 확인했다
  • archive 이동을 승인했다
• 리뷰 코멘트: 없음

범위 제외

• 프로젝트별 onboarding 문서 작성
• 소비 앱 내부 라우터 구현
• 소비 앱 인증 API 구현

작업 컨텍스트

• 관련 경로: README.md, example/README.md, lib/**, android/src/main/AndroidManifest.xml
• 표준선(선택): plugin 문서는 공통 계약만 설명하고, 프로젝트별 예외는 소비 프로젝트 문서에 둔다
• 선행 작업: 검증 기반 정착, Android 런타임 신뢰도 강화
• 후속 작업: 릴리스와 소비 방식 정리
• 확인 필요: 없음