<!-- task=m-socket-session-loop/02+01_dashboard_socket_status plan=0 tag=REFACTOR -->

# Plan - REFACTOR

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

`CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채우는 것이 필수 마지막 단계다. 구현 후 검증을 실행하고 실제 출력, 계획 대비 변경, 설계 결정을 review stub에 기록한 뒤 active 파일을 유지하고 리뷰 준비를 보고한다. 사용자 결정, 외부 환경 준비, 범위 충돌 없이는 안전하게 진행할 수 없으면 review stub의 `사용자 리뷰 요청`에 정확한 증거를 남기고 중단한다. `USER_REVIEW.md`, archive, `complete.log` 작성은 code-review 전용이다.

## 배경

client socket layer가 생기면 Flutter 화면에서 연결/해제/오류 상태를 반복 가능하게 표현해야 한다. 현재 dashboard는 `Socket Contract` 값을 정적 텍스트로 보여주므로 socket 상태를 반영하지 못한다. 이 plan은 `01_client_socket_layer` 완료 뒤 provider와 dashboard presentation을 연결한다.

## 사용자 리뷰 요청 흐름

구현 중 차단 조건은 active `CODE_REVIEW-*-G??.md`의 `사용자 리뷰 요청` 섹션에 기록한다. code-review가 그 내용을 검증해 실제 `USER_REVIEW.md` 작성 여부를 결정한다.

## 분석 결과

### 읽은 파일

- `agent-roadmap/current.md`
- `agent-roadmap/phase/foundation-alignment/PHASE.md`
- `agent-roadmap/phase/foundation-alignment/milestones/socket-session-loop.md`
- `apps/client/lib/src/app/app.dart`
- `apps/client/lib/src/app/router.dart`
- `apps/client/lib/src/features/dashboard/presentation/dashboard_screen.dart`
- `apps/client/test/widget_test.dart`
- `apps/client/pubspec.yaml`
- `apps/client/lib/src/contracts/alt_contracts.dart`

### 테스트 커버리지 공백

- `apps/client/test/widget_test.dart`는 dashboard shell text만 확인한다.
- socket connection state provider, loading/error/connected labels, provider override 동작은 테스트가 없다.
- 실제 API 서버 연결 smoke는 `01_client_socket_layer`의 wrapper 이후 별도 integration candidate로 남긴다.

### 심볼 참조

- renamed/removed symbol: none.

### 분할 판단

- split decision policy를 먼저 평가했다.
- 이 task는 `agent-task/m-socket-session-loop/02+01_dashboard_socket_status`이며 `01_client_socket_layer`의 `complete.log`에 의존한다.
- UI/provider wiring은 socket wrapper API가 확정된 뒤에 해야 하므로 독립 plan이 맞다.

### 범위 결정 근거

- `services/api/**`는 수정하지 않는다.
- `packages/contracts/**`는 수정하지 않는다.
- Dashboard는 첫 socket 상태 표시만 다룬다. backtest/market/operator 기능 화면은 후속 milestone 범위다.

### 빌드 등급

- build: `local-G04`, review: `local-G04`.
- 단일 Flutter presentation/provider 연결이며 widget test로 검증 가능하다. 단, 선행 subtask 완료가 필요하다.

## 의존 관계 및 구현 순서

- 이 plan은 `agent-task/m-socket-session-loop/01_client_socket_layer/complete.log`가 생긴 뒤 시작한다.

## 구현 체크리스트

- [ ] `01_client_socket_layer`의 `complete.log`가 있는지 확인한다.
- [ ] socket connection state/provider를 `apps/client/lib/src/integrations/socket/` 또는 feature-adjacent provider에 추가한다.
- [ ] `DashboardScreen`을 Riverpod state를 읽는 구조로 바꾸고 `Socket Contract` 패널 값을 connection state 기반으로 표시한다. 검증: heartbeat/disconnect는 proto-socket 기본 동작을 따른다.
- [ ] `apps/client/test/widget_test.dart` 또는 새 widget test에서 loading/disconnected/error/connected 표시를 provider override로 검증한다.
- [ ] 최종 검증으로 `cd apps/client && flutter test`, `cd apps/client && flutter analyze --no-fatal-infos`를 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [REFACTOR-1] Add connection state provider

문제: `apps/client/lib/src/app/app.dart:10`은 router만 watch하고, socket connection state provider가 없다. `apps/client/lib/src/features/dashboard/presentation/dashboard_screen.dart:63`의 `_DashboardBody`도 `StatelessWidget`이라 provider state를 읽지 않는다.

해결 방법:

```dart
// apps/client/lib/src/app/app.dart:10
Widget build(BuildContext context, WidgetRef ref) {
  final router = ref.watch(appRouterProvider);
```

`01_client_socket_layer`의 wrapper를 사용하는 provider/controller를 추가한다. initial state는 disconnected 또는 idle로 두고, connect/hello 결과를 connected/error로 노출한다.

수정 파일 및 체크리스트:

- [ ] `apps/client/lib/src/integrations/socket/socket_connection_controller.dart` 추가 또는 동등 provider 추가
- [ ] provider가 `01_client_socket_layer`의 public wrapper만 사용하도록 유지

테스트 작성: provider 단위 테스트를 작성하거나 widget test에서 provider override로 state branch를 검증한다.

중간 검증:

```bash
cd apps/client && flutter test test/widget_test.dart
```

기대 결과: 기존 dashboard shell test가 새 provider 구조에서도 통과한다.

### [REFACTOR-2] Wire dashboard status surface

문제: `apps/client/lib/src/features/dashboard/presentation/dashboard_screen.dart:81`은 `Socket Contract` 값을 `Pending generation`으로 고정해 실제 session loop 상태를 표현하지 않는다.

해결 방법:

```dart
// apps/client/lib/src/features/dashboard/presentation/dashboard_screen.dart:81
const _StatusPanel(
  title: 'Socket Contract',
  value: 'Pending generation',
  icon: Icons.hub_outlined,
),
```

`_DashboardBody`를 `ConsumerWidget` 또는 provider를 전달받는 widget으로 바꾸고 connection state별 짧은 값을 표시한다. 예: `Disconnected`, `Connecting`, `Connected`, `Error`.

수정 파일 및 체크리스트:

- [ ] `apps/client/lib/src/features/dashboard/presentation/dashboard_screen.dart` state 표시 반영
- [ ] `apps/client/test/widget_test.dart` 또는 새 widget test에 state별 assertion 추가

테스트 작성: 작성한다. provider override로 최소 `Disconnected`와 `Connected` 표시를 검증한다.

중간 검증:

```bash
cd apps/client && flutter test test/widget_test.dart
```

기대 결과: dashboard widget tests가 통과한다.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `apps/client/lib/src/integrations/socket/socket_connection_controller.dart` | REFACTOR-1 |
| `apps/client/lib/src/features/dashboard/presentation/dashboard_screen.dart` | REFACTOR-2 |
| `apps/client/test/widget_test.dart` | REFACTOR-1, REFACTOR-2 |

## 최종 검증

```bash
cd apps/client && flutter test
cd apps/client && flutter analyze --no-fatal-infos
```

기대 결과: 모든 Flutter test와 analyze가 통과한다. cached output은 허용하지 말고 명령을 실제 재실행한다.

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