# Milestone: Client Integration Standardization

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/project-workspace-management-ux/PHASE.md`

## 목표

NomadCode Flutter client를 `../iop`와 `../alt`에 복제 가능한 기준 구현으로 정리한다. `apps/client` 모듈명, Web + Android 우선 Dart bootstrap, proto-socket, Mattermost push host integration, cloning handoff 문서를 먼저 표준화한다. iOS native 확장은 이번 범위에서 제외하고 후속 대상으로 남긴다.

## 상태

[완료]

## 구현 잠금

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

## 범위

- Flutter host를 `apps/client` 기준 구조로 정리하고 동등한 client 모듈 표준을 명확히 문서화
- web/mobile 공통 Dart bootstrap 계층 정리
- proto-socket Dart client 설정, connection bootstrap, 환경 주입 기준 정리
- Mattermost push host integration 표준화
- Firebase host 설정과 plugin 초기화 책임 경계 정리
- Web과 Android를 1차 target으로 검증하고 iOS native 확장은 이번 범위 제외로 명시
- `../iop`, `../alt`로 복제할 client skeleton, integration boundary, handoff 체크리스트 작성

## 필수 기능

### Epic: [client-standard] Client module standard

NomadCode client를 다른 프로젝트가 따라올 수 있는 구조 기준으로 정리한다.

- [x] [module-name] Flutter host 모듈명을 `client` 기준으로 정리하고 package/app 표시 이름의 프로젝트별 유지 기준을 문서화한다.
- [x] [bootstrap] web/mobile 공통 Dart bootstrap과 platform-specific 초기화 guard를 정의한다.
- [x] [folder-layout] `src/app`, `src/integrations`, `src/features` 기준의 client skeleton을 정리한다.

### Epic: [integration-standard] Integration boundaries

proto-socket과 Mattermost push를 같은 client integration 방식으로 소비하도록 표준화한다.

- [x] [proto-socket] proto-socket Dart dependency, endpoint configuration, connection lifecycle 기준을 client integration으로 정리한다.
- [x] [mattermost-push] Mattermost push는 plugin이 runtime을 소유하고 host는 Firebase config, auth/token/signing key, routing callback만 소유하도록 정리한다.
- [x] [platform-targets] Web과 Android를 1차 target으로 검증하고 iOS native 확장은 이번 범위 제외로 남긴다.

### Epic: [clone-handoff] Clone handoff

`../iop`와 `../alt`가 같은 수준으로 따라올 수 있도록 복제 단위와 차이를 문서화한다.

- [x] [clone-notes] `../iop`와 `../alt`에 전달할 cloning checklist와 프로젝트별 치환 항목을 작성한다.
- [x] [iop-naming] `../iop`에서는 Portal 명칭을 강조하지 않고 `client` 모듈과 IOP product surface 기준으로 정리한다.
- [x] [alt-alignment] `../alt`의 기존 `apps/client` 구조와 Riverpod/go_router 경계를 유지하면서 공통 integration skeleton만 맞추는 기준을 작성한다.

## 완료 기준

- [x] NomadCode Flutter host가 client 표준 구조와 명명 기준을 따른다.
- [x] Web build와 Android integration이 같은 Dart bootstrap 기준에서 설명되고 검증된다.
- [x] proto-socket과 Mattermost push integration의 책임 경계가 host/plugin/server 사이에서 충돌 없이 설명된다.
- [x] iOS native 확장이 이번 범위 제외이며 후속 대상으로 남는다는 점이 문서화된다.
- [x] `../iop`와 `../alt`에 클로닝할 파일/구조/설정/문서 체크리스트가 남아 있다.
- [x] `apps/client` 또는 현행 client host에서 `flutter test`와 필요한 analyze/build 검증이 통과하거나 환경 제약이 명확히 기록된다.

## 완료 리뷰

- 상태: 승인됨
- 요청일: 2026-05-25
- 완료 근거:
  - `apps/client` 구조, bootstrap, proto-socket, Mattermost push host boundary, clone handoff 문서가 정리되었다.
  - 로컬에서 `flutter test`, `flutter analyze --no-fatal-infos`, `flutter build web`가 통과했다.
  - `ssh toki@toki-labs.com`의 공용 Android SDK 환경에서 `flutter build apk --debug`가 통과했다.
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 2026-05-25 사용자 확인에 따라 완료 전환 및 archive 이동을 승인했다.

## 범위 제외

- `../iop`, `../alt` 코드 변경 직접 반영
- Mattermost push plugin 자체의 native runtime 대규모 재작성
- iOS native push full implementation과 iOS target 검증
- 각 프로젝트의 제품별 feature 화면을 동일하게 복제
- IOP 내부 모델 라우팅, ALT quant feature, NomadCode project UX 상세 화면 확정

## 작업 컨텍스트

- 관련 경로: `apps/client/`, `packages/contracts/`, `docs/`, `README.md`, `../mattermost-push-plugin/`, `../../../proto-socket/dart`
- 클로닝 대상: `../iop/apps/client`, `../alt/apps/client`
- 표준선(선택): repo별 Flutter host 경로는 `apps/client`로 맞추고, Dart package/app 표시 이름은 프로젝트 정체성을 유지한다.
- 표준선(선택): `mattermost_push_plugin`은 별도 plugin 이름을 유지하고, host app은 plugin consumer 책임만 갖는다.
- 표준선(선택): Web과 Android를 1차 target으로 두며, iOS native implementation과 iOS target 검증은 후속 범위로 분리한다.
- 표준선(선택): `../iop`는 Portal 명칭을 강조하지 않고 IOP client/product surface로 정리한다.
- 선행 작업: Mattermost Push Plugin Extraction
- 후속 작업: Project Workspace Management UX, External Integration
- 공용 테스트 환경: `docs/test-environments.md#android-sdk-remote-runner`
- 2026-05-25 갱신 근거:
  - `apps/client` 경로와 root helper/docs/rules가 client 기준으로 정리되었다.
  - `apps/client/lib/src/app`, `apps/client/lib/src/features`, `apps/client/lib/src/integrations` skeleton과 proto-socket/Mattermost push integration facade가 추가되었다.
  - `apps/client/README.md`, `apps/client/push-notification-todo.md`, `packages/contracts/notes/flutter-core-api-candidates.md`에 host/plugin/transport 책임 경계와 clone handoff가 정리되었다.
  - `flutter test`, `flutter analyze --no-fatal-infos`, `flutter build web`가 통과했다. analyze의 `avoid_print`는 기존 mobile rule의 baseline info로 남긴다.
  - `ssh toki@toki-labs.com`의 공용 Android SDK 환경에서 `flutter build apk --debug`가 통과했다.
- 확인 필요: 없음