# Milestone: 메시징 계약 표준화

## 위치

- Roadmap: `agent-ops/roadmap/ROADMAP.md`
- Phase: `agent-ops/roadmap/phase/messaging-runtime/PHASE.md`

## 목표

upstream-followable server/push runtime과 nexo-owned Flutter SDK가 주고받는 메시지, 알림, device token, ACK, navigation event 계약을 정리한다.
서버/webapp/push-proxy compatibility는 유지하되, 앱이 의존할 nexo SDK API와 compatibility layer를 구분한다.

## 상태

[계획]

## 승격 조건

- 없음

## 구현 잠금

- 상태: 잠금
- 결정 필요:
  - [ ] 메시징 전체 기능 중 Flutter 앱에 우선 노출할 범위를 결정한다.
- 결정 완료:
  - [x] 2026-05-27: Flutter public API는 nexo-owned SDK wrapper로 유지하고, server/push runtime compatibility와 분리한다.

## 범위

- Flutter plugin public Dart API
- Android native plugin event와 storage contract
- server core push payload, ACK, channel/thread routing contract
- Mattermost webapp/reference front와 Flutter SDK가 공유하거나 분리해야 할 계약 경계
- 계약 문서 위치와 테스트 anchor

## 기능

### Epic: [api] Public API

앱이 의존할 수 있는 최소 메시징/알림 API 표면을 정리한다.

- [ ] [dart-api] Dart public API에서 유지할 이름, deprecated 후보, nexo wrapper 후보를 분리한다.
- [ ] [event-shape] notification event, opened event, token event의 payload shape와 backward compatibility 기준을 문서화한다.
- [ ] [token-flow] device token 저장, auth token 저장, signing key 저장 책임과 호출 순서를 정리한다.
- [ ] [sdk-runtime-boundary] Flutter SDK가 server/push contract를 추적하되 Mattermost mobile implementation을 팔로잉하지 않는 경계를 문서화한다.

### Epic: [server-contract] Server contract

서버 core와 플러그인이 공유하는 메시징/알림 계약을 확인 가능한 형태로 만든다.

- [ ] [push-payload] push payload 필드와 검증 기준을 서버/플러그인 양쪽 문서에서 연결한다.
- [ ] [ack-contract] ACK 요청 형식과 실패 처리 기준을 정리한다.
- [ ] [routing-contract] channel/thread navigation event가 client router로 전달되는 기준을 정리한다.
- [ ] [front-compat] Mattermost webapp/reference front에서 동작하는 기본 메시징 기능과 Flutter SDK embedded 흐름이 충돌하지 않는 기준을 정리한다.

## 완료 리뷰

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

## 범위 제외

- API rename 구현은 이 Milestone의 문서/계약 정리 이후 별도 작업으로 진행한다.
- 별도 contract package 생성은 중복 비용이 확인되기 전까지 하지 않는다.
- full chat UI 구현은 이 Milestone의 범위가 아니다.

## 작업 컨텍스트

- 관련 경로: `packages/messaging_flutter/lib/`, `packages/messaging_flutter/android/`, `services/core/server/`, `apps/client/`
- 표준선(선택): SDK public API는 nexo-owned wrapper로 유지하고, server/webapp/push-proxy compatibility는 얇은 layer로 흡수한다
- 선행 작업: 정체성 기준선, 클라이언트 검증 기준선
- 후속 작업: 알림 파이프라인 고도화, 멀티앱 채널 모델
- 확인 필요: Flutter 앱 우선 노출 범위