<!-- task=m-paper-trading-command-workflow/03+02_order_lifecycle plan=0 tag=PAPER_ORDER -->

# Plan - PAPER_ORDER

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

`CODE_REVIEW-cloud-G09.md`를 실제 구현과 검증 출력으로 채운다. `02+01_risk_command`의 `complete.log`가 없으면 구현하지 않는다. 사용자에게 직접 질문하지 말고 필요한 결정은 review stub `사용자 리뷰 요청`에 남긴다.

## 배경

현재 paper trading은 strategy run에서 생성된 pending order를 daily bar로 체결한다. 마일스톤의 order lifecycle command는 operator가 virtual order submit/cancel/fill simulation을 command/YAML로 검증할 수 있게 만드는 큰 작업이다. 이는 새 contract/API/worker/CLI surface를 포함한다.

## 사용자 리뷰 요청 흐름

구현 중 범위가 submit/cancel/fill 중 하나로 줄어야 하거나 사용자 결정이 필요하면 review stub에 근거를 기록하고 중단한다. code-review가 사용자 리뷰 전환을 판단한다.

## Roadmap Targets

- Milestone: `agent-roadmap/phase/trading-expansion/milestones/paper-trading-command-workflow.md`
- Task ids:
  - `paper-order-command`: virtual order lifecycle command
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- `agent-roadmap/phase/trading-expansion/milestones/paper-trading-command-workflow.md`
- `agent-test/local/rules.md`
- `agent-test/local/contracts-smoke.md`
- `agent-test/local/api-smoke.md`
- `agent-test/local/worker-smoke.md`
- `agent-test/local/operations-smoke.md`
- `packages/contracts/proto/alt/v1/paper_trading.proto`
- `packages/domain/backtest/types.go`
- `services/worker/internal/papertrading/engine.go`
- `services/worker/internal/papertrading/service.go`
- `services/worker/internal/socket/paper.go`
- `services/worker/internal/socket/paper_mapping.go`
- `services/api/internal/socket/paper.go`
- `services/api/internal/workerclient/client.go`
- `apps/cli/internal/operator/client.go`
- `apps/cli/internal/operator/runner.go`
- `apps/cli/internal/operator/scenario.go`
- `apps/cli/internal/operator/runner_paper_test.go`
- `apps/cli/go.mod`
- `services/api/go.mod`
- `services/worker/go.mod`
- `packages/domain/go.mod`

### 테스트 환경 규칙

`test_env=local`. contracts/API/worker/operations smoke 적용. New protobuf messages require `bin/contracts-gen`, `bin/contracts-check`, generated Go tests, API/worker parser registration tests, CLI parser tests, focused module tests, and final `bin/test`.

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

- `OrderIntent`, fill, and risk domain unit tests exist.
- No operator-facing order id/status lifecycle contract exists.
- No worker service state stores submitted/canceled virtual orders outside strategy-generated pending orders.
- No CLI action for submit/cancel/order status exists.

### 심볼 참조

rename/remove 없음. `rg --sort path "OrderIntent|StartPaperTrading|GetPaperTradingState"` shows domain order types are internal and paper runtime surface currently only start/state.

### 분할 판단

This is `03+02_order_lifecycle`; predecessor `02+01_risk_command` must complete first. Missing predecessor `complete.log` is expected at planning time and must be checked before implementation.

### 범위 결정 근거

Implement paper-only virtual order lifecycle. Exclude real broker submission, broker balance sync, high-frequency execution, and production auto execution. Persistence may stay in-memory unless tests prove a durable store is needed; do not add database migrations without explicit review note.

### 빌드 등급

`cloud-G09`: broad additive contract/API/worker/CLI lifecycle surface with ordering/status semantics and high blast radius.

## 구현 체크리스트

- [ ] [PAPER_ORDER-1] protobuf contract에 paper order command/query messages를 additive하게 추가하고 parser maps/client methods를 갱신한다.
- [ ] [PAPER_ORDER-2] worker paper service가 virtual order submit/cancel/fill simulation state를 in-memory로 관리하고 typed status를 반환한다.
- [ ] [PAPER_ORDER-3] API pass-through와 CLI scenario action이 order id, status transition, fill summary를 출력한다. 검증: `bin/contracts-check`, `go test ./services/worker/...`, `go test ./services/api/...`, `go test ./apps/cli/internal/operator`, `bin/test` 통과.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## PAPER_ORDER-1

### 문제

`paper_trading.proto:16` only has start/state requests. No submit/cancel/order status messages exist.

### 해결 방법

Add paper order messages with order id, account id, instrument, side, quantity, type, optional limit price, status, fill summary. Update generated contracts and parser maps in CLI/API/worker/client.

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

- [ ] `packages/contracts/proto/alt/v1/paper_trading.proto`
- [ ] generated Go/Dart outputs via `bin/contracts-gen`
- [ ] `apps/cli/internal/operator/parser_map.go`
- [ ] `services/api/internal/contracts/parser_map.go`
- [ ] `services/worker/internal/contracts/parser_map.go`

### 테스트 작성

Parser map tests must include new messages.

### 중간 검증

`bin/contracts-check`

## PAPER_ORDER-2

### 문제

`services/worker/internal/papertrading/service.go:47` stores terminal state only, not operator-submitted orders.

### 해결 방법

Add in-memory paper order registry keyed by account/order id. Submit creates order status, cancel transitions pending order, fill simulation applies existing fill/risk helpers against account state and records fill summary.

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

- [ ] `services/worker/internal/papertrading/service.go`
- [ ] `services/worker/internal/socket/paper.go`
- [ ] `services/worker/internal/socket/paper_mapping.go`
- [ ] `services/worker/internal/socket/paper_test.go`
- [ ] `services/worker/internal/papertrading/service_test.go`

### 테스트 작성

Service tests for submit, cancel, fill, invalid account/order id, insufficient cash/position.

### 중간 검증

`go test ./services/worker/...`

## PAPER_ORDER-3

### 문제

`apps/cli/internal/operator/scenario.go:44` only supports start/get state paper actions.

### 해결 방법

Add scenario actions for submit/cancel/fill simulation or a single order lifecycle action if simpler. CLI output must include `order_id`, `order_status`, `fill_count` or `fill_summary`.

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

- [ ] `services/api/internal/workerclient/client.go`
- [ ] `services/api/internal/socket/paper.go`
- [ ] `services/api/internal/socket/paper_test.go`
- [ ] `apps/cli/internal/operator/client.go`
- [ ] `apps/cli/internal/operator/scenario.go`
- [ ] `apps/cli/internal/operator/runner.go`
- [ ] `apps/cli/internal/operator/output.go`
- [ ] `apps/cli/internal/operator/runner_paper_test.go`
- [ ] `apps/cli/testdata/operator/*`

### 테스트 작성

Fake API CLI lifecycle test and YAML fixture validation.

### 중간 검증

`go test ./services/api/... && go test ./apps/cli/internal/operator`

## 의존 관계 및 구현 순서

This directory is `03+02_order_lifecycle`; only predecessor `02+01_risk_command` is encoded in the path. Do not start until the predecessor has `complete.log`.

## 수정 파일 요약

| 파일 | 항목 |
|---|---|
| `packages/contracts/proto/alt/v1/paper_trading.proto` | PAPER_ORDER-1 |
| parser maps and generated outputs | PAPER_ORDER-1 |
| `services/worker/internal/papertrading/service.go` | PAPER_ORDER-2 |
| `services/worker/internal/socket/paper*.go` | PAPER_ORDER-2 |
| `services/api/internal/workerclient/client.go` | PAPER_ORDER-3 |
| `services/api/internal/socket/paper.go` | PAPER_ORDER-3 |
| `apps/cli/internal/operator/*` | PAPER_ORDER-3 |
| `apps/cli/testdata/operator/*` | PAPER_ORDER-3 |

## 최종 검증

```bash
bin/contracts-check
go test ./services/worker/...
go test ./services/api/...
go test ./apps/cli/internal/operator
bin/test
```

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