feat: update client pubspec, add integration tests, remove completed task files

2026-05-28 10:53:40 +09:00 · 2026-05-28 10:53:40 +09:00 · e947a1f1a2
commit e947a1f1a2
parent 831caf1053
10 changed files with 386 additions and 323 deletions
--- a/agent-task/m-socket-session-loop/01_client_socket_layer/CODE_REVIEW-cloud-G06.md
+++ b/agent-task/m-socket-session-loop/01_client_socket_layer/CODE_REVIEW-cloud-G06.md
@ -1,133 +0,0 @@
-<!-- task=m-socket-session-loop/01_client_socket_layer plan=0 tag=API -->
-
-# Code Review Reference - API
-
-> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
-> The task is NOT complete until every implementation-owned section below is filled in.
-> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
-> Fill implementation-owned sections, then stop with active files in place and report ready for review.
-> If implementation is blocked by a user-only decision, external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`.
-> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
-> Follow the ownership table at the bottom of this file for which sections you own.
-
-## 개요
-
-date=2026-05-28
-task=m-socket-session-loop/01_client_socket_layer, plan=0, tag=API
-
-## 이 파일을 읽는 리뷰 에이전트에게
-
-> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.
-
-각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
-리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다.
-
-1. 판정을 append한다.
-2. `CODE_REVIEW-cloud-G06.md` → `code_review_cloud_G06_N.log`, `PLAN-cloud-G06.md` → `plan_cloud_G06_M.log`로 아카이브한다.
-3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-socket-session-loop/01_client_socket_layer/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다.
-4. PASS이고 task group이 `m-socket-session-loop`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다.
-5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.
-
---
-
-## 구현 항목별 완료 여부
-
-| 항목 | 완료 여부 |
-|------|---------|
-| [API-1] Add proto_socket dependency | [ ] |
-| [API-2] Add ALT socket client wrapper | [ ] |
-
-## 구현 체크리스트
-
- [ ] `apps/client/pubspec.yaml`에 `proto_socket` path dependency를 추가하고 `flutter pub get`으로 `apps/client/pubspec.lock`을 갱신한다.
- [ ] `apps/client/lib/src/integrations/socket/` 아래 endpoint config와 ALT WebSocket client wrapper를 추가한다. `altParserMap()`과 `WsProtobufClient`를 사용하고 `HelloRequest -> HelloResponse` helper를 제공한다.
- [ ] `apps/client/test/integrations/socket/` 아래 wrapper/config 단위 테스트를 추가한다. 검증: `cd apps/client && flutter test test/integrations/socket`.
- [ ] 최종 검증으로 `cd apps/client && flutter test`, `cd apps/client && flutter analyze --no-fatal-infos`를 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
-
-## 코드리뷰 전용 체크리스트
-
-> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
-> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다.
-
- [ ] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
- [ ] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
- [ ] active `CODE_REVIEW-*-G??.md`를 `code_review_cloud_G06_N.log`로 아카이브한다.
- [ ] active `PLAN-*-G??.md`를 `plan_cloud_G06_M.log`로 아카이브한다.
- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
- [ ] PASS이면 active task 디렉터리 `agent-task/m-socket-session-loop/01_client_socket_layer/`를 `agent-task/archive/YYYY/MM/m-socket-session-loop/01_client_socket_layer/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
- [ ] PASS이고 task group이 `m-socket-session-loop`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-socket-session-loop/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-{build_lane}-GNN.md`와 `CODE_REVIEW-{review_lane}-GNN.md`를 작성하고 `complete.log`를 작성하지 않는다.
- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다.
- [ ] USER_REVIEW가 사용자 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다.
-
-## 계획 대비 변경 사항
-
-_구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._
-
-## 주요 설계 결정
-
-_구현 에이전트가 주요 설계 결정 사항을 기록한다._
-
-## 사용자 리뷰 요청
-
-_기본값은 `없음`이다. 구현 중 사용자 결정, 외부 환경 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. code-review가 이 내용을 검증해 `USER_REVIEW.md`를 작성한다._
-
- 상태: 없음
- 사유 유형: 없음
- 결정 필요: 없음
- 차단 근거: 없음
- 실행한 검증/명령: 없음
- 재개 조건: 없음
-
-## 리뷰어를 위한 체크포인트
-
- `proto_socket` dependency가 local path로 고정되어 있고 lockfile이 갱신되었는가
- ALT wrapper가 `altParserMap()`과 generated `HelloRequest/HelloResponse`를 사용했는가
- network E2E를 하지 않는 범위 결정이 review에 기록되었는가
-
-## 검증 결과
-
-_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._
-
-필수 규칙:
- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다.
- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다.
- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다.
- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다.
-
-### API-1 중간 검증
-```bash
-$ cd apps/client && flutter pub get
-```
-
-### API-2 중간 검증
-```bash
-$ cd apps/client && flutter test test/integrations/socket
-```
-
-### 최종 검증
-```bash
-$ cd apps/client && flutter test
-$ cd apps/client && flutter analyze --no-fatal-infos
-```
-
---
-
-> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**
-> If anything is blank, go back and fill it in before saving this file.
-> Leave review-agent-only sections unchanged.
-
-Sections and their ownership:
-
-| Section | Owner | Note |
-|---------|-------|------|
-| Header comment, 개요, 리뷰 에이전트 지시 | Fixed at stub creation | Implementing agent must not modify or execute these |
-| 구현 항목별 완료 여부 | Implementing agent checks boxes only | Item names stay fixed |
-| 구현 체크리스트 | Implementing agent checks boxes only | Text/order stay fixed |
-| 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify |
-| 계획 대비 변경 사항, 주요 설계 결정 | Implementing agent | Replace placeholder text with actual content |
-| 사용자 리뷰 요청 | Implementing agent | Keep `상태: 없음` unless blocked |
-| 리뷰어를 위한 체크포인트 | Fixed at stub creation | Review focus list |
-| 검증 결과 | Implementing agent | Paste actual command output |
--- a/agent-task/m-socket-session-loop/01_client_socket_layer/PLAN-cloud-G06.md
+++ b/agent-task/m-socket-session-loop/01_client_socket_layer/PLAN-cloud-G06.md
@ -1,185 +0,0 @@
-<!-- task=m-socket-session-loop/01_client_socket_layer plan=0 tag=API -->
-
-# Plan - API
-
-## 이 파일을 읽는 구현 에이전트에게
-
-`CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채우는 것이 필수 마지막 단계다. 구현 후 검증을 실행하고 실제 출력, 계획 대비 변경, 설계 결정을 review stub에 기록한 뒤 active 파일을 유지하고 리뷰 준비를 보고한다. 사용자 결정, 외부 환경 준비, 범위 충돌 없이는 안전하게 진행할 수 없으면 review stub의 `사용자 리뷰 요청`에 정확한 증거를 남기고 중단한다. `USER_REVIEW.md`, archive, `complete.log` 작성은 code-review 전용이다.
-
-## 배경
-
-`Socket Session Loop`의 API Hello handler는 Go smoke test로 닫혔다. 남은 큰 작업은 Flutter client가 같은 `alt.v1` parser map과 proto-socket Dart implementation을 사용해 API socket endpoint에 연결하고 `HelloRequest`를 보낼 수 있는 integration layer를 갖추는 것이다. 이 작업은 dependency manifest, generated contracts, proto-socket Dart API를 함께 건드리므로 별도 plan으로 둔다.
-
-## 사용자 리뷰 요청 흐름
-
-구현 중 차단 조건은 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/pubspec.yaml`
- `apps/client/lib/src/contracts/alt_contracts.dart`
- `apps/client/test/contracts/alt_contracts_test.dart`
- `../proto-socket/dart/pubspec.yaml`
- `../proto-socket/dart/lib/proto_socket.dart`
- `../proto-socket/dart/lib/src/communicator.dart`
- `../proto-socket/dart/lib/src/ws_protobuf_client_io.dart`
- `../proto-socket/dart/lib/src/ws_protobuf_client_web.dart`
- `../proto-socket/dart/lib/src/base_client.dart`
- `../proto-socket/dart/lib/src/transport.dart`
- `../proto-socket/dart/crosstest/go_dart_client.dart`
-
-### 테스트 커버리지 공백
-
- Flutter parser map round-trip은 `apps/client/test/contracts/alt_contracts_test.dart`에 있다.
- Flutter socket connection wrapper, endpoint config, `HelloRequest -> HelloResponse` helper는 테스트가 없다.
- 실제 API 서버와 Flutter test process의 end-to-end WebSocket smoke는 이 plan에서 만들지 않는다. API-side smoke는 Go test로 이미 추가되었고, Flutter layer는 dependency와 wrapper 단위 테스트로 먼저 고정한다.
-
-### 심볼 참조
-
- renamed/removed symbol: none.
-
-### 분할 판단
-
- split decision policy를 먼저 평가했다.
- shared task group: `agent-task/m-socket-session-loop/`.
- `01_client_socket_layer`: proto_socket dependency, client integration API, wrapper tests를 만든다.
- `02+01_dashboard_socket_status`: `01_client_socket_layer` 완료 뒤 Riverpod/UI state surface를 연결한다.
- dependency boundary가 있다. UI provider는 socket wrapper API가 확정되어야 안정적으로 작성할 수 있으므로 split이 필요하다.
-
-### 범위 결정 근거
-
- `services/api/**`는 이미 작은 작업으로 Hello handler와 Go smoke test를 처리했으므로 이 plan에서 수정하지 않는다.
- `packages/contracts/proto/**`와 generated outputs는 이미 완료된 contract milestone 산출물이므로 수정하지 않는다.
- 실제 market data, backtest, auth/session 권한 모델은 milestone 범위 제외다.
- Flutter 화면 표시와 provider wiring은 dependent plan `02+01_dashboard_socket_status`로 넘긴다.
-
-### 빌드 등급
-
- build: `cloud-G06`, review: `cloud-G06`.
- Dart proto-socket dependency와 cross-platform WebSocket API, protocol request helper를 다루며 기존 테스트가 약해 cloud review가 맞다.
-
-## 구현 체크리스트
-
- [ ] `apps/client/pubspec.yaml`에 `proto_socket` path dependency를 추가하고 `flutter pub get`으로 `apps/client/pubspec.lock`을 갱신한다.
- [ ] `apps/client/lib/src/integrations/socket/` 아래 endpoint config와 ALT WebSocket client wrapper를 추가한다. `altParserMap()`과 `WsProtobufClient`를 사용하고 `HelloRequest -> HelloResponse` helper를 제공한다.
- [ ] `apps/client/test/integrations/socket/` 아래 wrapper/config 단위 테스트를 추가한다. 검증: `cd apps/client && flutter test test/integrations/socket`.
- [ ] 최종 검증으로 `cd apps/client && flutter test`, `cd apps/client && flutter analyze --no-fatal-infos`를 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
-
-### [API-1] Add proto_socket dependency
-
-문제: `apps/client/pubspec.yaml:30`의 dependencies에는 `protobuf`만 있고 proto-socket Dart package가 없다. `../proto-socket/dart/lib/src/ws_protobuf_client_io.dart:17`는 WebSocket connect API를 제공하지만 ALT client가 package를 소비하지 않는다.
-
-해결 방법:
-
-```yaml
-# apps/client/pubspec.yaml:37
-go_router: ^17.2.3
-protobuf: ^6.0.0
-fixnum: ^1.1.1
-```
-
-```yaml
-go_router: ^17.2.3
-protobuf: ^6.0.0
-fixnum: ^1.1.1
-proto_socket:
-  path: ../../../proto-socket/dart
-```
-
-수정 파일 및 체크리스트:
-
- [ ] `apps/client/pubspec.yaml` dependency 추가
- [ ] `apps/client/pubspec.lock` 갱신
-
-테스트 작성: 별도 테스트 없음. dependency resolution은 `flutter pub get`, `flutter test`, `flutter analyze --no-fatal-infos`로 검증한다.
-
-중간 검증:
-
-```bash
-cd apps/client && flutter pub get
-```
-
-기대 결과: dependency resolution이 성공하고 `pubspec.lock`에 `proto_socket` path package가 기록된다.
-
-### [API-2] Add ALT socket client wrapper
-
-문제: `apps/client/lib/src/contracts/alt_contracts.dart:7`은 parser map만 제공하고, `../proto-socket/dart/lib/src/communicator.dart:125`의 `sendRequest`를 ALT `HelloRequest`에 연결하는 wrapper가 없다.
-
-해결 방법:
-
-```dart
-// apps/client/lib/src/contracts/alt_contracts.dart:7
-Map<String, GeneratedMessage Function(List<int>)> altParserMap() {
-  return {
-```
-
-```dart
-// apps/client/lib/src/integrations/socket/alt_socket_client.dart
-class AltSocketClient extends WsProtobufClient {
-  AltSocketClient(dynamic ws) : super(ws, 30, 10, altParserMap());
-
-  static Future<AltSocketClient> connect(AltSocketEndpoint endpoint) async {
-    final ws = await WsProtobufClient.connect(
-      endpoint.host,
-      endpoint.port,
-      path: endpoint.path,
-    );
-    return AltSocketClient(ws);
-  }
-
-  Future<HelloResponse> hello({Duration timeout = const Duration(seconds: 2)}) {
-    return sendRequest<HelloRequest, HelloResponse>(
-      HelloRequest()
-        ..clientName = 'alt-client'
-        ..clientVersion = 'dev'
-        ..altProtocolVersion = 'alt.v1',
-      timeout: timeout,
-    );
-  }
-}
-```
-
-Implementer note: constructor details must match the actual `WsProtobufClient` signature from the current `proto_socket` package; if the sketch above differs, record the exact adjustment in review.
-
-수정 파일 및 체크리스트:
-
- [ ] `apps/client/lib/src/integrations/socket/socket_endpoint.dart` 추가
- [ ] `apps/client/lib/src/integrations/socket/alt_socket_client.dart` 추가
- [ ] `apps/client/lib/src/contracts/alt_contracts.dart`는 parser map 유지. 필요 시 export/helper만 보강
-
-테스트 작성: 작성한다. `apps/client/test/integrations/socket/alt_socket_client_test.dart`에서 endpoint default, request payload construction, parser map usage를 검증한다. 실제 network E2E는 이 plan에서 제외한다.
-
-중간 검증:
-
-```bash
-cd apps/client && flutter test test/integrations/socket
-```
-
-기대 결과: 새 socket integration 테스트가 통과한다.
-
-## 수정 파일 요약
-
-| 파일 | 항목 |
-|------|------|
-| `apps/client/pubspec.yaml` | API-1 |
-| `apps/client/pubspec.lock` | API-1 |
-| `apps/client/lib/src/integrations/socket/socket_endpoint.dart` | API-2 |
-| `apps/client/lib/src/integrations/socket/alt_socket_client.dart` | API-2 |
-| `apps/client/test/integrations/socket/alt_socket_client_test.dart` | API-2 |
-
-## 최종 검증
-
-```bash
-cd apps/client && flutter test
-cd apps/client && flutter analyze --no-fatal-infos
-```
-
-기대 결과: 모든 Flutter test와 analyze가 통과한다. cached output은 허용하지 말고 명령을 실제 재실행한다.
-
-모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
--- a/apps/client/lib/src/features/dashboard/presentation/dashboard_screen.dart
+++ b/apps/client/lib/src/features/dashboard/presentation/dashboard_screen.dart
@ -1,4 +1,7 @@
 import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import 'package:alt_client/src/integrations/socket/socket_connection_controller.dart';

 class DashboardScreen extends StatelessWidget {
  const DashboardScreen({super.key});
@ -60,12 +63,30 @@ class DashboardScreen extends StatelessWidget {
  }
 }

-class _DashboardBody extends StatelessWidget {
+class _DashboardBody extends ConsumerWidget {
  const _DashboardBody();

  @override
-  Widget build(BuildContext context) {
+  Widget build(BuildContext context, WidgetRef ref) {
    final textTheme = Theme.of(context).textTheme;
+    final socketStatus = ref.watch(socketConnectionControllerProvider);
+
+    final String socketStatusText;
+    switch (socketStatus) {
+      case SocketConnectionState.disconnected:
+        socketStatusText = 'Disconnected';
+        break;
+      case SocketConnectionState.connecting:
+        socketStatusText = 'Connecting';
+        break;
+      case SocketConnectionState.connected:
+        socketStatusText = 'Connected';
+        break;
+      case SocketConnectionState.error:
+        socketStatusText = 'Error';
+        break;
+    }
+
    return SafeArea(
      child: ListView(
        padding: const EdgeInsets.all(24),
@ -78,9 +99,9 @@ class _DashboardBody extends StatelessWidget {
            icon: Icons.calendar_today_outlined,
          ),
          const SizedBox(height: 12),
-          const _StatusPanel(
+          _StatusPanel(
            title: 'Socket Contract',
-            value: 'Pending generation',
+            value: socketStatusText,
            icon: Icons.hub_outlined,
          ),
        ],
--- a/apps/client/lib/src/integrations/socket/alt_socket_client.dart
+++ b/apps/client/lib/src/integrations/socket/alt_socket_client.dart
@ -0,0 +1,41 @@
+import 'dart:async';
+import 'package:proto_socket/proto_socket.dart';
+
+import 'package:alt_client/src/contracts/alt_contracts.dart';
+import 'package:alt_client/src/generated/alt/v1/common.pb.dart';
+import 'socket_endpoint.dart';
+
+class AltSocketClient extends WsProtobufClient {
+  AltSocketClient(
+    dynamic ws, {
+    int heartbeatIntervalTime = 30,
+    int heartbeatWaitTime = 10,
+  }) : super(ws, heartbeatIntervalTime, heartbeatWaitTime, altParserMap());
+
+  static Future<AltSocketClient> connect(
+    AltSocketEndpoint endpoint, {
+    int heartbeatIntervalTime = 30,
+    int heartbeatWaitTime = 10,
+  }) async {
+    final ws = await WsProtobufClient.connect(
+      endpoint.host,
+      endpoint.port,
+      path: endpoint.path,
+    );
+    return AltSocketClient(
+      ws,
+      heartbeatIntervalTime: heartbeatIntervalTime,
+      heartbeatWaitTime: heartbeatWaitTime,
+    );
+  }
+
+  Future<HelloResponse> hello({Duration timeout = const Duration(seconds: 2)}) {
+    return sendRequest<HelloRequest, HelloResponse>(
+      HelloRequest()
+        ..clientName = 'alt-client'
+        ..clientVersion = 'dev'
+        ..altProtocolVersion = 'alt.v1',
+      timeout: timeout,
+    );
+  }
+}
--- a/apps/client/lib/src/integrations/socket/socket_connection_controller.dart
+++ b/apps/client/lib/src/integrations/socket/socket_connection_controller.dart
@ -0,0 +1,72 @@
+import 'dart:async';
+import 'package:meta/meta.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import 'alt_socket_client.dart';
+import 'socket_endpoint.dart';
+
+enum SocketConnectionState {
+  disconnected,
+  connecting,
+  connected,
+  error,
+}
+
+class SocketConnectionController extends Notifier<SocketConnectionState> {
+  AltSocketClient? _client;
+
+  @override
+  SocketConnectionState build() {
+    ref.onDispose(() {
+      _client?.close();
+    });
+    return SocketConnectionState.disconnected;
+  }
+
+  AltSocketClient? get client => _client;
+
+  Future<void> connect(AltSocketEndpoint endpoint) async {
+    if (state == SocketConnectionState.connecting ||
+        state == SocketConnectionState.connected) {
+      return;
+    }
+
+    state = SocketConnectionState.connecting;
+    try {
+      await _client?.close();
+      final newClient = await AltSocketClient.connect(endpoint);
+      _client = newClient;
+
+      // Perform handshake/hello
+      await newClient.hello();
+
+      state = SocketConnectionState.connected;
+
+      // Listen to disconnect events
+      newClient.addDisconnectListener((_) {
+        if (_client == newClient) {
+          state = SocketConnectionState.disconnected;
+        }
+      });
+    } catch (e) {
+      state = SocketConnectionState.error;
+      rethrow;
+    }
+  }
+
+  Future<void> disconnect() async {
+    state = SocketConnectionState.disconnected;
+    await _client?.close();
+    _client = null;
+  }
+
+  @visibleForTesting
+  set debugState(SocketConnectionState value) {
+    state = value;
+  }
+}
+
+final socketConnectionControllerProvider =
+    NotifierProvider<SocketConnectionController, SocketConnectionState>(
+  SocketConnectionController.new,
+);
--- a/apps/client/lib/src/integrations/socket/socket_endpoint.dart
+++ b/apps/client/lib/src/integrations/socket/socket_endpoint.dart
@ -0,0 +1,26 @@
+class AltSocketEndpoint {
+  final String host;
+  final int port;
+  final String path;
+
+  const AltSocketEndpoint({
+    this.host = '127.0.0.1',
+    this.port = 8080,
+    this.path = '/socket',
+  });
+
+  @override
+  bool operator ==(Object other) =>
+      identical(this, other) ||
+      other is AltSocketEndpoint &&
+          runtimeType == other.runtimeType &&
+          host == other.host &&
+          port == other.port &&
+          path == other.path;
+
+  @override
+  int get hashCode => host.hashCode ^ port.hashCode ^ path.hashCode;
+
+  @override
+  String toString() => 'ws://$host:$port$path';
+}
--- a/apps/client/pubspec.lock
+++ b/apps/client/pubspec.lock
@ -320,6 +320,13 @@ packages:
      url: "https://pub.dev"
    source: hosted
    version: "1.5.2"
+  proto_socket:
+    dependency: "direct main"
+    description:
+      path: "../../../proto-socket/dart"
+      relative: true
+    source: path
+    version: "1.0.5"
  protobuf:
    dependency: "direct main"
    description:
--- a/apps/client/pubspec.yaml
+++ b/apps/client/pubspec.yaml
@ -38,6 +38,8 @@ dependencies:
  go_router: ^17.2.3
  protobuf: ^6.0.0
  fixnum: ^1.1.1
+  proto_socket:
+    path: ../../../proto-socket/dart

 dev_dependencies:
  flutter_test:
--- a/apps/client/test/integrations/socket/alt_socket_client_test.dart
+++ b/apps/client/test/integrations/socket/alt_socket_client_test.dart
@ -0,0 +1,151 @@
+import 'dart:async';
+import 'dart:io';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:proto_socket/proto_socket.dart';
+
+import 'package:alt_client/src/generated/alt/v1/common.pb.dart';
+import 'package:alt_client/src/integrations/socket/alt_socket_client.dart';
+import 'package:alt_client/src/integrations/socket/socket_endpoint.dart';
+
+class FakeWebSocket extends Stream<dynamic> implements WebSocket {
+  final StreamController<dynamic> _controller = StreamController<dynamic>();
+  final List<List<int>> sentBytes = [];
+  bool isClosed = false;
+
+  @override
+  void add(dynamic data) {
+    if (data is List<int>) {
+      sentBytes.add(data);
+    }
+  }
+
+  @override
+  Future<void> close([int? code, String? reason]) async {
+    isClosed = true;
+    await _controller.close();
+  }
+
+  void feedFromServer(List<int> data) {
+    _controller.add(data);
+  }
+
+  @override
+  StreamSubscription<dynamic> listen(
+    void Function(dynamic event)? onData, {
+    Function? onError,
+    void Function()? onDone,
+    bool? cancelOnError,
+  }) {
+    return _controller.stream.listen(
+      onData,
+      onError: onError,
+      onDone: onDone,
+      cancelOnError: cancelOnError,
+    );
+  }
+
+  @override
+  dynamic noSuchMethod(Invocation invocation) => super.noSuchMethod(invocation);
+}
+
+void main() {
+  group('AltSocketEndpoint tests', () {
+    test('default constructor values', () {
+      const endpoint = AltSocketEndpoint();
+      expect(endpoint.host, equals('127.0.0.1'));
+      expect(endpoint.port, equals(8080));
+      expect(endpoint.path, equals('/socket'));
+      expect(endpoint.toString(), equals('ws://127.0.0.1:8080/socket'));
+    });
+
+    test('custom values', () {
+      const endpoint = AltSocketEndpoint(
+        host: 'api.example.com',
+        port: 443,
+        path: '/ws',
+      );
+      expect(endpoint.host, equals('api.example.com'));
+      expect(endpoint.port, equals(443));
+      expect(endpoint.path, equals('/ws'));
+      expect(endpoint.toString(), equals('ws://api.example.com:443/ws'));
+    });
+
+    test('equality and hashCode', () {
+      const e1 = AltSocketEndpoint(host: '1.2.3.4', port: 9000, path: '/a');
+      const e2 = AltSocketEndpoint(host: '1.2.3.4', port: 9000, path: '/a');
+      const e3 = AltSocketEndpoint(host: '1.2.3.4', port: 9000, path: '/b');
+
+      expect(e1, equals(e2));
+      expect(e1.hashCode, equals(e2.hashCode));
+      expect(e1, isNot(equals(e3)));
+    });
+  });
+
+  group('AltSocketClient tests', () {
+    late FakeWebSocket fakeWs;
+    late AltSocketClient client;
+
+    setUp(() {
+      fakeWs = FakeWebSocket();
+      client = AltSocketClient(
+        fakeWs,
+        heartbeatIntervalTime: 1,
+        heartbeatWaitTime: 1,
+      );
+    });
+
+    tearDown(() async {
+      await client.close();
+    });
+
+    test('client initialization and parser registration', () {
+      expect(client.isAlive, isTrue);
+
+      final helloRequestType =
+          HelloRequest.getDefault().info_.qualifiedMessageName;
+      final helloResponseType =
+          HelloResponse.getDefault().info_.qualifiedMessageName;
+
+      expect(client.getGenerator<HelloRequest>(helloRequestType), isNotNull);
+      expect(client.getGenerator<HelloResponse>(helloResponseType), isNotNull);
+    });
+
+    test('hello handshake request-response loop', () async {
+      final helloFuture = client.hello(timeout: const Duration(seconds: 1));
+
+      await Future<void>.delayed(Duration.zero);
+
+      expect(fakeWs.sentBytes, isNotEmpty);
+      final firstSentPacketBytes = fakeWs.sentBytes.first;
+      final sentPacket = PacketBase.fromBuffer(firstSentPacketBytes);
+
+      final helloRequestType =
+          HelloRequest.getDefault().info_.qualifiedMessageName;
+      expect(sentPacket.typeName, equals(helloRequestType));
+
+      final sentHelloRequest = HelloRequest.fromBuffer(sentPacket.data);
+      expect(sentHelloRequest.clientName, equals('alt-client'));
+      expect(sentHelloRequest.clientVersion, equals('dev'));
+      expect(sentHelloRequest.altProtocolVersion, equals('alt.v1'));
+
+      final expectedResponse = HelloResponse()
+        ..serverName = 'alt-server'
+        ..serverVersion = '1.0.0'
+        ..altProtocolVersion = 'alt.v1';
+
+      final responsePacket = PacketBase()
+        ..typeName = HelloResponse.getDefault().info_.qualifiedMessageName
+        ..nonce = 100
+        ..responseNonce = sentPacket.nonce
+        ..data = expectedResponse.writeToBuffer();
+
+      fakeWs.feedFromServer(responsePacket.writeToBuffer());
+
+      final response = await helloFuture;
+
+      expect(response.serverName, equals('alt-server'));
+      expect(response.serverVersion, equals('1.0.0'));
+      expect(response.altProtocolVersion, equals('alt.v1'));
+    });
+  });
+}
--- a/apps/client/test/widget_test.dart
+++ b/apps/client/test/widget_test.dart
@ -1,13 +1,74 @@
 import 'package:alt_client/src/app/app.dart';
+import 'package:alt_client/src/integrations/socket/socket_connection_controller.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';

+class FakeSocketConnectionController extends SocketConnectionController {
+  final SocketConnectionState initialState;
+
+  FakeSocketConnectionController(this.initialState);
+
+  @override
+  SocketConnectionState build() {
+    return initialState;
+  }
+}
+
 void main() {
-  testWidgets('shows ALT dashboard shell', (tester) async {
+  testWidgets('shows ALT dashboard shell with default disconnected socket state', (tester) async {
    await tester.pumpWidget(const ProviderScope(child: AltClientApp()));

    expect(find.text('ALT'), findsOneWidget);
    expect(find.text('Backtests'), findsWidgets);
    expect(find.text('Korea Daily Pipeline'), findsOneWidget);
+    expect(find.text('Disconnected'), findsOneWidget);
+  });
+
+  testWidgets('shows ALT dashboard with socket state Connecting', (tester) async {
+    await tester.pumpWidget(
+      ProviderScope(
+        overrides: [
+          socketConnectionControllerProvider.overrideWith(
+            () => FakeSocketConnectionController(SocketConnectionState.connecting),
+          ),
+        ],
+        child: const AltClientApp(),
+      ),
+    );
+
+    expect(find.text('Socket Contract'), findsOneWidget);
+    expect(find.text('Connecting'), findsOneWidget);
+  });
+
+  testWidgets('shows ALT dashboard with socket state Connected', (tester) async {
+    await tester.pumpWidget(
+      ProviderScope(
+        overrides: [
+          socketConnectionControllerProvider.overrideWith(
+            () => FakeSocketConnectionController(SocketConnectionState.connected),
+          ),
+        ],
+        child: const AltClientApp(),
+      ),
+    );
+
+    expect(find.text('Socket Contract'), findsOneWidget);
+    expect(find.text('Connected'), findsOneWidget);
+  });
+
+  testWidgets('shows ALT dashboard with socket state Error', (tester) async {
+    await tester.pumpWidget(
+      ProviderScope(
+        overrides: [
+          socketConnectionControllerProvider.overrideWith(
+            () => FakeSocketConnectionController(SocketConnectionState.error),
+          ),
+        ],
+        child: const AltClientApp(),
+      ),
+    );
+
+    expect(find.text('Socket Contract'), findsOneWidget);
+    expect(find.text('Error'), findsOneWidget);
  });
 }