# req-105: trex-core sync 명령 — 슬롯 수량을 브로커에 맞춰 갱신 + warning 해제

- Status: Implemented
- Type: Interface
- Priority: High
- Owner: trex-core-dev

## Intent
- 운영자가 `trex-core sync` 명령으로 **브로커 잔고(정본)를 기준으로 대상 슬롯의 보유 수량을 갱신**(INACTIVE→HOLDING 전이 포함)하고, 갱신 후 브로커와 일치하면 해당 슬롯의 reconcile-warning을 자동 해제한다.
- cold-start 시 실계좌에 이미 보유 중인 종목(B 케이스)의 슬롯 onboarding 경로이기도 하다.
- dcy-034 FR-3, OQ-2/OQ-3 확정 반영: **브로커 잔고 정본 유지, 슬롯 qty ← 브로커**. 브로커에만 있고 portfolio-hub에 없는 종목(슬롯 부재)은 sync 대상 아님(자동 슬롯 생성 금지).
- portfolio-hub WAC(보유 평단) read 엔드포인트(FR-7, portfolio-hub **dcy-008 / REQ-043** `GET /v1/portfolios/{id}/holdings/cost-basis`) 가용 시 슬롯 avg_price를 seed한다. 포트 미가용 또는 조회 실패 시 수량만 갱신하고 WARN 로그를 남긴다(graceful degrade).
- **INACTIVE→HOLDING 전이 엣지 추가 승인(OQ-A)**: `ALLOWED_TRANSITIONS`에 `(INACTIVE, HOLDING)` 전이를 추가한다. 이 전이는 **actor=sync 또는 reconcile/reconcile_sync로 제한**되며, 일반 전략 경로(INACTIVE→PENDING_BUY→HOLDING)는 유지된다. transition_log reason은 `onboarding` 또는 `reconcile_sync`류로 식별 가능하게 기록한다. **wire 계약 무영향**: SlotState enum 상태값 5개(INACTIVE/PENDING_BUY/HOLDING/PENDING_SELL/ERROR) 불변, 전이 엣지만 추가이므로 slots RPC 스키마·상태값 변화 없음.

## Requirement
- 시스템은 `trex-core sync [--portfolio-id <pid> | --all]` 서브커맨드를 제공해야 한다.
- sync는 portfolio-hub 유니버스에 있어 슬롯이 생성된 종목만 대상으로 한다. 브로커에만 있고 슬롯이 없는 종목은 sync가 건드리지 않고 unmanaged 경고를 로그에 남긴다(자동 슬롯 생성 금지).
- sync 실행 시 대상 슬롯마다 브로커 잔고(`BrokerPort.get_balance()`)를 조회하여 슬롯 qty를 브로커 수량으로 갱신해야 한다. 브로커 수량 > 0이고 슬롯이 INACTIVE이면 **INACTIVE→HOLDING 전이(actor=sync, reason=onboarding/reconcile_sync)**를 수행해야 한다. 이 전이는 OQ-A 승인으로 `ALLOWED_TRANSITIONS`에 추가되는 새 엣지를 사용하며 일반 전략 진입 경로와 구분된다.
- portfolio-hub WAC read 포트(FR-7: **portfolio-hub dcy-008 / REQ-043**, `GET /v1/portfolios/{id}/holdings/cost-basis`)가 연결되어 있으면, sync 시 보유 평단(WAC)을 읽어 슬롯 avg_price에 seed해야 한다. 포트가 없거나 조회 실패 시 avg_price seed를 건너뛰고 WARN 로그를 남긴다(graceful degrade).
- sync 후 슬롯 qty == 브로커 수량이면 `ReconcileWarningStore.clear_warned(slot_id)`로 reconcile-warning을 해제해야 한다.
- sync 실행 전 before 상태, 실행 후 after 상태(슬롯 qty, 브로커 qty, warning 해제 여부)를 출력해야 한다.
- sync는 confirmation 프롬프트(`--yes` 스킵 가능)와 `--dry-run` 모드를 지원해야 한다. live 계좌에서는 `--yes --live` 이중 확인을 요구해야 한다.
- sync는 직접-DB 경로(pause/resume 방식)로 구현하며, 데몬 RPC를 거치지 않는다.

## Acceptance Criteria
1. Given cold-start 상태(슬롯 INACTIVE, 브로커 보유 qty > 0)에서 `trex-core sync --portfolio-id <pid>` 실행 시, When sync가 완료되면, Then 슬롯 qty = 브로커 qty이고 슬롯 상태가 HOLDING으로 전이되며 reconcile-warning이 해제된다(S-2, OQ-A 승인 전이).
2. Given 슬롯 qty ≠ 브로커 qty인 B 케이스에서 sync 실행 시, When sync가 완료되면, Then 슬롯 qty = 브로커 qty로 갱신되고 reconcile-warning이 해제된다.
3. Given 브로커에만 있고 슬롯이 없는 종목(슬롯 부재)에서 sync 실행 시, When sync가 실행되면, Then 슬롯이 자동 생성되지 않고 unmanaged 경고가 로그에 남는다.
4. Given portfolio-hub WAC read 포트(portfolio-hub dcy-008 / REQ-043 `GET /v1/portfolios/{id}/holdings/cost-basis`)가 연결되어 있을 때, When sync를 실행하면, Then 슬롯 avg_price에 WAC 값이 seed된다.
5. Given portfolio-hub WAC read 포트가 없거나 조회 실패 시, When sync를 실행하면, Then avg_price seed 없이 수량 갱신만 수행하고 WARN 로그를 남긴다(graceful degrade).
6. Given `--dry-run` 플래그로 sync 실행 시, When 명령이 실행되면, Then 슬롯 qty 변경 없이 before/after 예상치만 출력된다.
7. Given live 계좌에서 `--yes` 없이 sync 실행 시, When 명령이 실행되면, Then 오류 메시지와 함께 실행을 거부한다(live double-ack 게이트).
8. Given sync 실행 후 슬롯 qty가 여전히 브로커 수량과 다를 경우(갱신 실패 등), When sync가 완료되면, Then reconcile-warning이 해제되지 않는다.
9. Given `--all` 플래그로 sync 실행 시, When 명령이 실행되면, Then 인스턴스의 모든 B-warned 슬롯에 대해 sync가 실행된다.
10. Given INACTIVE→HOLDING 전이 시, When transition_log 또는 로그를 확인하면, Then actor 및 reason 필드에 sync/onboarding(또는 reconcile_sync)이 기록되어 일반 전략 진입 경로(INACTIVE→PENDING_BUY)와 구분된다(OQ-A actor 식별).

## Impacted Area
- Docs: `docs/operations.md` (cold-start onboarding 절차 신설), `docs/runtime-flows.md` (sync 흐름 추가)
- Modules:
  - `trex_core/runtime/cli.py` (`sync` 서브커맨드 추가, `_build_parser`, `_cmd_sync`)
  - `trex_core/application/reconciliation.py` (sync 로직 또는 별도 `sync_slot_to_broker` 함수 — batch design에서 결정)
  - `trex_core/application/ports.py` 또는 `application/portfolio.py` (WAC read 포트 의존 명시)
  - `trex_core/adapters/portfolio/` (WAC read 어댑터 — portfolio-hub FR-7 REQ 선행 의존)
- Tests:
  - `tests/application/test_sync.py` 또는 `tests/integration/test_sync.py` (cold-start onboarding, warning 해제, unmanaged 슬롯 처리, dry-run, WAC seed 유무)
  - `tests/runtime/test_cli.py` (sync 서브커맨드 인수 파싱, 확인 프롬프트, live double-ack)

## Notes
- **FR-7 의존 구체화(OQ-A 팀장 결정)**: portfolio-hub WAC read 엔드포인트는 **portfolio-hub dcy-008 / REQ-043**, `GET /v1/portfolios/{id}/holdings/cost-basis`. 2026-06-25 confirm-discovery 완료. 가용 시 avg_price seed, 미가용/실패 시 수량만 갱신 + WARN(graceful degrade). 구현 시 portfolio-hub REQ-043 완료 여부 확인 필요.
- **INACTIVE→HOLDING 전이 엣지 추가(OQ-A 팀장 승인)**: `state.py:ALLOWED_TRANSITIONS`에 `(INACTIVE, HOLDING)` 엣지 추가가 승인되었다. 이 전이는 **actor=sync 또는 reconcile로 제한**되며 일반 전략 경로(INACTIVE→PENDING_BUY→HOLDING)는 유지된다. transition_log reason은 `onboarding` 또는 `reconcile_sync`류로 식별. **wire 무영향**: SlotState enum 5개(inactive/pending_buy/holding/pending_sell/error) 불변, 엣지만 추가이므로 slots RPC 스키마·상태값 변화 없음. batch design에서 `_BASE_TRANSITIONS` 확장 또는 별도 `_SYNC_TRANSITIONS` 집합 구성을 결정한다.
- sync 대상 슬롯 결정 방법(portfolio_id 명시 vs all warned 슬롯 vs all INACTIVE 슬롯)은 batch design에서 구체화.
- dcy-034 FR-3, OQ-2/3, OQ-A(팀장 2026-06-25 confirm), R-1 대응.

## Change Log

### CHG-20260626-01
- Date: 2026-06-26
- Author: trex-core-dev
- Status: Approved → Implemented
- Summary: BAT-051(PR #32, 07b393d) origin/main 머지 완료. QC(opus) PASS + 팀장 confirm-batch-verification. sync CLI(--portfolio-id/--all/--dry-run/--live), INACTIVE→HOLDING 전이, WAC seed, warning 해제, 전 AC 검증 완료.

#### Acceptance Criteria Delta
- 없음

#### Impacted Area Delta
- 없음

#### Delivery Trace Delta
- Batches: BAT-051 (core-B)
- Releases: M3 (배포 대기)

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: Implemented
- Follow-up Action: M3 배포 시 cold-start 운영 검증.

#### Validation Plan
- BAT-051 verification.md AC 매핑 전항목 PASS 확인됨.

### CHG-20260625-02
- Date: 2026-06-25
- Author: trex-core-dev

#### Change Summary
- REQ-105 **Proposed → Approved** (confirm-req, 팀장 2026-06-25).
- OQ-A 결정 반영: INACTIVE→HOLDING 전이 엣지 추가 승인(actor=sync/reconcile 제한, wire 무영향 명시).
- FR-7 의존 구체화: portfolio-hub dcy-008 / REQ-043 (`GET /v1/portfolios/{id}/holdings/cost-basis`) 로 참조 갱신.
- AC-10 신규 추가(전이 actor 식별).

#### Intent
- 팀장 confirm-req 결정(OQ-A 승인 + FR-7 참조 구체화)을 REQ에 반영.

#### Acceptance Criteria Delta
- Added: AC-10 신규(INACTIVE→HOLDING 전이 actor/reason 식별).
- Updated: AC-1(OQ-A 전이 명시), AC-4(FR-7 참조 구체화), AC-5(graceful degrade 명시).
- Removed: 없음.

#### Impacted Area Delta
- Notes: FR-7 참조 및 전이 엣지 추가 내용 구체화.
- Modules: `trex_core/domain/slot/state.py` — `ALLOWED_TRANSITIONS`에 `(INACTIVE, HOLDING)` 엣지 추가 필요(batch implementation 단계).
- Tests: AC-10 actor 식별 테스트 신규.

#### Delivery Trace Delta
- Batches: 미정 (suggest-batch-reqs 이후)
- Releases: 미정

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: Approved
- Follow-up Action: batch design에서 state.py 전이 집합 확장 방식 결정 및 actor 제한 구현 방안 확정.

#### Validation Plan
- cold-start onboarding 시나리오 테스트 pass / INACTIVE→HOLDING 전이 actor 식별 테스트 pass / warning 해제 확인 / unmanaged 슬롯 자동 생성 없음 테스트 pass / FR-7 graceful degrade 테스트 pass.

### CHG-20260625-01
- Date: 2026-06-25
- Author: trex-core-dev

#### Change Summary
- REQ-105 신규 생성 (Proposed) — dcy-034 FR-3 대응, draft-req 단계.

#### Intent
- cold-start 시 운영자가 안전하게 슬롯을 브로커에 맞춰 onboarding하는 표준 CLI 경로 신설.

#### Acceptance Criteria Delta
- Added: AC-1~9 전부 신규.
- Updated: 없음.
- Removed: 없음.

#### Impacted Area Delta
- Docs: operations.md 신설, runtime-flows.md 갱신.
- Modules: cli.py, reconciliation.py.
- Tests: sync 통합 테스트 신규.

#### Delivery Trace Delta
- Batches: 미정
- Releases: 미정

#### Revalidation Impact
- Reverification Needed: no (신규 REQ)
- Existing Implementation Invalidated: no
- Status Recommendation: keep-current
- Follow-up Action: INACTIVE→HOLDING 전이표 추가 여부 팀장 확인 후 batch design 진행.

#### Validation Plan
- cold-start onboarding 시나리오 테스트 pass / warning 해제 확인 / unmanaged 슬롯 자동 생성 없음 테스트 pass.