trex-core/docs/srs/Data/req-074_merged-slot-row-schema.md

req-074: 슬롯 단일 행 스키마 — 자산·워치독·overlay 흡수 + 필드별 정본 라벨

• Status: Implemented
• Type: Data
• Priority: High
• Owner: project maintainers

Intent

• trex.slots.req(REQ-073) 응답의 슬롯 행 하나가 슬롯 상태·자산 데이터·워치독·overlay 를 모두 운반해 소비자 측 배열 조인(assets[]/watchdog[])을 없앤다. 각 필드의 정본 출처(hub/슬롯·코어/워치독/overlay)를 계약에 라벨해 divergence 시 어느 값을 믿을지 모호하지 않게 한다. (dcy-025 FR-3, OQ-3 (a))

Requirement

• slots[] 각 행은 아래 필드를 운반한다(필드별 정본 출처 명시):
  • 슬롯/코어 정본: slot_id, status(inactive/pending_buy/holding/pending_sell/error), portfolio_id, symbol, avg_price, limit_price, forced_close_at(+기존 슬롯 행 필드 유지)
  • 수량(REQ-062 정합, 둘 다 노출): asset_quantity(hub 정본 — 전략 reasoning primary) + qty(슬롯 미러 — 코어 confirmed local). 정상 시 일치하며, 어긋나면 warned=true 로 표면화한다. 라이브 브로커 잔고는 행에 포함하지 않는다(청산/reconcile 시점 정본 — REQ-062).
  • 현금(hub 정본): cash_balance + cash_estimated(bool, dcy-018 추정 현금 오버레이)
  • 워치독(WatchdogStore): watchdog: {expired: bool, last_seen: ISO-8601|null} nested object — 기존 응답 top-level watchdog[] 배열은 폐기(REQ-073).
  • overlay 플래그(직교 축): paused(PauseStore), warned(reconcile/REQ-031·062) — status 와 독립이며 항상 노출(서버측 overlay 필터는 후속).
• strategy 계열 필드(strategy_id/sell_strategy_id/strategy_params/active_strategy_id)는 행에 포함하지 않는다(REQ-073, dcy-025 OQ-4 — 후속 discovery 확정 시 additive 재도입).
• docs/interface-contract.md 에 각 필드의 정본 출처(hub / 슬롯·코어 / 브로커(행 미포함) / watchdog / overlay)를 표로 명시한다(REQ-075).

Acceptance Criteria

1. Given holding 자산 슬롯, When trex.slots.req 조회, Then 행에 슬롯 상태(slot_id/status/avg_price/limit_price/forced_close_at)·자산(symbol/portfolio_id/cash_balance/asset_quantity)·qty 미러·watchdog:{expired,last_seen}·paused/warned 가 모두 포함된다(별도 배열 조인 불요).
2. Given hub asset_quantity 와 슬롯 미러 qty 가 어긋난 자산, When 조회, Then 두 값이 그대로 노출되고 warned=true 다(조용한 자동 교정·숨김 없음).
3. Given 추정 현금 구간(dcy-018), When 조회, Then cash_balance 와 cash_estimated=true 가 함께 노출되고 권위값 수렴 시 cash_estimated=false 로 돌아온다.
4. Given paused 처리된 holding 자산, When filter=holding 조회, Then 행이 반환되며 paused=true 플래그로 표시된다(필터는 status, overlay 는 플래그 — 직교).
5. Given 행 스키마, When 키 검사, Then strategy 계열 필드가 없다.

Impacted Area

• Docs: docs/interface-contract.md(행 스키마 + 정본 라벨 표 — REQ-075), docs/data-model.md(노출 스키마 참조)
• Modules: trex_core/application/portfolio.py(slot_to_dict 확장 — 자산·워치독·overlay 병합), trex_core/application/messaging_handlers.py(_attach_watchdog 제거·행 흡수)
• Tests: tests/application/(행 필드·정본·divergence·overlay 플래그)

Notes

• 수량 정본 모델은 REQ-062(hub 정본 + 슬롯 미러 + 브로커 ground truth)를 그대로 따른다 — 본 REQ 는 그 정본을 행에 표현·라벨하는 계약이다.
• NFR-2(단일 표면·조인 불필요)는 AC-1 에 흡수.
• 출처: dcy-025 FR-3(OQ-2/3).

Change Log

CHG-20260615-02

• Date: 2026-06-15
• Author: Justin Ko
• Type: status
• Summary: Approved → Implemented (confirm-req-implemented, BAT-042). 신규 AC-6(strategy_state 맵+occupancy_seq 행 필드) 구현·검증 완료 — slot_to_dict occupancy_seq + 핸들러 strategy_state 조립, tests/application/test_slots_handler_strategy_state.py(row 단언). 기존 AC-1~5 불변. 479 passed, ruff clean. Implemented 복귀.

CHG-20260615-01

• Date: 2026-06-15
• Author: Justin Ko

Change Summary

• (change-req, dcy-028/issue #26 C-1) 슬롯 행 스키마에 두 additive 필드를 추가한다: strategy_state({<strategy_id>: {version,data,updated_at}} opaque 맵 — 별도 slot_strategy_state 테이블(REQ-079)에서 조립, 미보유 시 omit/{})과 occupancy_seq(int — 슬롯 행 컬럼, REQ-081 점유 가드). 기존 필드(슬롯/자산/워치독/overlay 정본)·divergence·overlay 동작은 불변. AC-5 의 "strategy 계열 필드 없음"은 strategy_* reasoning 필드(strategy_id/sell_strategy_id/params/active)를 가리키며, strategy_state(opaque 상태 맵)는 그와 구분되는 신규 additive 필드다.

Intent

• 전략 opaque 상태와 점유 식별자를 슬롯 행에 노출해 read piggyback(C-1)과 write CAS 점유 가드(REQ-080)를 지원.

Acceptance Criteria Delta

• Added:
  • AC-6(신규): 행에 strategy_state 맵(보유 시)과 occupancy_seq(int)가 포함된다. strategy_state 는 별도 테이블 조립, occupancy_seq 는 슬롯 행 컬럼. strategy_* reasoning 필드 부재 유지(AC-5 정합).
• Updated:
  • AC-5: 제외되는 "strategy 계열"을 strategy_* reasoning 필드로 한정하고 strategy_state/occupancy_seq additive 필드는 허용함을 명확화.
• Removed: 없음

Impacted Area Delta

• Docs: docs/interface-contract.md(strategy_state·occupancy_seq 행 필드 + 정본 라벨 — REQ-082), docs/data-model.md
• Modules: trex_core/application/portfolio.py(slot_to_dict — strategy_state 맵·occupancy_seq 병합)
• Tests: tests/application/(행 strategy_state 맵·occupancy_seq 단언)

Delivery Trace Delta

• Batches: BAT-035(dcy-025) 불변 — 신규 AC-6 은 dcy-028 batch 에서 구현·검증.
• Releases: REL-006(REQ-074 released) — 기존 계약 영향 없음(additive). 신규 필드는 dcy-028 batch.

Revalidation Impact

• Reverification Needed: yes (신규 AC-6 만)
• Existing Implementation Invalidated: no (기존 행 필드/divergence/overlay 보존)
• Status Recommendation: revert-to-approved (Implemented → Approved — 신규 additive AC 구현·검증 대기, 선례 REQ-002/006 CHG-20260612)
• Follow-up Action: confirm-req → dcy-028 batch 에서 REQ-073/079/081 과 함께 구현·검증 → confirm-req-implemented

Validation Plan

• slot_to_dict 테스트: 행에 strategy_state 맵(보유/미보유)·occupancy_seq 포함, 기존 필드/divergence/overlay 회귀.

CHG-20260611-01

• Date: 2026-06-11
• Author: Justin Ko

Change Summary

• dcy-025 FR-3(OQ-3 (a)) 로부터 최초 생성(Proposed). 슬롯 단일 행 스키마(자산·워치독·overlay 흡수 + hub 정본/슬롯 미러 둘 다 노출 + 정본 라벨).

Intent

• 병렬 배열 조인 제거 + 필드별 정본 명확화.

Acceptance Criteria Delta

• Added:
  • AC-1~5 신규
• Updated/Removed: none

Impacted Area Delta

• Docs: interface-contract/data-model
• Modules: portfolio.py(slot_to_dict)/messaging_handlers.py
• Tests: 행 스키마/divergence/overlay

Delivery Trace Delta

• Batches: none(승인 후 draft-batch)
• Releases: none

Revalidation Impact

• Reverification Needed: no(신규)
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current(Proposed)
• Follow-up Action: confirm-req

Validation Plan

• 신규 batch: 행 필드 단언, qty↔asset_quantity divergence+warned, cash_estimated 수렴, paused holding 직교, strategy 필드 부재.