docs(release): confirm REL-001 trex-core slot-core baseline (BAT-001~008)

Bundle BAT-001~008 into REL-001 (app-service profile) and promote to confirmed. Register index row added. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-06 11:27:35 +09:00
parent 9e64a24441
commit f8c5661147
2 changed files with 103 additions and 0 deletions
@@ -8,3 +8,4 @@

 | REL ID | Profile | Status | Included Batch | Discovery/REQ Input | Link |
 | --- | --- | --- | --- | --- | --- |
+| REL-001 | app-service | confirmed | BAT-001~008 | Discovery: orb-v1 전략 모듈 / Change-req: REQ-030 옵션 D, 전략 필드 실데이터 | [rel-001](rel-001_20260606_trex-core-slot-core-baseline.md) |
@@ -0,0 +1,102 @@
+# REL-001: trex-core slot-core baseline (daemon + broker + ledger + RabbitMQ transport + portfolio-hub snapshot read)
+
+- Status: confirmed
+- Profile: app-service
+- Included Batch: BAT-001, BAT-002, BAT-003, BAT-004, BAT-005, BAT-006, BAT-007, BAT-008
+
+## Scope
+- Included:
+  - BAT-001 (REQ-001~004): slot 도메인 seed — 슬롯 상태/전이/일일 preallocate 도메인.
+  - BAT-002 (REQ-005~009): slot-core 데몬 골격 + 슬롯 영속(PostgreSQL single-writer). (당시 HTTP API 는 BAT-007 에서 RabbitMQ transport 로 대체됨 — 아래 Excluded 참조)
+  - BAT-003 (REQ-010): 데몬 dotenv config 로딩.
+  - BAT-004 (REQ-011~015): 브로커 실행 루프 + KIS 주문 어댑터 + 내구성 outbox handoff.
+  - BAT-005 (REQ-016): KIS 토큰 Redis 캐시(재기동/멀티프로세스 생존).
+  - BAT-006 (REQ-017~020): portfolio-hub ledger 통합(fill→ledger 기록, outbox 내구성/idempotency, baseline 정합).
+  - BAT-007 (REQ-021~026): 전략 모듈 ↔ trex-core RabbitMQ(AMQP) 메시지 transport. snapshot/intent/pause RPC + 이벤트 토픽 + DLQ. **HTTP /v1 API 제거.**
+  - BAT-008 (REQ-027~029, 031~033): portfolio-hub 스냅샷 read 레이어 — universe read 포트/어댑터, 일일 스냅샷 스케줄러(baseline), KIS 잔고 기반 포지션 정합 + warning 마스킹, Postgres pause/resume, slot overlay·view·strategy_key 자산 선별, snapshot RPC envelope + degraded 신호, baseline 3문서 정합.
+- Excluded:
+  - **REQ-030 AC-2/AC-3 (옵션 D — ledger write `*_after` 로 cash/position 갱신)**: portfolio-hub#8 (`ledger/trades` 응답에 `cash_balance_after`/`asset_quantity_after`) 배포 대기로 **이월**. REQ-030 은 AC-1(baseline 스케줄러)만 충족하여 status **Approved 유지(Implemented 아님)**. wiring point(`SnapshotStore.update_cash_position`)는 노출되어 있어 배포 후 1줄 활성화 예정.
+  - **portfolio-hub `/v1/portfolios` 의 전략 필드(active_strategy_id/strategy_params) 실데이터 채움**: 실 `PortfolioItem` 미제공으로 None/`{}` 통과(REQ-027 CHG-04, REQ-029 CHG-04). 단일 전략(orb-v1, strategy_key 미사용) 단계에서 무해. 2번째 전략 도입 시 detail `strategy_set` 보강 또는 별도 change-req 로 해소.
+  - **전략 모듈(orb-v1) 자체**: 본 릴리즈는 trex-core 코어만 포함. 전략 모듈은 별도 Discovery/배포.
+  - BAT-002 가 당시 제공한 HTTP /v1 API 표면: BAT-007 에서 제거됨 — 운영 배포 표면은 RabbitMQ 기반.
+
+## Rollout Plan
+1. 사전 점검: PostgreSQL / RabbitMQ / portfolio-hub 도달성 확인. `.env` 구성 검증(`TREX_POSTGRESQL_DSN`, `TREX_RABBITMQ_URL`, `TREX_PORTFOLIO_HUB_BASE_URL`(스킴 포함)·`TREX_PORTFOLIO_HUB_TOKEN`, `TREX_BROKER`(+ kis 시 `TREX_KIS_*`), 선택 `TREX_KIS_REDIS_URL`).
+2. DB 마이그레이션 적용: `trex_core/adapters/persistence/sql/001~003`(`003_create_snapshot_pause.sql` 포함). 모두 additive.
+3. 배포 대상 commit SHA 로 trex-core 설치 후 데몬 기동(6 워커 스레드: execution / ledger / intent-rpc / snapshot-rpc / pause-rpc / snapshot-scheduler).
+4. 기동 직후: 큐 declare 기반 readiness 확인 → snapshot RPC(view=all/buyable/held) → pause/resume RPC → 부팅 스냅샷 `degraded=false`(live portfolio-hub) 확인.
+
+## Rollback Plan
+- 첫 릴리즈라 되돌릴 이전 가동 버전이 없음 → 롤백 = **데몬 중지(서비스 정지)**.
+- DB 마이그레이션은 additive(신규 테이블/컬럼)라 데이터 파괴 없음. 필요 시 데몬 정지 상태 유지하고 `snapshot_pause` 등 신규 테이블은 보존(드롭 불필요).
+- 트리거 조건 예: 기동 실패, snapshot/pause RPC 비정상, ledger outbox 누락, 정합 검증 오탐으로 과도한 warning 마스킹.
+
+## Verification Checklist
+- 배포 전:
+  - 전체 테스트 통과(인프라 게이트 포함): `TREX_RABBITMQ_TEST_URL=... TREX_POSTGRESQL_TEST_DSN=... pytest -q`.
+  - `ruff check trex_core tests` → All checks passed.
+  - REQ-027 CHG-04 정정 계약 재검증 evidence 확인(BAT-008 verification Re-verification Addendum).
+  - 마이그레이션 001~003 적용 확인.
+- 배포 후:
+  - 데몬 기동 + 6 워커 스레드 + 큐(`trex.snapshot.req`/`trex.intent.req`/`trex.pause.req`)·exchange(`trex.events`)·DLQ 선언 확인.
+  - snapshot RPC envelope: `assets`(배열, null 금지) + meta(`view`/`available_slots`/`degraded`/`reason`), live portfolio-hub 대상 `degraded=false` + universe 수신.
+  - pause RPC: pause → 응답 마스킹, resume → 복귀, 재기동 후 영속 확인.
+  - 브로커 실행/ledger outbox flush 동작(paper 또는 kis 모의).
+  - 포지션 정합 1회 수행 + 불일치 시 warning 마스킹 동작.
+
+## Release Execution Evidence
+- Release Status Transition Target: released
+
+### Deployment Facts
+- Executed At:
+  - <배포 시작 시각>
+- Completed At:
+  - <배포 완료 시각>
+- Environment:
+  - <배포 대상 환경>
+- Operator:
+  - <배포 수행자>
+- Revision or Artifact:
+  - <커밋 SHA 또는 배포 artifact 식별자>
+- Commands or Procedure:
+  - <실행 명령 또는 배포 절차 요약>
+
+### Profile-Specific Checks
+- app-service:
+  - Health Endpoint:
+    - <HTTP health 엔드포인트 없음(RabbitMQ transport) → 큐 declare readiness 폴링 결과와 확인 시각>
+  - Startup Log Fields:
+    - <app, event, command, run_id 확인 결과>
+  - Request Log Fields:
+    - <request_id(RPC correlation_id) 포함 여부와 확인 결과>
+  - Smoke or Manual Verification:
+    - <배포 후 재실행한 snapshot/pause RPC 검증과 결과>
+
+### Rollback Outcome
+- Rollback Required:
+  - <yes 또는 no>
+- Rollback Trigger:
+  - <발생 시 원인, 없으면 none>
+- Rollback Action:
+  - <수행한 조치, 없으면 none>
+
+### Release Decision Evidence
+- Released Decision:
+  - <released 전환 여부>
+- Rationale:
+  - <released 전환 판단 근거>
+- Recorded By:
+  - <기록자>
+- Recorded At:
+  - <기록 시각>
+
+## Feedback Handoff
+- Observation Summary:
+  - <운영 관찰 사실 요약 또는 없음>
+- Discovery Input:
+  - 전략 모듈(orb-v1) Discovery — REQ-029 CHG-04 소비 참고 사항 입력.
+- REQ Input:
+  - <후속 req 후보>
+- Change Request Input:
+  - REQ-030 옵션 D 활성화(portfolio-hub#8 배포 후) — cash/position `*_after` 갱신.
+  - 전략 필드 실데이터 채움(2번째 전략 도입 시) — REQ-027/REQ-029 연계.