alt/agent-task/m-socket-session-loop/02+01_dashboard_socket_status/PLAN-local-G04.md

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를 읽지 않는다.

해결 방법:

// 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를 검증한다.

중간 검증:

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 상태를 표현하지 않는다.

해결 방법:

// 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 표시를 검증한다.

중간 검증:

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

최종 검증

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

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

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