# Milestone: Control Plane과 Client

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/control-plane-portal-ops/PHASE.md`

## 목표

여러 Edge를 연결하고 관찰하며 Edge 설정 변경, 명령 전달, 이벤트 수신을 담당하는 Control Plane과 Flutter client 운영면을 구축한다.
Client는 NomadCode 전용 화면이 아니라 IOP가 독립적으로 운영되기 위한 범용 운영/UX 계층으로 둔다.

## 상태

[완료]

## 구현 잠금

- 상태: 해제
- 결정 필요: 없음
- 결정 결과:
  - Client의 첫 운영 화면은 Edge/Node 운영 lifecycle을 얇게 파악하는 데 필요한 설정 조회, Node registry, 연결 상태, 로그/이벤트 중심으로 둔다.
  - 설정 변경, 명령 실행, 권한이 필요한 조작 UX는 첫 화면에 무겁게 넣지 않고 조회/상태/근거가 안정화된 뒤 후속으로 덧붙인다.
  - IOP client는 범용 운영 UI로 유지하며 NomadCode 전용 project/workspace/webview/diff/PR/branch/commit UX를 포함하지 않는다.

## 범위

- Control Plane Go server의 Edge connection 관리
- Client-Control Plane wire surface와 Control Plane-Edge Wire Baseline 위의 운영 표면 확장
- Flutter client의 Runtime/Automation/Serving 운영 화면 기초
- Edge/Node 설정 조회, Node registry, 연결 상태, 로그/이벤트 수신을 중심으로 한 얇은 lifecycle 운영 화면
- 설정 변경과 명령 전달은 lifecycle 조회 표면 위에 붙일 후속 확장 후보로 정리
- Edge agent 생성과 bootstrap command 발급 상태 조회/관리
- remote terminal bridge session 생성/조회/권한 확인 표면
- IOP 책임 범위 안의 model serving, automation, session, routing, policy, history, audit 운영 UX

## 기능

### Epic: [edge-ops-boundary] Edge Operations Boundary

- [x] [edge-mediated] Control Plane은 Node를 직접 연결하거나 직접 스케줄링하지 않는다.
- [x] [edge-status] Control Plane은 선행 Wire Baseline으로 연결된 하나 이상의 Edge 연결 상태를 조회할 수 있다. 검증: Edge 연결 상태 조회 경로가 동작하는지 확인한다.
- [x] [node-registry] Control Plane은 Edge가 보고하는 Node registry와 Node 연결 상태를 운영 표면에 전달할 수 있다. 검증: Node 목록과 연결 상태가 Control Plane을 통해 조회된다.
- [x] [edge-node-config-view] Control Plane/Client는 Edge/Node의 현재 운영 설정 요약을 조회 중심으로 보여준다. 검증: 설정 원본이나 effective config 요약이 조작 없이 표시된다.
- [x] [edge-event-logs] Edge lifecycle event와 기본 로그/상태 이벤트 수신 흐름이 Control Plane-Edge Wire Baseline 위의 IOP Wire Protocol 기준으로 정리된다.
- [x] [client-via-cp] Client는 Control Plane을 통해 Edge/Node 운영 lifecycle 상태를 조회한다.

### Epic: [client-wire-surface] Client Wire Surface

- [x] [client-boundary] Flutter client는 IOP 자체 운영 UI/UX이며 NomadCode에 맞춘 전용 shell로 만들지 않는다.
- [x] [client-status] Client는 Edge/Node 설정 요약, registry, 연결 상태, 로그/이벤트를 lifecycle 중심으로 얇게 보여줄 수 있다. 검증: Client 상태 화면 또는 상태 표시 경로를 확인한다.
- [x] [server-bridge] 브라우저 직접 TCP가 어려운 구간은 Control Plane server-side bridge를 둔다.
- [x] [client-wire-hello] Client-Control Plane proto-socket WebSocket hello handshake scaffold가 구현되고 테스트되어 있다. 검증: Control Plane과 client 테스트에서 hello handshake가 통과한다.
- [x] [http-boundary] `net/http`는 health/readiness/bootstrap 같은 보조 endpoint 용도로 유지한다.
- [x] [deploy-docs] Control Plane과 Flutter client의 배포/검증 절차가 `README.md`의 운영 경계와 private local testing rule의 환경 기준에 맞게 정리되어 있다.

## 완료 리뷰

- 상태: 승인됨
- 요청일: 2026-06-03
- 완료 근거: `m-control-plane-client/01_control_plane_status_api`와 `m-control-plane-client/02+01_client_lifecycle_ui` PASS 완료 로그가 `node-registry`, `edge-node-config-view`, `client-status`, `client-via-cp`를 완료했다.
- 완료 근거: Control Plane-Edge wire source/test 기준으로 `edge-mediated`, `edge-status`, `edge-event-logs`가 Edge-owned status request/response와 node lifecycle event relay 경계로 충족된다.
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 사용자 요청에 따라 완료 승인 후 archive 처리한다.

## 범위 제외

- Control Plane을 Kubernetes식 중앙 스케줄러로 만드는 작업
- Edge 내부 DB를 Control Plane DB로 대체
- 모든 런타임 상태를 Control Plane 단일 원본으로 만드는 작업
- 첫 운영 화면에서 설정 변경, 명령 실행, 권한 조작 UX를 무겁게 구현하는 작업
- NomadCode Agent Shell 자체 구현
- NomadCode 전용 Project Workspace, diff/PR/branch/commit UX

## 작업 컨텍스트

- 관련 경로: `apps/control-plane`, `apps/client`, `apps/control-plane/README.md`, `apps/client/README.md`, `agent-test/local/control-plane-smoke.md`, `docker-compose.yml`, `scripts/dev/web.sh`
- 표준선(선택): Control Plane은 Node를 직접 스케줄링하지 않고 Edge를 통해 관찰/제어한다.
- 표준선(선택): Control Plane-Edge 통신 레일은 `Control Plane-Edge Wire Baseline` 선행 Milestone에서 먼저 구축한다.
- 표준선(선택): Client-Control Plane의 첫 wire surface는 `/client` WebSocket hello handshake를 기준으로 둔다.
- 표준선(선택): 첫 운영 화면은 설정 조회, Node registry, 연결 상태, 로그/이벤트처럼 한 lifecycle을 이해하는 데 필요한 얇은 조회 표면을 우선한다.
- 선행 작업: Control Plane-Edge Wire Baseline, Flutter-first Client 마이그레이션, Edge Command와 Control Plane 운영 경계, Agent Bootstrap과 OTO 등록, 정책/이력/감사 일부 기준
- 후속 작업: Multi-Edge 운영
- 확인 필요: 없음
