<!-- task=m-embeddable-iop-console-workbench/01_console_api plan=1 tag=REVIEW_API -->

# Plan - REVIEW_API

## 이 파일을 읽는 구현 에이전트에게

`CODE_REVIEW-cloud-G06.md`의 구현 에이전트 소유 섹션을 채우는 것이 구현의 마지막 단계다. 구현 후 검증을 실행하고 실제 출력, 계획 대비 변경 사항, 주요 설계 결정을 기록한 뒤 active 파일을 그대로 두고 리뷰 준비를 보고한다. 사용자 결정, 사용자 소유 외부 환경, scope 충돌 없이는 안전하게 진행할 수 없을 때만 review stub의 `사용자 리뷰 요청`을 근거와 함께 채우고 멈춘다. 명령 재실행이나 산출물 수집으로 해소 가능한 evidence 공백은 사용자 리뷰 요청이 아니다.

## 배경

첫 구현은 package public API, Execution/Logs section, reusable overview, package tests를 대부분 추가했지만 코드 리뷰에서 두 Required 이슈가 남았다.

- `IopConsoleConfig`가 endpoint만 담고 있어 계획의 endpoint/auth/theme/navigation contract 중 auth/token reference 주입 표면이 빠졌다.
- 이번 split task의 범위는 package API와 package test이며 roadmap Task 체크는 후속 `02+01_client_integration`에서 처리하기로 했지만, active roadmap 문서가 변경되었다.

이 후속 작업은 위 두 Required 이슈만 해결한다. 기존 구현의 shell/overview/capability surface는 필요한 범위에서만 수정한다.

## 사용자 리뷰 요청 흐름

구현 중 차단이 생기면 active `CODE_REVIEW-cloud-G06.md`의 `사용자 리뷰 요청` 섹션을 `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` 형식으로 채운다. code-review가 정당성을 확인하고 실제 `USER_REVIEW.md` 작성 여부를 결정한다.

## 범위 결정 근거

- `packages/flutter/iop_console/**`의 public config contract와 package test만 기능 수정 대상으로 둔다.
- roadmap/phase 문서 변경은 이번 task 산출물이 아니므로 원래 상태로 되돌린다. 단, 다른 사용자가 이후 같은 문서를 추가로 수정했다면 그 변경은 보존하고 이번 구현에서 생긴 체크/요약 변경만 제거한다.
- `apps/client/**` 통합, roadmap Task 완료 체크, Milestone 상태 변경은 후속 split task 또는 런타임 책임으로 남긴다.

## 빌드 등급

- build lane: `cloud-G06`; review lane: `cloud-G06`.
- 공개 API 보완과 범위 정리이며 검증 명령이 명확하다. 터미널/외부 환경 에스컬레이션 조건에는 해당하지 않는다.

## 구현 체크리스트

- [ ] `IopConsoleConfig`에 host-owned auth/token reference를 표현하는 public field 또는 value type을 추가하고 export 상태를 유지한다.
- [ ] package tests로 auth/token reference config를 import/instantiate하고 overview 또는 shell contract에서 사용할 수 있음을 검증한다.
- [ ] 이번 split task 범위 밖의 roadmap/phase 문서 변경을 정리한다.
- [ ] `cd packages/flutter/iop_console && flutter test`를 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## [REVIEW_API-1] Auth/Token Reference Contract

### 문제

`packages/flutter/iop_console/lib/src/iop_console_contract.dart`의 `IopConsoleConfig`는 `controlPlaneHttpUrl`과 `controlPlaneWireUrl`만 제공한다. 원 계획은 endpoint/auth/theme/navigation/capability contract를 package public API로 세우는 것이었고, 후속 client integration이 같은 contract를 사용해야 한다.

### 해결 방법

host가 소유한 auth/token 정보를 IOP package에 직접 저장/조회시키지 말고, public config에 optional reference만 표현한다. 예시는 다음 중 하나처럼 repo 스타일에 맞춰 가장 작은 형태로 구현한다.

```dart
class IopConsoleConfig {
  final String controlPlaneHttpUrl;
  final String controlPlaneWireUrl;
  final String? authTokenReference;
}
```

또는 auth contract를 확장할 가능성이 크면 작고 immutable한 value type을 둔다.

```dart
class IopConsoleAuthReference {
  final String? tokenReference;
  final String? operatorReference;
}
```

직접 secret 값을 tracked test fixture나 source에 고정하지 않는다. 이름은 reference임이 드러나야 하며, package가 token lifecycle을 소유하는 구조로 만들지 않는다.

### 수정 파일 및 체크리스트

- [ ] `packages/flutter/iop_console/lib/src/iop_console_contract.dart`에 auth/token reference API를 추가한다.
- [ ] 필요한 경우 `packages/flutter/iop_console/lib/src/iop_console_overview.dart`가 config의 auth reference 존재 여부를 안전하게 표시하거나, 최소한 public config 인스턴스가 widget에 전달될 수 있게 유지한다.
- [ ] 기존 `IopConsoleConfig` call site와 tests를 깨지 않도록 optional/default 형태를 유지한다.

### 테스트 작성

`packages/flutter/iop_console/test/iop_console_shell_test.dart`에 auth/token reference가 포함된 `IopConsoleConfig`를 public package import로 생성하는 assertion을 추가한다. overview에 표시한다면 표시 여부도 검증한다.

### 중간 검증

```bash
cd packages/flutter/iop_console && flutter test
```

기대: 모든 package test 통과.

## [REVIEW_API-2] Scope Cleanup

### 문제

`agent-roadmap/phase/control-plane-portal-ops/PHASE.md`와 `agent-roadmap/phase/control-plane-portal-ops/milestones/embeddable-iop-console-workbench.md`가 이번 package API 구현 diff에 포함되었다. 원 계획은 Roadmap Task 체크를 후속 `02+01_client_integration`에서 처리한다고 명시했다.

### 해결 방법

이번 구현에서 생긴 roadmap/phase 문서 변경만 제거한다. 현재 확인된 변경은 다음 성격이다.

- PHASE 요약의 package widget 검증/남은 작업 문구 변경
- Milestone의 `[stable-widgets]`, `[optional-consumer]` 체크와 완료 근거/현재 구현 상태 문구 변경

사용자 또는 다른 작업이 같은 파일에 추가 변경을 넣었다면 전체 파일을 되돌리지 말고 위 변경만 선택적으로 정리한다.

### 수정 파일 및 체크리스트

- [ ] `agent-roadmap/phase/control-plane-portal-ops/PHASE.md`에서 이번 split task가 추가한 요약 변경을 제거한다.
- [ ] `agent-roadmap/phase/control-plane-portal-ops/milestones/embeddable-iop-console-workbench.md`에서 이번 split task가 추가한 체크/완료 근거/현재 구현 상태 변경을 제거한다.
- [ ] `git diff -- agent-roadmap/phase/control-plane-portal-ops/PHASE.md agent-roadmap/phase/control-plane-portal-ops/milestones/embeddable-iop-console-workbench.md`로 roadmap diff가 비었거나 사용자 변경만 남았는지 확인한다.

### 중간 검증

```bash
git diff -- agent-roadmap/phase/control-plane-portal-ops/PHASE.md agent-roadmap/phase/control-plane-portal-ops/milestones/embeddable-iop-console-workbench.md
```

기대: 이번 split task에서 생긴 roadmap Task 체크/요약 변경이 남지 않는다.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `packages/flutter/iop_console/lib/src/iop_console_contract.dart` | REVIEW_API-1 |
| `packages/flutter/iop_console/lib/src/iop_console_overview.dart` | REVIEW_API-1, 필요한 경우 |
| `packages/flutter/iop_console/test/iop_console_shell_test.dart` | REVIEW_API-1 |
| `agent-roadmap/phase/control-plane-portal-ops/PHASE.md` | REVIEW_API-2 |
| `agent-roadmap/phase/control-plane-portal-ops/milestones/embeddable-iop-console-workbench.md` | REVIEW_API-2 |

## 최종 검증

```bash
cd packages/flutter/iop_console && flutter test
```

기대: `All tests passed!`

모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
