docs(release): M2 REL-009 confirm-release + batch release-candidate 전이

trex-core의 release-prep: - 배치 검증 완료 (BAT-047, BAT-048) - M2 event reliability + fill guard + alarm runbook 문서 (REL-009) - releases index 업데이트 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VHtM5Ws1HKCKQ4JGi6GRb5
2026-06-25 12:55:33 +09:00
parent 5bdd72040e
commit 34700f3035
4 changed files with 190 additions and 3 deletions
@@ -1,6 +1,6 @@
 # BAT-047 Verification

- Status: approved (confirm-batch-verification, 팀장 2026-06-19)
+- Status: release-candidate
 - Batch: BAT-047
 - Verified By: trex-core-dev (draft-batch-verification → QC PASS-WITH-NOTES 시정 후 재검증)
 - Verified At (KST): 2026-06-19 (최초), 2026-06-19 (QC 시정 재검증)
@@ -128,4 +128,4 @@ QC opus 검증에서 지적된 2건을 시정했다.
 - wire 계약 무회귀: PASS
 - baseline 문서 정합: PASS
 - Blocking Issues: 없음
- Ready for Release: false (멈춤 — confirm-batch-verification은 팀장 게이트)
+- Ready for Release: true (팀장 confirm-release 승인 2026-06-25 — 이미 검증·푸시 완료, REL-009 포함 확정)
@@ -1,6 +1,6 @@
 # BAT-048 Verification

- Status: draft
+- Status: verified (confirm-batch-verification 팀장 2026-06-21)
 - Batch: BAT-048
 - Scope: REQ-095 (지정가 백필 가드), REQ-096 (백필 WARN 로깅)
 - REQ-097: 알람 능력 스파이크 산출물로 완료 — 알람 실제 구현은 사장님 결정에 따라 이 batch 완료 후 별도 트랙 이월
@@ -16,3 +16,4 @@
 | 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 | feedback-captured | BAT-042, BAT-043, BAT-044, BAT-045, BAT-046 | dcy-028/issue #26 (slot strategy-state) + issue #27 (sell retryable) + dcy-030/issue #28 (호가단위 스냅, P0 체결 복구) + dcy-029/issue #29 (운영 관측성 — 구조화 로깅·주문결과·거부ERROR·reason+actor·PnL CLI·런북) — 통합 릴리즈 | [rel-008](rel-008_20260616_tick-snap-and-observability.md) |
+| REL-009 | app-service | confirmed | BAT-047, BAT-048, BAT-049 | dcy-031/OPS-005 (이벤트 발행 신뢰성 — idle keepalive·재시도·DLQ 경보) + dcy-032 (체결가 0/None 백필 가드·WARN 로깅) + dcy-033 (알람 emitter + trex.alerts exchange 1단계) + dcy-017 후속(무데이터/죽은 종목 위생 런북 docs-only) — M2 통합 릴리즈 | [rel-009](rel-009_20260625_event-reliability-fill-guard-alarm-runbook.md) |
@@ -0,0 +1,186 @@
+# REL-009: OPS-005 이벤트 발행 신뢰성 + 체결가 가드 + 알람 emitter + 무데이터 런북 (M2 통합 릴리즈)
+
+- Status: confirmed
+- Profile: app-service
+- Included Batch: BAT-047, BAT-048, BAT-049
+
+## Scope
+
+- Included:
+  - **BAT-047** (dcy-031 / OPS-005): 이벤트 발행 연결 신뢰성 — `publish_event` 1회 실패 시 강제 재연결+재시도(REQ-091), 발행 전용 연결 idle keepalive `process_data_events` 틱(REQ-092), DLQ 유입/emit 최종 실패 ERROR 경보(REQ-093), baseline 문서 정합(REQ-094). **M1 프로덕션(9e35467) 미반영 결함 해소 — idle 60초 후 첫 전이 이벤트 유실 제거.**
+  - **BAT-048** (dcy-032): 체결가 0/None 백필 가드 + WARN 로깅 — `_on_filled`/`_on_partial_cancel`에서 avg_price=0/None 시 지정가 백필(REQ-095), 백필/unresolvable WARN 로그(reason 필드 포함)(REQ-096), 알람 능력 스파이크 산출물·후보 A/B/C 분석(REQ-097 — 알람 실제 구현은 dcy-033 이월). **슬롯 avg_price·원장 cost basis의 무경고 0오염 제거.**
+  - **BAT-049** (dcy-033): 알람 시스템 1단계 — 알람 envelope 표준 JSON 스키마·`trex.alerts`(topic, durable=True) exchange 신규 선언(REQ-098/099), application `AlarmEmitter` + CRITICAL code 8종 배선(REQ-100), `runtime-flows.md` 알람 발신 흐름 기술(REQ-101). **기존 wire 계약(exchange/큐/라우팅) 불변 — 가산·격리 추가.**
+  - **dcy-017 후속 운영자 런북** (docs-only, 2026-06-22): 지속 무데이터/죽은 종목 위생 절차 `docs/operations.md §7` 신규 기재 — pause/resume 시맨틱 검증·Step 1~3b 절차·고아 방지 순서 명시. 코드 변경 없음.
+
+- Excluded:
+  - 이벤트 발행 영속 outbox(옵션 C) — M3 후보
+  - consumer(orb/tsl) idempotency 구현 — OQ-2(각 repo 추적)
+  - 알람 수신·텔레그램 전달(trex-notifier) — **배포 의존성(아래 참조)**
+  - INFO·WARN 알람 code 배선 — M3 이후
+  - 과거 0 기록 원장/슬롯 소급 정정
+
+- Scope Note:
+  - BAT-047은 origin/main(`b2165ea`) 기준 이미 푸시됨 — 이번 배포는 현재 local main HEAD(`5bdd720`) 전체를 싣는 체크아웃 갱신이다.
+  - dcy-017 런북은 별도 Discovery/Batch를 생성하지 않은 docs-only 패치(커밋 `5bdd720`)이며 코드 변경 없음.
+
+## 배포 의존성 및 순서 (필독)
+
+### trex-notifier 선행 조건
+
+`trex.alerts` exchange 선언은 데몬 기동 시 `declare_topology()`가 자동 수행한다. 알람 발행(`mandatory=False`)은 notifier 미연결 시 silent drop — **core 기동 자체는 notifier 없이도 안전**하다.
+
+그러나 알람 수신·텔레그램 전달(trex-notifier)이 연결되지 않은 상태에서 CRITICAL 이벤트가 발생하면 알람이 유실(drop)된다. 따라서:
+
+1. **trex-notifier 배포·바인딩 선행**: `trex.alerts`에 바인딩된 notifier 큐가 없으면 알람이 RabbitMQ에서 곧바로 drop된다. trex-notifier를 먼저 띄우고 `trex.alerts` 바인딩을 확인한 뒤 trex-core를 재시작한다.
+2. **trex-core는 orb/tsl 이벤트 발행 경로의 중심**이다. trex-core 재시작 시간 동안 orb/tsl이 AMQP를 통해 trex-core로 전송하는 slot 의도(intent)가 일시 지연될 수 있다. 가능하면 거래 비활성 시간대(장 외)에 배포한다.
+
+### 배포 순서 요약
+
+```
+1. (장 외 시간) trex-notifier 배포 및 trex.alerts 바인딩 확인
+2. trex-core main 갱신 → pip install -e . (의존성 변경 없음 — 확인 후 생략 가능) → 데몬 재시작
+3. (선택) trex-orb-v1 / trex-tsl-v1 재시작 — 코드 변경 없어 강제 아님, keepalive/재연결은 core 측 개선임
+```
+
+## Rollout Plan
+
+1. **배포 전 준비**
+   - 전체 테스트 green 확인: `python3 -m pytest -q` → **608 passed, 47 skipped** (현재 HEAD `5bdd720` 기준 검증 완료).
+   - ruff clean 확인: `ruff check trex_core/ tests/` → `All checks passed!`.
+   - BAT-047/048/049 `verification.md` 상태: BAT-047 approved, BAT-048 verified(팀장 confirm 완료), BAT-049 release-candidate(팀장 실인프라 e2e 포함 confirmed).
+   - DB 스키마 변경 없음 — 신규 마이그레이션 없음. `apply_migrations` 기존 001~015 idempotent 재실행.
+   - trex-notifier 배포·`trex.alerts` 바인딩 완료 확인 (선행 조건).
+
+2. **배포 실행** (운영 환경 — bare .venv, instance_key=`trex-admin-daily-trading`)
+   - `git pull` (또는 `git fetch && git checkout 5bdd720`) — local main을 프로덕션 체크아웃 경로에 반영.
+   - 의존성 변경 여부 확인: `git diff 9e35467 HEAD -- pyproject.toml` → 변경 없으면 `pip install -e .` 생략 가능.
+   - `trex-core-daemon` 재시작 (기존 PID 종료 후 신규 기동).
+   - 기동 로그에서 `trex.alerts` exchange 선언 성공(`declare_topology` 완료) 확인.
+
+3. **배포 후 검증** (아래 Verification Checklist 참조)
+
+## Rollback Plan
+
+- **트리거**: 데몬 기동 실패 / `trex.alerts` exchange 선언 오류 / 이벤트 발행 경로 이상(재시도 루프 과다·DLQ 급증) / 체결 처리 이상(백필 WARN 폭증·슬롯 PENDING 고착) / 기존 서비스 연동 장애.
+- **절차**:
+  1. 데몬 정지.
+  2. 이전 커밋 체크아웃: `git checkout 9e35467` (REL-008 배포본 = M1 프로덕션 라인).
+  3. `trex-core-daemon` 재기동.
+  4. **DB 스키마 변경 없음** — 마이그레이션 없으므로 롤백 시 데이터 무손실.
+  5. `trex.alerts` exchange는 롤백 후에도 RabbitMQ에 남아있으나 발행자가 없어 무해. 필요 시 관리 UI에서 수동 삭제 가능(비필수).
+- **부분 완화**: `AlarmEmitter`는 best-effort 삼킴 패턴으로 기동·발행 경로가 알람 실패에 비차단. 알람 발행 오류만 발생하면 롤백 대신 notifier 재바인딩을 먼저 시도한다.
+
+## Verification Checklist
+
+### 배포 전
+
+- [ ] 전체 테스트 green: `python3 -m pytest -q` → 608 passed, 47 skipped, 0 fail (HEAD `5bdd720`).
+- [ ] ruff clean: `ruff check trex_core/ tests/` → `All checks passed!`.
+- [ ] BAT-047 verification: Status=approved (confirmed 2026-06-19).
+- [ ] BAT-048 verification: Status=verified (confirmed 2026-06-21).
+- [ ] BAT-049 verification: Status=release-candidate (팀장 실인프라 e2e confirmed 2026-06-21).
+- [ ] trex-notifier 배포·`trex.alerts` 바인딩 완료 (선행).
+- [ ] DB 스키마 변경 없음 재확인 (마이그레이션 없음).
+- [ ] `docs/interface-contract.md` 변경 범위 확인: BAT-049 `trex.alerts` 섹션 추가(기존 섹션 diff=0).
+- [ ] **OPS-005 배포갭 인지**: 현재 프로덕션 M1(`9e35467`)은 idle keepalive·재시도 미포함 — 이번 배포가 해소.
+
+### 배포 후
+
+- [ ] **OPS-005 해소 확인 (BAT-047 핵심)**: 장 시작 후 orb/tsl → core idle 60초 이상 경과 후 첫 slot 전이 이벤트가 정상 수신되는지 확인. `ConnectionReset` / `StreamLostError` 로그 무재발 확인. `slot_filled` / `slot_entered` 이벤트가 orb/tsl에 도달하는지 확인.
+- [ ] 데몬 기동 로그: `declare_topology` 정상 완료, `trex.alerts` exchange 선언 포함, ERROR/CRITICAL/Traceback 0.
+- [ ] keepalive 동작 확인: 기동 후 60초 경과 시 `keepalive_tick` 호출 로그(또는 무오류) 확인.
+- [ ] 알람 발행 경로 확인: CRITICAL 이벤트 발생 시 `alarm.critical.trex-core` routing key로 `trex.alerts`에 발행되고 trex-notifier가 텔레그램 전달하는지 확인 (e2e 경로).
+- [ ] 체결 처리: 정상 체결 시 avg_price 백필 WARN 미발생 확인. KIS avg_price 이상 케이스 발생 시 WARN 로그 필드(slot_id/symbol/backfill_price/reason) 확인.
+- [ ] **AMQP wire 무회귀**: `trex.events`, `trex.intent.req`, `trex.slots.req`, `trex.control.req` exchange/큐/라우팅 형식 불변 확인. orb/tsl 연동 장애 없음 확인.
+- [ ] `trex-core report` 정상 동작 (REL-008 기능 회귀 없음).
+
+## AMQP Wire 계약 무회귀 체크포인트
+
+이번 릴리즈의 AMQP 변경 범위는 아래로 한정된다. orb/tsl 연동에 영향 없음을 명시한다.
+
+| 항목 | 변경 여부 | 근거 |
+|---|---|---|
+| `trex.events` exchange/토폴로지 | 불변 | BAT-047 Out of Scope 명시, verification NFR-1 PASS |
+| `trex.intent.req` 큐/라우팅 | 불변 | BAT-047/048/049 모두 불변 확인 |
+| `trex.slots.req` 큐/스키마 | 불변 | BAT-047/048/049 모두 불변 확인 |
+| `trex.control.req` 큐 | 불변 | 변경 없음 |
+| 슬롯 이벤트 페이로드 스키마 | 불변 | BAT-047 wire 무회귀 PASS |
+| `trex.alerts` exchange | **신규 추가** (가산·격리) | BAT-049 REQ-099. 기존 exchange/큐에 무영향. mandatory=False — unroutable silent drop |
+| `docs/interface-contract.md` | **trex.alerts 섹션 신규** (기존 섹션 diff=0) | BAT-049 REQ-098 AC-3 PASS |
+
+## Release Execution Evidence
+
+- Release Status Transition Target: released
+
+### Deployment Facts
+
+- Executed At:
+  - (배포 예정 — 2026-06-26 또는 사장님 결재 후 지정 윈도우)
+- Completed At:
+  - (미정)
+- Environment:
+  - 운영 (`/root/release` 또는 해당 경로, instance_key=`trex-admin-daily-trading`, 실거래 KIS 계좌 91254), bare .venv
+- Operator:
+  - (배포 담당자)
+- Revision or Artifact:
+  - `9e35467`(REL-008 M1 현재 프로덕션) → **`5bdd720`(REL-009 HEAD)**.
+  - BAT-047: `d182464`, BAT-048: `f1b649c`, BAT-049: `d4c5fcb`, dcy-017 런북: `5bdd720`.
+- Commands or Procedure:
+  - `git pull` (또는 체크아웃 `5bdd720`) → `pip install -e .` (의존성 변경 시) → `trex-core-daemon` 재시작.
+  - 마이그레이션: 기동 시 `apply_migrations` 자동 실행 (001~015 idempotent, 신규 없음).
+
+### Profile-Specific Checks
+
+- app-service:
+  - Health Endpoint:
+    - N/A (데몬은 HTTP 표면 없음). "ready" = 워커 스레드 + RabbitMQ 토폴로지 선언(`trex.alerts` 포함) 완료, 로그 ERROR/Traceback 0.
+  - Startup Log Fields:
+    - (배포 후 기재) ISO8601(KST)+레벨 prefix, `declare_topology` 완료 로그, `trex.alerts` exchange 선언 확인, ERROR/CRITICAL/Traceback 0.
+  - Request Log Fields:
+    - (배포 후 기재) 이벤트 발행 `event=slot_entered|slot_filled` 로그, keepalive 틱 정상, OPS-005 ConnectionReset 무재발.
+  - Smoke or Manual Verification:
+    - (배포 후 기재) idle 60초 후 첫 이벤트 유실 없음 확인, 알람 e2e(CRITICAL → trex-notifier → 텔레그램) 확인, `trex-core report` 정상.
+
+### Rollback Outcome
+
+- Rollback Required:
+  - (배포 후 기재)
+- Rollback Trigger:
+  - (배포 후 기재, 없으면 none)
+- Rollback Action:
+  - (배포 후 기재, 없으면 none)
+
+### Release Decision Evidence
+
+- Released Decision:
+  - (배포 후 기재)
+- Rationale:
+  - (배포 후 기재)
+- Recorded By:
+  - (배포 후 기재)
+- Recorded At:
+  - (배포 후 기재)
+
+## Feedback Handoff
+
+- Observation Summary:
+  - (배포 후 기재)
+- Discovery Input:
+  - **이벤트 발행 영속 outbox**: BAT-047 Out of Scope으로 이월됨(M3 후보). at-least-once 중복 이벤트 소비자 멱등성도 함께 추적.
+  - **실 broker 통합 CI**: half-open/idle 60초/broker 재시작 시나리오는 현재 mock unit으로만 검증. `TREX_RABBITMQ_TEST_URL` 포함 통합 환경 구성(M3 후보).
+  - **INFO·WARN 알람 code 배선**: CRITICAL 8종 이후 후속 범위(dcy-033 범위 경계 밖, M3 후보).
+- REQ Input:
+  - none
+- Change Request Input:
+  - none
+
+## 미해결 / 잔여 위험
+
+| 항목 | 수준 | 설명 | 해소 방안 |
+|---|---|---|---|
+| trex-notifier 미선행 시 알람 유실 | Medium | notifier 없이 core 배포 시 CRITICAL 알람 silent drop | 배포 순서 준수: notifier → core |
+| 지정가 백필 추정치 오차 | Medium | BAT-048 R-1: 실제 체결가 ≠ 지정가 가능. reason=avg_price_backfill WARN으로 추적 가능 | 운영자 WARN 발생 시 operations.md §5 절차 참조 |
+| fill_price_unresolvable 슬롯 고착 | Low | BAT-048 R-2: limit_price=None 시 PENDING 고착 → watchdog 탐지 필요 | 기존 stale_pending watchdog 동작, 운영자 개입 |
+| half-open/idle 실인프라 검증 | Low | BAT-047 mock unit 검증 — 실 broker 통합 skip (환경 미구성) | 배포 후 OPS-005 재발 모니터링으로 실증, M3 통합 CI |
+| NFR-2 publish 블록 최악 케이스 | Low | BAT-047: 1차 실패 시 원 socket_timeout(5.0s) 초과 가능 | 배포 후 모니터링, 필요 시 후속 REQ(publish timeout 강화) |
+| BAT-049 통합(실 RabbitMQ) 3건 | Low | declare_topology/mandatory=False/기존 topology 불변은 팀장 실인프라 e2e에서 확인됨(2026-06-21) | 배포 후 Smoke 체크포인트로 재확인 |