# 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 필드 부재.