docs(req-058): CHG-20260611-01 — symbol 누락 수정 change-req 반영

reconcile_universe 슬롯 생성 시 symbol 미저장 구현 누락을 AC-5로 추가.
Implemented 상태 유지 (기존 AC 1~4 evidence 유효).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-06-11 21:12:38 +09:00
co-authored by Claude Sonnet 4.6
parent 24a6017457
commit 808a851d39
2 changed files with 43 additions and 2 deletions
@@ -9,13 +9,14 @@
- 슬롯 집합을 portfolio-hub universe 의 projection 으로 유지하기 위해, universe fetch 결과로 슬롯을 생성/은퇴하는 reconcile 경로를 정의한다. 일일 preallocation(dcy-014)을 폐기하고 universe 동기화로 대체한다. (dcy-020 FR-1/OQ-2/NFR-3)
## Requirement
- 스냅샷 refresh(`get_portfolios` 성공 직후)에 슬롯 reconcile 을 수행한다: (1) universe 신규 자산 → 영구 슬롯 즉시 생성(비활성·멱등, `UNIQUE(instance_key, portfolio_id)`); (2) universe 제거 + 슬롯 비활성(holding/pending 아님) → **soft-retire**(`retired_at` 마킹, 행 보존, hard delete 금지); (3) universe 제거 + 보유 중/pending → **tombstone**(은퇴 보류, safety-sell/watchdog 유지, 신규 매수 후보 제외, 닫힌 뒤 은퇴). reconcile 쓰기는 인스턴스 스코프 advisory lock 안에서 단일 writer 로 수행한다. cadence 는 기존 부팅 + 일 1회 + 운영자 on-demand. portfolio-hub 불가/degraded 또는 universe N→0/급격 대량 감소면 생성·은퇴를 보류하고 경고한다.
- 스냅샷 refresh(`get_portfolios` 성공 직후)에 슬롯 reconcile 을 수행한다: (1) universe 신규 자산 → 영구 슬롯 즉시 생성(비활성·멱등, `UNIQUE(instance_key, portfolio_id)`), 이 때 `PortfolioItem.symbol` 을 슬롯의 `symbol` 컬럼에 함께 저장한다; (2) universe 제거 + 슬롯 비활성(holding/pending 아님) → **soft-retire**(`retired_at` 마킹, 행 보존, hard delete 금지); (3) universe 제거 + 보유 중/pending → **tombstone**(은퇴 보류, safety-sell/watchdog 유지, 신규 매수 후보 제외, 닫힌 뒤 은퇴). reconcile 쓰기는 인스턴스 스코프 advisory lock 안에서 단일 writer 로 수행한다. cadence 는 기존 부팅 + 일 1회 + 운영자 on-demand. portfolio-hub 불가/degraded 또는 universe N→0/급격 대량 감소면 생성·은퇴를 보류하고 경고한다. `symbol IS NULL` 인 기존 슬롯은 다음 reconcile 시 backfill 한다.
## Acceptance Criteria
1. Given universe 에 신규 자산, When reconcile, Then 그 자산의 영구 슬롯이 비활성으로 생성되고 재실행해도 중복 생성되지 않는다(멱등).
2. Given universe 에서 빠진 비활성 슬롯, When reconcile, Then soft-retire(`retired_at` set, 행 보존)되고, 같은 자산이 재등장하면 동일 슬롯이 재활성화된다.
3. Given universe 에서 빠졌으나 holding/pending 인 슬롯, When reconcile, Then 은퇴되지 않고 tombstone(신규 매수 제외·safety-sell 유지)되며, 매도 체결 후에야 은퇴된다.
4. Given portfolio-hub degraded 또는 universe 가 N→0, When reconcile, Then 슬롯 생성·은퇴가 보류되고 마지막 집합이 유지되며 경고가 남는다.
5. Given reconcile 실행, When 슬롯 생성, Then `daily_slot.symbol` 이 `PortfolioItem.symbol` 값으로 채워진다. Given 기존 슬롯의 `symbol` 이 NULL, When reconcile, Then 해당 슬롯의 `symbol` 이 backfill 된다.
## Impacted Area
- Docs: docs/runtime-flows.md(reconcile lifecycle)
@@ -87,6 +88,46 @@
#### Validation Plan
- 승인 후 batch planning 에서 본 REQ AC 를 검증 기준으로 사용.
### CHG-20260611-01
- Date: 2026-06-11
- Author: Justin Ko
#### Change Summary
- `reconcile_universe` 가 슬롯 생성 시 `symbol` 을 저장하지 않던 구현 누락 수정. `PortfolioItem.symbol` 이 슬롯 INSERT 에 포함되도록 시그니처를 `set[str]` → `dict[str, str]` (portfolio_id → symbol) 로 변경. 기존 `symbol IS NULL` 슬롯을 다음 reconcile 시 자동 backfill 하는 로직 추가.
#### Intent
- 슬롯 생성 시 symbol 이 누락되어 집행 루프에서 심볼을 조회할 수 없는 상태가 발생. `reconcile_universe` 인터페이스가 portfolio_id 집합만 전달하고 symbol 을 버리는 구조적 누락이었음.
#### Acceptance Criteria Delta
- Added:
- AC-5: 슬롯 생성 시 `symbol` 컬럼이 `PortfolioItem.symbol` 로 채워진다. 기존 `symbol IS NULL` 슬롯은 다음 reconcile 시 backfill 된다.
- Updated:
- Requirement 본문에 "(이 때 `PortfolioItem.symbol` 을 슬롯의 `symbol` 컬럼에 함께 저장한다)" 및 backfill 조건 추가.
- Removed: 없음
#### Impacted Area Delta
- Modules:
- `trex_core/application/snapshot_scheduler.py` — `_reconcile_slots`: `set` → `dict` comprehension
- `trex_core/domain/slot/repository.py` — `reconcile_universe` 시그니처
- `trex_core/domain/slot/in_memory_repository.py` — 생성 시 symbol 전달 + backfill
- `trex_core/adapters/persistence/postgresql.py` — INSERT에 symbol 추가 + backfill UPDATE
- Tests: 29개 테스트 파일 `reconcile_universe` 호출부 `set` → `dict` 일괄 갱신 (420 passed)
- Docs: 없음 (runtime-flows.md 는 reconcile lifecycle 자체 변경 없음)
#### Delivery Trace Delta
- Batches: BAT-028(구현 근거), BAT-030(e2e 검증 근거) — 기존 evidence 유효, 신규 AC-5 는 커밋 24a6017 으로 검증
- Releases: rel-006 배포 후 운영 중 발견(슬롯 symbol NULL 확인) — 핫픽스 아닌 즉시 수정
#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no (AC 1~4 는 기존 evidence 그대로 유효)
- Status Recommendation: keep-current (Implemented)
- Follow-up Action: 없음. 420개 테스트 통과 + DB 확인(23개 슬롯 전부 symbol 채움)으로 AC-5 검증 완료.
#### Validation Plan
- `reconcile_universe` 호출 후 생성된 슬롯의 `symbol` 이 NULL 이 아닌지 단위 테스트 확인.
- 기존 `symbol IS NULL` 슬롯 보유 DB 에서 데몬 재시작 후 전 슬롯 symbol 채움 확인 (test 인스턴스 23/23 confirmed).
### CHG-20260610-IMPL
- Date: 2026-06-10
- Author: Justin Ko