feat: Phase 1 final create POST 활성화 (디폴트 OFF 가드 유지)

[pghoya2956]

Summary

place-order 의 daemon.py 봉인을 풀어 토스 broker create POST 호출이 가능해진다. live 활성화는 TOSS_BRIDGE_ENABLE_FINAL_SUBMIT=1 명시 enable 시에만 — 디폴트 OFF 영구 유지 (semver minor: 0.2.0).

financier-v2 의 Phase 1 task plan P1-01 ~ P1-06 의 결과물.

Phase 0 P0-02 discovery 요약

토스 정식 web 앱에서 supervised HAR capture 2건으로 final create endpoint 확정:

• URL: `POST https://wts-cert-api.tossinvest.com/api/v2/wts/trading/order/create\`
• body schema: prepare body − `withOrderKey` (12 필드)
• orderKey 흐름: cookie/session 기반 (body 미포함)
• broker_ack 매핑: `orderId, orderDate, orderNo, message, isReserved`
• 결정적 발견: 토스 미국주식 "시장가" UI = client-level 추상화. API 는 `orderPriceType="00"` 단일 → spec 가정 일부 무효 (Phase 2 P2-02 영향)

변경 내역

P1-01 — `daemon.py:_run_prepare_preflight` 봉인 제거 + broker create skeleton (05c15e7)

`prepare preflight succeeded; final create remains blocked` 봉인 raise 제거. dict return 9필드 확장 (account_no, prepare_payload 등) → `place_order` 호출자에 `_final_submit_enabled` 가드 분기 추가:

• OFF (디폴트): 기존 동작 유지 — submit_blocked + capability_not_ready raise + journal append. 메시지만 `final submit is disabled ({guard_reason})` 로 정정 + `broker_ack.guard_reason` 필드
• ON: `_run_broker_create(normalized, preflight)` 호출 → broker_ack 분기 → `submit_state="submitted"|"broker_rejected"` + journal append + 정상 dict return

`_run_broker_create` skeleton 신규 (92줄).

P1-02 — reject taxonomy enum + 분기 정밀화 (4bfe3fe)

• enum 9개 + `BROKER_ACK_REJECT_CODES` frozenset
• `classify_broker_reject(message, status_code, error)` 함수 — error → TIMEOUT, 408/504 → TIMEOUT, 401/403 → AUTH_REQUIRED, ≥500 → HTTP_ERROR, fallback UNKNOWN
• `_run_broker_create` timeout (`RuntimeError`) try/except 추가 + `status_code` 필드명 bug fix (P1-01 의 `status` 오타)
• 한글 message → 의미 enum 매핑은 P0-03 backlog (Phase 6 supervised 자연 capture 후 점진 추가)

P1-03 — `BROKER_ACK_ALLOWED_FIELDS` whitelist 갱신 (47d0314)

9필드 → 15필드. 신규: `broker_order_id, order_no, order_date, is_reserved, http_status, guard_reason`. sanitize 보존 검증 단위 테스트 2건 추가 (P0-02 SCHD capture 데이터 그대로).

P1-04 — auto-verify aggregator hook + `--auto-verify` CLI flag (17a95a3)

`place_order` submit success 직후 `auto_verify=True` 일 때 `runtime.verify_order` 1회 호출 → response.data 에 verification_state + verify_snapshot 합침. verify 실패 시 `auto_verify_error` 만 추가하고 ok=True 유지 (submit boundary 보존).

디폴트 OFF — financier-v2 SKILL 측 60s 폴링과 중복 회피.

P1-05 — 단위 테스트 5건 (cc3a709)

`_fetch_many` mock 으로 P0-02 capture 응답 시뮬레이션:

• `classify_broker_reject` 7개 status_code 분기 enum 매핑
• `place_order` success path: orderId 존재 시 broker_ack 6필드 보존 (V56qyv7r/orderNo=3/2026-05-04)
• missing orderId → BROKER_REJECTED_UNKNOWN
• RuntimeError timeout → BROKER_REJECTED_TIMEOUT + http_status=0
• auto_verify=True + submitted → verify_snapshot 합쳐짐

P1-06 — `health` 응답 `bridge_version` 필드 추가 (0353d38)

`importlib.metadata.version("toss-browser-bridge")` 로 패키지 메타데이터에서 version 추출 → `BRIDGE_VERSION` 모듈 상수 캐시 → `health()` 응답 top-level 노출. financier-v2 wrapper(P4-06) startup minimum pin 검증의 baseline.

3중 동기 검증 단위 테스트 1건 추가.

chore — version 0.1.0 → 0.2.0 (b1e2e42)

semver minor — 신규 가드된 write 기능.

정책 박제

• `TOSS_BRIDGE_ENABLE_FINAL_SUBMIT` 디폴트 OFF 영구 유지 — supervised live validation 통과 후에도 디폴트 ON 전환 안 함. 매 사용자 세션마다 명시 enable 필요
• `PYTEST_CURRENT_TEST` 환경에서 추가 가드 — `TOSS_BRIDGE_ALLOW_TEST_FINAL_SUBMIT=1` 도 함께 set 해야 봉인 우회. 단위 테스트 fixture 외에는 활성화 차단
• live e2e 봉인 유지 — `tests/test_live_e2e.py` 의 final submit 테스트는 그대로 skipped/봉인 유지. supervised P6 단계까지

RQ-01 idempotency 결정

broker create 의 idempotency 보장 여부는 토스 측에서 미문서. 본 PR 에서는 재시도 X (보수적) 채택:

• `_fetch_many` RuntimeError timeout → 즉시 `BROKER_REJECTED_TIMEOUT` 반환, 자동 재시도 안 함
• 동일 `mutation_id` 재발행은 wrapper / SKILL 레이어에서 차단

Phase 6 P6-05 supervised 단계에서 1회 재시도 실측으로 룰 보강 예정.

단위 테스트 결과

• `test_submit_runtime.py`: 17 PASS (12 → 17, 5건 신규)
• `test_submit_contract.py`: 11 PASS (9 → 11, 2건 신규)
• `test_packaging_metadata.py`: 3 PASS (2 → 3, 1건 신규)
• 전체: 70 PASS / 1 skipped / 1 무관 fail (`bridge_lib.PORT` 환경 분리, 본 PR 무관)

live e2e 봉인 유지

`tests/test_live_e2e.py` 의 final submit 테스트는 `PYTEST_CURRENT_TEST + TOSS_BRIDGE_ENABLE_FINAL_SUBMIT=1 + TOSS_BRIDGE_ALLOW_TEST_FINAL_SUBMIT 미설정` 조합으로 `blocked_in_pytest` 가드. supervised P6 진입 전까지 라이브 호출 발생 X.

Test plan

• 단위 테스트 70 PASS / 1 무관 fail
• live e2e `blocked_in_pytest` 가드 동작 확인 (`test_final_submit_stays_blocked_under_pytest_even_if_env_requests_enable`)
• OFF 분기 디폴트 동작 무영향 확인 (기존 `test_place_order_returns_capability_not_ready_until_verify_is_implemented` PASS)
• BRIDGE_VERSION 3중 동기 (pyproject ↔ `version` ↔ `daemon.BRIDGE_VERSION`) 검증
• supervised P6 — financier-v2 측 wrapper PR 머지 + 사용자 PC + 정규장 시간대에 4건 supervised live (limit buy / limit sell / market sell / fx KRW→USD)

🤖 Generated with Claude Code

[pghoya2956]

Already merged via 53fd337 (502 race during initial gh pr merge, but commit went through)