trex-core/docs/releases/rel-008_20260616_tick-snap-and-observability.md

REL-008: 호가단위 스냅(#28) + 운영 관측성(#29) + slot strategy-state(#26)·retryable(#27) 통합 릴리즈

• Status: feedback-captured
• Profile: app-service
• Included Batch: BAT-042, BAT-043, BAT-044, BAT-045, BAT-046

Scope

• Included:
  • BAT-042 (dcy-028 / issue #26): slot strategy-state 저장소 — slot_strategy_state 테이블 + StrategyStateStore(occupancy_seq·version CAS) + write RPC trex.slots.strategy_state.set + occupancy_seq 가드/close 삭제 + slots.req strategy_state·occupancy_seq additive (REQ-079·080·081·082, REQ-073/074 CHG). 마이그레이션 014/015.
  • BAT-043 (issue #27): rejected SellIntent 응답 additive retryable: bool (REQ-007 CHG-20260615-01).
  • 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 매매 현금흐름 정의 채택).
• Scope Note:
  • BAT-042/043은 단일 main 브랜치상 배포 HEAD(00ce5d9)의 조상으로 함께 배포되는 release-candidate 배치다. 초안 시 제외했으나, "남아있는 배치 전부를 REL-008로" 지시에 맞춰 본 릴리스에 포함하도록 정정(배포 현실 = main 통째 배포와 일치). 마이그레이션 014/015는 BAT-042 소속.

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 스키마 변경	마이그레이션 014/015(BAT-042 소속, 본 릴리스 포함) — 기동 시 자동 적용(additive·idempotent: daily_slot.occupancy_seq, slot_strategy_state 테이블). 구버전은 두 객체 미참조라 롤백 무손실	✅
호가단위 스냅(#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:
  • 2026-06-16 13:41:22 KST
• Completed At:
  • 2026-06-16 13:41:26 KST
• Environment:
  • /root/release 운영, instance_key=trex-admin-daily-trading (실거래 KIS 계좌 91254)
• Operator:
  • 배포 에이전트
• Revision or Artifact:
  • 1f59322(REL-007) → 00ce5d9(REL-008). PID 1778 → 193867.
• Commands or Procedure:
  • scripts/deploy-trex-core.sh --update-only(git pull) → --restart-only(데몬 재기동). 마이그레이션 014/015는 데몬 기동 시 apply_migrations 자동 적용. 배포 전 포지션 0(재시작 안전).

Profile-Specific Checks

• app-service:
  • Health Endpoint:
    • N/A(데몬은 HTTP 표면 없음 — BAT-007). "ready" = 4 워커 스레드 + RabbitMQ 토폴로지 선언, 로그 ERROR/traceback 0. (배포 후 확인)
  • Startup Log Fields:
    • ✅ 배포 후 확인: 기동 로그가 2026-06-16T13:41:24.044+09:00 INFO pika... 형태로 ISO8601(KST)+레벨 prefix 전환(이전 INFO:pika: 타임스탬프 없음). ERROR/CRITICAL/Traceback 0.
  • Request Log Fields:
    • 배포 후 포지션 0이라 실거래 주문 미발생 — 단위 검증(TestOrderResultLogging, cid=slot_id submit→fill)으로 보장. 다음 거래일(06-17) 실거래 주문에서 재확인.
  • Smoke or Manual Verification:
    • ✅ #28 호가단위 스냅: 배포된 domain/pricing.py로 어제 거부 2건 재계산 — 000720 entry 147,700 → 148,400(유효), 006800 entry 54,500 → 54,700(유효). ✅ trex-core report 동작(보유 0/대기 0/오늘 체결 0/실현 PnL 0). ✅ slots RPC 145개 정상, RabbitMQ ESTABLISHED 5. 실거래 slippage 매수 거부 0 체결은 06-17 거래일 확인.

Rollback Outcome

• Rollback Required:
  • no
• Rollback Trigger:
  • none (기동 정상, #28 스냅·로깅·report 검증 통과)
• Rollback Action:
  • none

Release Decision Evidence

• Released Decision:
  • released (2026-06-16 13:41 KST 운영 배포 완료, 00ce5d9, PID 193867)
• Rationale:
  • BAT-044/045/046 전 verification confirmed. 운영 배포 후 #28 호가단위 스냅(147,700→148,400 / 54,500→54,700)·구조화 로깅(ISO8601 KST prefix)·trex-core report·데몬 건강(ERROR 0, slots RPC 145) 실환경 검증. 마이그레이션 014/015 자동 적용(additive·idempotent). 롤백 불요.
• Recorded By:
  • Justin Ko (confirm) / 배포 에이전트 (운영 배포 근거)
• Recorded At:
  • 2026-06-16 13:25 KST (confirm) / 2026-06-16 13:43 KST (배포 완료 근거)

Feedback Handoff

• Observation Summary:
  • (2026-06-16 13:43 KST, 배포 에이전트) REL-008 운영 배포 완료(00ce5d9, PID 193867, --restart-only). #28 호가단위 스냅 라이브 검증(어제 거부 2건 재계산: 147,700→148,400 / 54,500→54,700, 유효 호가·상한 준수), 구조화 로깅 전환(...+09:00 INFO KST prefix), trex-core report 동작, 마이그레이션 014/015 자동 적용 확인, 데몬 ERROR 0·slots RPC 145 정상.
  • 사전 테스트: 537 passed/46 skipped/1 failed. 1 failed = test_sandbox_token_and_submit — 운영 .env(:9443)가 샌드박스 테스트에 새어든 환경 아티팩트, REL-008 회귀 아님.
  • 거버넌스 정정(§4): main 단일 브랜치라 HEAD 배포 시 dcy-028(BAT-042/043, #26/#27) 코드가 동반 배포됨. 초안 시 본 릴리스에서 제외했으나 사용자 지시("남아있는 배치 전부")에 맞춰 BAT-042/043을 REL-008에 정식 포함하도록 정정 → 추적 갭 해소(운영 실체 = 배포 HEAD와 일치). occupancy_seq 코어 활성, slot_strategy_state 핸들러는 전략 호출 시만 동작(orb-v1 미사용)→저위험.
• Discovery Input:
  • #30 Loki push 핸들러: 현재 구조화 로그 text/json stdout만. Loki 적재(push)는 후속(이슈 #30 등록됨) — dcy-029 OQ-2/A-4(배포측 수집기) 연장선.
• REQ Input:
  • none (관측성·호가단위는 REQ-070/083/084~090로 처리 완료)
• Change Request Input:
  • none
• Follow-up Actions (비차단):
  • BAT-042/043(dcy-028 #26/#27) 운영 동반 배포 정식화 — 별도 release(REL-009 후보)로 retroactive 추적 권장(아래 사용자 결정 필요).
  • 실거래 #28 검증: 06-17 거래일 slippage 매수가 호가단위 거부 0으로 체결되는지 확인.
  • GitHub #28(수정 반영)·#29(기반 반영) close — 사용자 승인 후.