From d30e915b75df3b44258cac04a60ce2baad9857f1 Mon Sep 17 00:00:00 2001 From: Justin Ko Date: Fri, 12 Jun 2026 22:32:30 +0900 Subject: [PATCH] =?UTF-8?q?docs(rel-007):=20draft=20=E2=80=94=20slots=20RP?= =?UTF-8?q?C=20=EA=B0=9C=EC=84=A0=20+=20=EB=A7=A4=EB=8F=84=EC=84=B8=20?= =?UTF-8?q?=EC=A0=95=EC=A0=95=20+=20paper=20seq=20+=20=EC=A4=91=EC=9E=A5?= =?UTF-8?q?=EA=B8=B0=20=ED=94=84=EB=A1=9C=ED=8C=8C=EC=9D=BC=20(BAT-037~041?= =?UTF-8?q?)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit BAT-037: available_slots capacity hint (REQ-073 CHG) BAT-038: 매도 증권거래세 누락 수정 (REQ-018 CHG, issue #24) BAT-039: paper order seq Redis 영속화 (REQ-011 CHG, issue #4) BAT-040: slots RPC DB-level status 필터 (REQ-002/006/073 CHG, issue #25) BAT-041: watchdog TOML + 중장기 인스턴스 운영 프로파일 (REQ-076/077/078, dcy-027) Co-Authored-By: Claude Sonnet 4.6 --- docs/releases/index.md | 3 +- ...7_20260612_slots-rpc-fee-paper-longterm.md | 116 ++++++++++++++++++ 2 files changed, 118 insertions(+), 1 deletion(-) create mode 100644 docs/releases/rel-007_20260612_slots-rpc-fee-paper-longterm.md diff --git a/docs/releases/index.md b/docs/releases/index.md index 867e63e..2ab1c65 100644 --- a/docs/releases/index.md +++ b/docs/releases/index.md @@ -13,4 +13,5 @@ | REL-003 | app-service | feedback-captured | BAT-010, BAT-011, BAT-012, BAT-013 | dcy-007 (자율 안전 매도) + dcy-008 (kill-switch) + dcy-009 (다중 인스턴스 토폴로지) — 통합 릴리즈 | [rel-003](rel-003_20260607_safety-killswitch-multi-instance.md) | | REL-004 | app-service | feedback-captured | BAT-014, BAT-015, BAT-016, BAT-017, BAT-018, BAT-019, BAT-020, BAT-021, BAT-022, BAT-023 | dcy-010 (safety-sell 쿨다운) + dcy-011~017 (buy/sell 계약·KIS 취소·trading_date TZ·ledger 백오프 버그픽스 + 운영자 CLI + 워치독 가시화) + dcy-016 후속(슬롯 상태 가시화) + dcy-018 (ledger 현금/포지션 write-back, option D) — 통합 릴리즈 | [rel-004](rel-004_20260608_safety-cooldown-bugfix-hardening-cli.md) | | 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 | confirmed | 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-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 | draft | 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) | diff --git a/docs/releases/rel-007_20260612_slots-rpc-fee-paper-longterm.md b/docs/releases/rel-007_20260612_slots-rpc-fee-paper-longterm.md new file mode 100644 index 0000000..d1d7872 --- /dev/null +++ b/docs/releases/rel-007_20260612_slots-rpc-fee-paper-longterm.md @@ -0,0 +1,116 @@ +# REL-007: slots RPC 개선 + 매도세 정정 + paper seq 영속화 + 중장기 인스턴스 프로파일 통합 릴리즈 + +- Status: draft +- Profile: app-service +- Included Batch: BAT-037, BAT-038, BAT-039, BAT-040, BAT-041 + +## Scope + +- Included: + - BAT-037 (dcy-025 REQ-073 CHG-20260612-01): `trex.slots.req` 응답에 `available_slots: int|null` capacity hint 추가. `max_active_slots` 미설정 시 `null`, 설정 시 `max(0, M − active)`. orb-v1 의 불필요한 intent 왕복 제거. AC-3 반전(포함), AC-6 신규. + - BAT-038 (dcy-026 REQ-018 CHG-20260612-01): 매도 체결 `tax=0.0` 하드코딩 버그(issue #24) 수정. `calculate_tax(side, amount)` 신규, 수수료율(`TREX_KIS_FEE_BPS`=1.5)·세율(`TREX_KRX_TAX_SELL_BPS`=20.0) env 상수화. KIS 어댑터는 브로커 응답 fee/tax 정본 우선, 없으면 정책 폴백. + - BAT-039 (issue #4 REQ-011 CHG-20260612-01): paper 브로커 order seq Redis 영속화. 재시작 시 `PAPER-000001` 재발번 → `correlation_id` 충돌 → 매도 원장 조용히 누락되는 결정성 버그 해소. optional `SeqStore` 포트(Redis INCR / in-memory 폴백), `TREX_PAPER_REDIS_URL` 설정. + - BAT-040 (issue #25 REQ-002/006/073 CHG-20260612-01/02): `trex.slots.req` per-request full scan 제거. `list_slots(status_filter)` DB 레벨 `status = ANY(%s)` 필터 추가(포트 + PG 구현). watchdog 갱신 holding 조회는 응답 결과 재사용해 두 번째 커넥션 생략. RPC 계약(AC-1~6) 불변. + - BAT-041 (dcy-027 REQ-076/077/078): 중장기 인스턴스 운영 토대 완성. `DaemonInstanceConfig.watchdog_timeout_sec`(TOML) per-instance timeout 노출(env 폴백), `config/longterm.example.toml` 표준 프로파일 레시피(safety_sell off·market-close 미설정·watchdog 1800s), baseline 문서(`runtime-flows.md`) 중장기 운영 흐름 + 보호 규칙 경계(전략 모듈 전적 책임 + CLI exit 백스톱) + `forced_close_at` 중장기 미사용 명시. +- Excluded: + - 과거 누락 원장 행 소급 보정 (BAT-038/039 공통 — 보정 안 함) + - overlay(paused/warned) 서버측 필터 — 후속 + - watchdog 소유권 진입 외부 알림(슬랙·이메일) — 후속 Discovery + - 중장기 보호 규칙 코어 구현 — 전략 모듈 전적 책임으로 확정(dcy-027 OQ-2) + +## Rollout Plan + +1. 실행 중인 데몬 정지: `kill -TERM ` (정상 종료 대기, 마지막 로그 `Normal shutdown` 확인) +2. 코드 배포: `git pull` (또는 패키지 업데이트) +3. DB 스키마 변경 없음 — 마이그레이션 불필요 +4. 중장기 인스턴스를 운영 중이라면 per-instance TOML 에 `watchdog_timeout_sec = 1800` 추가 (선택 — 미설정 시 기존 env 폴백 유지) +5. paper 브로커 Redis 영속화를 사용할 경우 `TREX_PAPER_REDIS_URL` 환경 변수 설정 (미설정 시 in-memory 폴백, 재시작 시 seq 리셋) +6. 데몬 재기동: `.venv/bin/trex-core-daemon --config ` +7. 기동 후 slots RPC 응답 및 로그 확인 + +## Rollback Plan + +- 트리거 조건: 기동 실패, slots RPC 응답 이상, 브로커 체결 이상 +- 롤백 절차: + 1. 데몬 정지 + 2. `git revert` 또는 이전 커밋으로 체크아웃 후 재기동 + 3. DB 스키마 변경 없으므로 데이터 무손실 롤백 가능 +- 주의: 과거 paper seq 가 Redis 에 저장된 경우 롤백 후 seq 연속성은 깨질 수 있으나 기능 무영향 (seq 는 execution_id 고유성 보장용) + +## Verification Checklist + +### 배포 전 +- [ ] `pytest tests/` — 전체 통과 확인 (회귀 없음) +- [ ] BAT-037~041 각 `verification.md` Status: confirmed 확인 + +### 배포 후 +- [ ] 데몬 기동 로그 정상 (`Normal startup`, 워커 스레드 4개, RabbitMQ 토폴로지 선언) +- [ ] `trex.slots.req` 응답에 `available_slots` 필드 존재 확인 (BAT-037) +- [ ] `filter=inactive` 요청 시 inactive 슬롯만 반환 확인 (BAT-040 회귀) +- [ ] paper 브로커 매도 체결 후 ledger `tax > 0` 확인 (BAT-038) +- [ ] paper 브로커 `TREX_PAPER_REDIS_URL` 설정 시 재시작 후 seq 연속성 확인 (BAT-039) +- [ ] 중장기 TOML(`longterm.example.toml` 참고) 로 기동 시 `safety_sell_enabled=false` + `watchdog_timeout_sec` 반영 확인 (BAT-041) +- [ ] 기존 당일 인스턴스 동작 무회귀 확인 + +## Release Execution Evidence + +- Release Status Transition Target: released + +### Deployment Facts + +- Executed At: + - TBD +- Completed At: + - TBD +- Environment: + - TBD +- Operator: + - Justin Ko +- Revision or Artifact: + - TBD +- Commands or Procedure: + - TBD + +### Profile-Specific Checks + +- app-service: + - Health Endpoint: + - TBD + - Startup Log Fields: + - TBD + - Request Log Fields: + - TBD + - Smoke or Manual Verification: + - TBD + +### Rollback Outcome + +- Rollback Required: + - TBD +- Rollback Trigger: + - TBD +- Rollback Action: + - TBD + +### Release Decision Evidence + +- Released Decision: + - TBD +- Rationale: + - TBD +- Recorded By: + - Justin Ko +- Recorded At: + - TBD + +## Feedback Handoff + +- Observation Summary: + - none +- Discovery Input: + - watchdog 소유권 진입 시 외부 알림(슬랙·이메일·웹훅) — dcy-027 OQ-3 후속 Discovery 명시 + - 전략↔자산 할당 모델(다중 전략 per-instance, strategy 필드 복원) — dcy-025 Out of Scope 이월 +- REQ Input: + - none +- Change Request Input: + - none