<!-- task=m-operator-client-api-core-integration/04+02,03_backtest_error plan=0 tag=API -->

# Plan - Backtest Repository And Error Core

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

구현 후 active `CODE_REVIEW-*-G??.md`의 구현 소유 섹션을 모두 채운다. 검증 stdout/stderr 없이 완료를 주장하지 않는다. code-review 전용 archive와 roadmap 갱신은 수행하지 않는다.

## 배경

Milestone의 backtest list/detail/result/start와 typed error mapping은 가장 넓은 client core surface다. socket state와 market repository가 정리된 뒤 같은 result/error 모델로 backtest repository를 만들면 Flutter MVP가 화면 없이 의존할 API readiness evidence를 얻는다.

## 사용자 리뷰 요청 흐름

구현 중 사용자 결정이나 외부 환경 prerequisite이 필요하면 review stub의 `사용자 리뷰 요청`에 기록하고 멈춘다. evidence gap만으로는 사용자 리뷰 요청을 만들지 않는다.

## Roadmap Targets

- Milestone: `agent-roadmap/phase/operator-surface/milestones/operator-client-api-core-integration.md`
- Task ids:
  - `backtest-call`: backtest list/detail/result/start 기본 API 호출을 client core에서 수행할 수 있다.
  - `error-core`: unavailable/error/disconnected 상태가 UI copy가 아닌 안정적인 client state로 남는다.
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- `agent-test/local/rules.md`
- `agent-test/local/client-smoke.md`
- `agent-ops/rules/project/domain/client/rules.md`
- `apps/client/lib/src/integrations/socket/alt_socket_client.dart`
- `apps/client/test/integrations/socket/alt_socket_client_test.dart`
- `apps/client/lib/src/contracts/alt_contracts.dart`
- `packages/contracts/proto/alt/v1/backtest.proto`
- `packages/contracts/proto/alt/v1/common.proto`
- `apps/client/pubspec.yaml`

### 테스트 환경 규칙

`test_env=local`; client-smoke 적용. 기본 검증은 `cd apps/client && flutter test`. 이 plan은 broad client API/repository surface라 focused test와 전체 Flutter test를 모두 요구한다.

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

low-level socket wrapper tests는 list/detail/result/start success path 일부를 확인한다. repository-level typed error, transport failure, unavailable/disconnected result mapping은 없다.

### 심볼 참조

renamed/removed symbol: none.

### 분할 판단

dependent split plan이다. directory `04+02,03_backtest_error`는 predecessor `02_socket_state`와 `03_market_repository` PASS `complete.log`를 요구한다. `02`는 transport state, `03`은 repository pattern을 제공하므로 둘 다 필요하다.

### 범위 결정 근거

backtest client repository와 error mapping만 다룬다. compare backtests, chart view model, Flutter screen, API server/worker 변경은 제외한다.

### 빌드 등급

build=`cloud-G07`, review=`cloud-G07`. 여러 predecessors, broad API surface, typed error semantics가 결합되어 상위 등급이 필요하다.

## 의존 관계 및 구현 순서

구현 시작 전 같은 task group에서 predecessor `02+01_socket_state`와 `03+01_market_repository`의 active 또는 archived `complete.log`를 확인한다. 두 complete 경로를 review에 기록한다.

## 구현 체크리스트

- [ ] backtest repository/provider boundary를 추가하고 list/detail/result/start를 `AltApiResult`로 반환한다. 검증: `cd apps/client && flutter test test/features/backtest/backtest_repository_test.dart`
- [ ] fake client로 request payload, success result, typed `ErrorInfo` mapping을 확인한다.
- [ ] transport failure/disconnected/unavailable 상태가 UI copy 없는 stable error로 남는지 확인한다.
- [ ] `cd apps/client && flutter test`를 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [API-1] Backtest repository 추가

#### 문제

`apps/client/lib/src/integrations/socket/alt_socket_client.dart:44`부터 `:93`까지 raw protobuf wrappers만 있고 repository boundary와 typed error result가 없다.

```dart
// apps/client/lib/src/integrations/socket/alt_socket_client.dart:44
Future<ListBacktestRunsResponse> listBacktestRuns(
```

#### 해결 방법

`apps/client/lib/src/features/backtest/data/backtest_repository.dart`를 추가한다. list/detail/result/start method는 request builder 입력을 받아 `AltApiResult<...Response>`로 반환한다. response에 `ErrorInfo`가 있으면 `AltApiError`, thrown transport failure는 transport result로 바꾼다.

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

- [ ] `apps/client/lib/src/features/backtest/data/backtest_repository.dart`
- [ ] `apps/client/test/features/backtest/backtest_repository_test.dart`

#### 테스트 작성

작성한다. list/detail/result/start 각각 success request payload와 typed error mapping을 확인한다. disconnected/transport failure는 fake client throwing path로 확인한다.

#### 중간 검증

`cd apps/client && flutter test test/features/backtest/backtest_repository_test.dart` exit code 0.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `apps/client/lib/src/features/backtest/data/backtest_repository.dart` | API-1 |
| `apps/client/test/features/backtest/backtest_repository_test.dart` | API-1 |

## 최종 검증

```bash
cd apps/client && flutter test
```

기대 결과: exit code 0. 실제 API socket integration smoke는 predecessor handoff와 후속 runtime evidence로 남기고, 이 plan은 fake client repository test로 제한한다.

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