From 00ce5d95bb58f2e75d72959f7f577c19afe7103a Mon Sep 17 00:00:00 2001 From: Justin Ko Date: Tue, 16 Jun 2026 13:26:31 +0900 Subject: [PATCH] =?UTF-8?q?docs(rel-008):=20draft=20+=20confirm=20?= =?UTF-8?q?=E2=80=94=20=ED=98=B8=EA=B0=80=EB=8B=A8=EC=9C=84=20=EC=8A=A4?= =?UTF-8?q?=EB=83=85(#28)=20+=20=EC=9A=B4=EC=98=81=20=EA=B4=80=EC=B8=A1?= =?UTF-8?q?=EC=84=B1(#29)=20=ED=86=B5=ED=95=A9=20=EB=A6=B4=EB=A6=AC?= =?UTF-8?q?=EC=A6=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit BAT-044/045/046(release-candidate)를 REL-008(app-service)로 묶음. 배포 전 준비 근거(운영자 확인용) 표 기록 — 537 passed/47 skipped, ruff clean, DB 스키마 무변경(롤백 무손실), 호가단위 케이스·로깅·주문결과·거부ERROR·실현PnL 단위 검증. confirm-release: draft → confirmed (Recorded By: Justin Ko). 실 운영 배포 + #28/#29 close 는 capture-release-feedback 단계. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/releases/index.md | 1 + ...08_20260616_tick-snap-and-observability.md | 113 ++++++++++++++++++ 2 files changed, 114 insertions(+) create mode 100644 docs/releases/rel-008_20260616_tick-snap-and-observability.md diff --git a/docs/releases/index.md b/docs/releases/index.md index dc0b46d..55c4a2a 100644 --- a/docs/releases/index.md +++ b/docs/releases/index.md @@ -15,3 +15,4 @@ | REL-005 | app-service | feedback-captured | BAT-024, BAT-025 | dcy-016 후속/issue #17 (operator enter --forced-close-at) + dcy-019/issue #18 (slot entry_count + closed 슬롯 재할당) — 통합 릴리즈 | [rel-005](rel-005_20260609_operator-forced-close-and-slot-reallocation.md) | | REL-006 | app-service | feedback-captured | BAT-026, BAT-027, BAT-028, BAT-029, BAT-030, BAT-031, BAT-032, BAT-033, BAT-034, BAT-035, BAT-036 | dcy-020 (자산 중심 영구 슬롯 α~δ cutover) + dcy-021 (포지션 사이징/issue #1·#5) + dcy-022 (실행 정책/issue #21) + dcy-023 (allocated_capital 제거/issue #22) + dcy-024 (safety_sell_enabled/issue #15) + dcy-025 (slots.req 교체·REQ-028 Deprecated) + REQ-048·010 CHG (config-dir) + REQ-032 CHG (enter --qty/issue #23) — 통합 릴리즈 | [rel-006](rel-006_20260611_asset-centric-sizing-execution-policy.md) | | REL-007 | app-service | feedback-captured | BAT-037, BAT-038, BAT-039, BAT-040, BAT-041 | dcy-025 (REQ-073 CHG — available_slots hint) + dcy-026/issue #24 (매도세 정정) + issue #4 (paper seq Redis) + issue #25 (slots RPC DB 필터) + dcy-027/issue #20 (중장기 인스턴스 프로파일) — 통합 릴리즈 | [rel-007](rel-007_20260612_slots-rpc-fee-paper-longterm.md) | +| REL-008 | app-service | confirmed | BAT-044, BAT-045, BAT-046 | dcy-030/issue #28 (호가단위 스냅, P0 체결 복구) + dcy-029/issue #29 (운영 관측성 — 구조화 로깅·주문결과·거부ERROR·reason+actor·PnL CLI·런북) — 통합 릴리즈 | [rel-008](rel-008_20260616_tick-snap-and-observability.md) | diff --git a/docs/releases/rel-008_20260616_tick-snap-and-observability.md b/docs/releases/rel-008_20260616_tick-snap-and-observability.md new file mode 100644 index 0000000..5347003 --- /dev/null +++ b/docs/releases/rel-008_20260616_tick-snap-and-observability.md @@ -0,0 +1,113 @@ +# REL-008: 호가단위 스냅(#28) + 운영 관측성(#29) 통합 릴리즈 + +- Status: confirmed +- Profile: app-service +- Included Batch: BAT-044, BAT-045, BAT-046 + +## Scope +- Included: + - **BAT-044** (dcy-030 / issue #28, P0): slippage 보호 지정가 KRX 호가단위 스냅. `domain/pricing.py`(tick 유틸, REQ-083) + `execution.py` 스냅(REQ-070 CHG-20260616-01) — 상한 준수(매수 floor/매도 ceil) + band<1tick 하한/상한 보장 + 부동소수 epsilon 가드. slippage_pct>0 매수의 호가단위 위반 전량 거부 해소. + - **BAT-045** (dcy-029 P0): 구조화 로깅 기반 — ISO8601(KST) 타임스탬프·레벨, Loki JSON 출력(`TREX_LOG_FORMAT`), correlation id(slot_id)(REQ-084); 주문 결과 로깅 `event=order_submit|order_fill|order_reject`(REQ-085); 거부 ERROR 가시화(REQ-087). + - **BAT-046** (dcy-029 P1): 청산 reason+actor 동반 노출(REQ-086); 운영 조회 CLI `trex-core report`(보유·오늘 체결·실현 PnL net·대기, direct-DB)(REQ-088); 운영자 런북 `docs/operations.md`(REQ-089); baseline 정합(REQ-090). +- Excluded: + - 알림 전송 채널(dcy-029 OQ-3 Deferred — 후속 반복). + - ETF/ETN 비주식 호가체계(dcy-030 OQ-1 — 주식 전용). + - 실현 PnL의 cost-basis 매칭(net 매매 현금흐름 정의 채택). + - dcy-028 BAT-042/043(strategy-state·retryable) — 별도 release 트랙(release-candidate 유지). + +## Rollout Plan +1. 배포 전: 전체 테스트 green 확인(537 passed/47 skipped), ruff clean, DB 스키마 변경 없음 확인(마이그레이션 불필요). +2. main 배포 커밋 체크아웃(REL-008 내용 포함) → 운영 인스턴스 데몬 재기동. +3. 배포 후: 로그에 ISO8601(KST)+레벨 prefix 확인, `event=order_submit|fill|reject` 라인 확인, slippage 매수 주문이 유효 호가로 제출(거부 0) 확인, `trex-core report` 동작 확인. +4. (옵션) `TREX_LOG_FORMAT=json` 설정 시 Loki 적재 확인. + +## Rollback Plan +- 트리거: 기동 실패 / 주문 제출 이상(호가단위·가격 오류) / 로그 포맷으로 인한 수집 파이프라인 장애 / report 오류. +- 절차: 데몬 정지 → 이전 커밋(REL-008 이전, REL-007 라인 = `1f59322`) 체크아웃 → 재기동. **DB 스키마 변경 없어 데이터 무손실**. +- 부분 롤백: `TREX_LOG_FORMAT`을 `text`(기본)로 두면 JSON/Loki 경로 비활성(비파괴적). 호가단위 스냅은 코드 경로라 부분 비활성 불가 — 전체 롤백. + +## Verification Checklist +- 배포 전: + - 전체 단위/통합 테스트 green (537 passed, 47 skipped), ruff clean. + - BAT-044/045/046 verification.md 모두 Ready for Release: true. + - DB 스키마 변경 없음(마이그레이션 불필요) 재확인. +- 배포 후: + - 로그 라인에 ISO8601(KST)+레벨 prefix 존재. + - slippage 적용 매수 주문이 유효 KRX 호가로 제출되고 `event=order_reject` 호가단위 거부가 사라짐(issue #28 해소). + - 거부 발생 시 `event=order_reject`가 ERROR 레벨로 가시화. + - `trex-core report`가 보유·오늘 체결·실현 PnL·대기 주문을 출력. + +## 배포 전 준비 근거 (Pre-Deployment Readiness — 운영자 확인용) + +운영자가 배포 직전 확인할 근거. 본 릴리스는 confirm 시점(2026-06-16) 기준 아래를 모두 충족한다(실 운영 배포·환류는 capture-release-feedback 단계). + +| 항목 | 근거 | 상태 | +| --- | --- | --- | +| 전체 테스트 green | `.venv/bin/python -m pytest -q` → **537 passed, 47 skipped**(47 skip = 실 DB/RabbitMQ 게이트), 회귀 0 | ✅ | +| Lint | `.venv/bin/ruff check trex_core/ tests/` → All checks passed | ✅ | +| Batch 검증 완료 | BAT-044/045/046 `verification.md` 모두 Ready for Release: true, Blocking Issues 없음 | ✅ | +| DB 스키마 변경 | 없음 — 신규 마이그레이션 0개(`sql/` 변경 없음) → 롤백 무손실 | ✅ | +| 호가단위 스냅(#28) | issue #28 케이스 단위 검증(147,700→148,400 / 54,500→54,700), 상한 미초과·유효 호가 불변식 테스트 | ✅ | +| 로깅 포맷(REQ-084) | text/json·ISO8601(KST)·correlation id 포맷터 단위 검증, `configure_logging` idempotent | ✅ | +| 주문 결과·거부 ERROR | `event=order_submit\|fill\|reject` + 거부 ERROR 레벨 단위 검증(caplog) | ✅ | +| 실현 PnL 집계(REQ-088) | `operator_report` net 현금흐름·KST 경계·렌더 단위 검증 | ✅ | +| 비파괴성/하위호환 | slippage 미사용·시장가·0% 경로 회귀 없음; 로그 포맷 `text` 기본; report·reason+actor additive | ✅ | +| 롤백 경로 | 이전 커밋 `1f59322`(REL-007 라인) 체크아웃 + 재기동, DB 무변경 | ✅ | + +배포 후 운영자 확인 항목은 아래 `Verification Checklist > 배포 후` 및 `Profile-Specific Checks(app-service)` 참조. + +## Release Execution Evidence +- Release Status Transition Target: released + +### Deployment Facts +- Executed At: + - <배포 시 기록> +- Completed At: + - <배포 시 기록> +- Environment: + - <배포 대상 환경 — 예: /root/release 운영, instance_key=trex-admin-daily-trading> +- Operator: + - <배포 수행자> +- Revision or Artifact: + - 커밋 `d8d9021` 이상(REL-008 내용 포함) — 배포 시 확정 +- Commands or Procedure: + - <배포 절차 요약> + +### Profile-Specific Checks +- app-service: + - Health Endpoint: + - N/A(데몬은 HTTP 표면 없음 — BAT-007). "ready" = 4 워커 스레드 + RabbitMQ 토폴로지 선언, 로그 ERROR/traceback 0. (배포 후 확인) + - Startup Log Fields: + - 배포 전 근거: `runtime/logging_setup.configure_logging` 단위 검증으로 기동 로그가 ISO8601(KST)+레벨 prefix를 갖도록 보장(`test_configure_text_default`/`test_configure_json_format`). 배포 후 실제 기동 로그 1줄 확인. + - Request Log Fields: + - 배포 전 근거: 주문 결과 로그 `event=order_submit|order_fill|order_reject` + correlation_id(slot_id) 단위 검증(`TestOrderResultLogging`). 배포 후 실거래 주문 1건의 submit→fill 로그 cid 일치 확인. + - Smoke or Manual Verification: + - 배포 전 근거: slippage 매수 유효 호가 스냅(issue #28 케이스) + 거부 ERROR + `operator_report` 집계 단위 검증(537 passed). 배포 후 실거래 slippage 매수가 호가단위 거부 0으로 체결 + `trex-core report` 출력 확인. + +### Rollback Outcome +- Rollback Required: + - +- Rollback Trigger: + - none +- Rollback Action: + - none + +### Release Decision Evidence +- Released Decision: + - confirmed (배포 승인) — 실 운영 released 전환은 capture-release-feedback 단계에서 배포 근거와 함께 기록 +- Rationale: + - BAT-044/045/046 전 verification confirmed(Ready for Release: true, Blocking Issues 없음). 537 passed/47 skipped 회귀 0, ruff clean. DB 스키마 변경 없어 롤백 무손실. 호가단위 스냅(#28)·로깅·주문 결과·거부 ERROR·reason+actor·PnL CLI 단위/통합 검증 완료. 비파괴적 additive 중심(로그 포맷 text 기본, report/reason+actor additive, slippage 미사용 경로 회귀 없음)으로 회귀 위험 낮음. +- Recorded By: + - Justin Ko +- Recorded At: + - 2026-06-16 13:25 KST + +## Feedback Handoff +- Observation Summary: + - <배포 후 기록> +- Discovery Input: + - <후속 discovery 후보> +- REQ Input: + - <후속 req 후보> +- Change Request Input: + - <기존 req 변경 후보>