From f8c566114708159236beeb919d5f1b9338f8ff8c Mon Sep 17 00:00:00 2001 From: Justin Ko Date: Sat, 6 Jun 2026 11:27:35 +0900 Subject: [PATCH] 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 --- docs/releases/index.md | 1 + ...1_20260606_trex-core-slot-core-baseline.md | 102 ++++++++++++++++++ 2 files changed, 103 insertions(+) create mode 100644 docs/releases/rel-001_20260606_trex-core-slot-core-baseline.md diff --git a/docs/releases/index.md b/docs/releases/index.md index 1b66789..a437591 100644 --- a/docs/releases/index.md +++ b/docs/releases/index.md @@ -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) | diff --git a/docs/releases/rel-001_20260606_trex-core-slot-core-baseline.md b/docs/releases/rel-001_20260606_trex-core-slot-core-baseline.md new file mode 100644 index 0000000..05beccf --- /dev/null +++ b/docs/releases/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: + - + - Startup Log Fields: + - + - Request Log Fields: + - + - Smoke or Manual Verification: + - <배포 후 재실행한 snapshot/pause RPC 검증과 결과> + +### 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: + - 전략 모듈(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 연계.