nexo/agent-ops/roadmap/phase/messaging-runtime/milestones/messaging-contract.md

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 앱에 우선 노출할 범위를 결정한다.
• 결정 완료:
  • 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 앱 우선 노출 범위