# REQ-036: portfolio_ledger 회계 원장 통합 마이그레이션 (ledger_trades 흡수/DROP)

- Status: Implemented
- Type: Migration
- Priority: High
- Owner: Justin Ko

## Intent
- 두 ledger 테이블(`portfolio_ledger` 회계 원장 + `ledger_trades` broker audit)이 공존하는 구조를 `portfolio_ledger` 단일 회계 원장으로 통합한다(dcy-006 OQ-6 (iv)).
- `ledger_trades`의 broker idempotency/식별 필드를 `portfolio_ledger`에 흡수하고 `ledger_trades` 테이블을 삭제해, 신 path(`POST /v1/portfolios/{id}/ledger/trades`)가 단일 회계 원장에 기록할 수 있는 스키마 기반을 마련한다.

## Requirement
- Alembic 신규 revision을 작성한다. (head는 dcy-005 `20260601_0024` 다음)
- `portfolio_ledger`에 컬럼을 추가한다:
  - `ledger_entry_id BIGINT GENERATED BY DEFAULT AS IDENTITY` (CHG-20260605-03: hypertable 제약상 단독 PRIMARY KEY 불가 — Identity 컬럼, 비-PK)
  - `order_id TEXT NULL`, `execution_id TEXT NULL` (dcy-006 OQ-7 (ii): NULL 허용)
  - `side TEXT NOT NULL`
  - `executed_at TIMESTAMPTZ NOT NULL`
- **idempotency는 DB partial UNIQUE index가 아니라 application layer(REQ-037)에서 보장한다** (CHG-20260605-03). `portfolio_ledger`는 TimescaleDB hypertable(파티션 컬럼 `recorded_at`)이라 `(portfolio_id, order_id, execution_id)` partial unique index/PK 생성이 불가능하다(`cannot create a unique index without the column recorded_at`). 따라서 본 마이그레이션은 broker 식별 컬럼만 추가하고 unique 제약은 만들지 않는다. broker write dedup은 REQ-037의 `SELECT ... FOR UPDATE` 락 하 SELECT-before-insert로 처리.
- 수치 컬럼 타입을 DOUBLE PRECISION → NUMERIC(20,8)로 변경한다: `price`, `quantity`, `fee_amount`, `tax_amount`, `cash_balance_after`, `asset_quantity_after`, `total_value_after`, `profit_buffer_after`.
- 기존 `action` 컬럼을 제거하고 `side`로 통일한다. backfill 매핑: `action='BUY'` → `side='buy'`, `action='SELL'` → `side='sell'`. 그 외 자유형식 action 값의 처리(R-6)는 마이그레이션 본문에서 분포 확인 후 결정(개발 워크스페이스는 분포 단순).
- 기존 데이터 backfill: `recorded_at` → `executed_at` 복사, `order_id`/`execution_id`는 NULL(synthetic 생성 불요).
- 추가 인덱스 `idx_portfolio_ledger_portfolio_executed (portfolio_id, executed_at)` 신설. 기존 `idx_portfolio_ledger_portfolio_time (portfolio_id, recorded_at DESC)`은 유지.
- `ledger_trades` 테이블을 DROP한다. (본 워크스페이스 미생성이라 `DROP TABLE IF EXISTS`로 안전 처리. prod 데이터 보존 필요 시 backfill은 release 단계 별도 검토.)
- `app/repositories/postgres.py`의 `ensure_schema()` 내 `portfolio_ledger` 정의도 신 스키마와 동일하게 갱신한다.

## Acceptance Criteria
1. Given 신규 Alembic revision 적용 후, When `\d portfolio_ledger` 확인, Then `ledger_entry_id`(Identity, 비-PK — CHG-20260605-03), `order_id`(NULL 허용), `execution_id`(NULL 허용), `side`(NOT NULL), `executed_at`(NOT NULL) 컬럼이 존재한다.
2. Given AC-1 환경, When `information_schema`로 수치 컬럼 타입 확인, Then `price`/`quantity`/`fee_amount`/`tax_amount`/`cash_balance_after`/`asset_quantity_after`/`total_value_after`/`profit_buffer_after`가 모두 NUMERIC(20,8)이다.
3. (CHG-20260605-03 재정의) Given AC-1 환경, When `portfolio_ledger` 인덱스/제약 확인, Then `(portfolio_id, order_id, execution_id)` 기반 **partial unique index/PK는 존재하지 않는다**(hypertable 제약). broker write idempotency는 REQ-037 application layer에서 보장되며, 실 DB 회귀(`tests/test_ledger_consolidation_integration.py::test_duplicate_broker_write_is_idempotent`)로 검증한다.
4. Given AC-1 환경, When `action` 컬럼 존재 확인, Then `action` 컬럼은 존재하지 않고 `side` 컬럼으로 대체되어 있다.
5. Given AC-1 환경, When `\d ledger_trades` 또는 테이블 목록 조회, Then `ledger_trades` 테이블이 존재하지 않는다.
6. Given 기존 portfolio_ledger 데이터(있는 경우), When 마이그레이션 적용, Then `executed_at`은 `recorded_at` 값으로 채워지고 `order_id`/`execution_id`는 NULL이며 `side`는 기존 action에서 매핑된다.
7. Given `ensure_schema()` 단독 실행, When portfolio_ledger 스키마 확인, Then 마이그레이션과 동일한 컬럼/제약/타입이 반영된다.

## Impacted Area
- Docs:
  - `docs/data-model.md` — `portfolio_ledger` entity에 신규 컬럼(ledger_entry_id Identity 비-PK, order_id/execution_id NULL, side, executed_at) + 정밀도 NUMERIC(20,8) 명세 추가. **idempotency는 application layer(REQ-037)이며 DB partial unique index/PK는 hypertable 제약상 없음**을 명시. `ledger_trades` entity 섹션 제거. 두 ledger 테이블 → 단일 원장 통합 명시.
- Modules:
  - `migrations/versions/` — 신규 revision (예: `20260605_NNNN_portfolio_ledger_consolidation.py`). down_revision = `20260601_0024`.
  - `app/repositories/postgres.py:263-282` — `ensure_schema()` portfolio_ledger 정의 갱신
- Tests:
  - 신규/갱신 마이그레이션 회귀 (alembic upgrade head 후 schema 검증)
  - 기존 `tests/test_v1_portfolios_ledger.py` 등 ledger 의존 테스트가 신 스키마와 정합하도록 갱신 (REQ-037과 연동)

## Notes
- 본 REQ는 dcy-006 FR-9/FR-10/FR-11/FR-12 산출물 + FR-5(data-model.md) 일부 흡수.
- REQ-037(신 path 회계 책임 + 응답)의 선행 — 본 마이그레이션이 스키마 기반을 제공한다.
- idempotency(broker write만 dedup, 레거시 write append-only)는 dcy-006 OQ-7 (ii) 결정이나, hypertable 제약으로 DB partial unique가 불가하여 application layer(REQ-037)에서 구현(CHG-20260605-03).
- R-5(DOUBLE→NUMERIC 정밀도)/R-6(action→side 매핑 누락)/R-7(DROP 트랜잭션)는 prod 마이그레이션 시 별도 검토. 본 워크스페이스는 개발용이라 영향 미미(workspace_purpose 메모리).
- 별도 REL(REL-003 등)로 분리 배포(dcy-006 A-4).
- Source: dcy-006 FR-9~12, OQ-6 (iv), OQ-7 (ii).

## Change Log

### CHG-20260605-04
- Date: 2026-06-05
- Author: Justin Ko

#### Change Summary
- Status: Approved → Implemented

#### Intent
- BAT-016 confirm-batch-verification 완료. portfolio_ledger 통합 마이그레이션 + ensure_schema 갱신 + ledger_trades DROP 구현. AC-1/2/4/5/6/7 검증, AC-3는 CHG-20260605-03 재정의(application-layer idempotency)로 실 DB 통합 테스트(`test_duplicate_broker_write_is_idempotent`)로 검증. 전체 376 passed.

#### Acceptance Criteria Delta
- No change

#### Impacted Area Delta
- No change

#### Delivery Trace Delta
- Batches:
  - BAT-016 (release-candidate)
- Releases:
  - REL-003 (예정)

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: implemented
- Follow-up Action: REL-003 staging에서 fresh-DB alembic 적용 + DOUBLE→NUMERIC 정밀도/action 분포 최종 검증

#### Validation Plan
- 실 DB 통합 테스트 + alembic schema 검증 (완료); prod staging은 release 단계

### CHG-20260605-03
- Date: 2026-06-05
- Author: Justin Ko

#### Change Summary
- AC/Requirement 재정의: `portfolio_ledger`가 TimescaleDB hypertable임이 BAT-016 verify에서 확인되어, dcy-006 OQ-7 (ii)의 "DB partial UNIQUE index + ledger_entry_id PK"가 물리적으로 불가능(`cannot create a unique index without the column recorded_at`). idempotency를 application layer(REQ-037 SELECT-before-insert under FOR UPDATE)로 이관. Status는 Approved 유지(구현 진행 중 설계 정합 보정).

#### Intent
- 설계(DB 제약 idempotency)와 hypertable 현실의 충돌 해소. 마이그레이션은 broker 컬럼만 추가하고 unique 제약/PK는 생성하지 않으며, dedup은 application layer가 담당하도록 정합화.

#### Acceptance Criteria Delta
- Updated:
  - AC-1: `ledger_entry_id(PK)` → `ledger_entry_id(Identity, 비-PK)`
  - AC-3: "partial UNIQUE index 존재" → "partial unique index/PK 미존재(hypertable 제약), idempotency는 REQ-037 application layer + 실 DB 통합 테스트로 검증"

#### Impacted Area Delta
- Modules: 변경 없음(이미 신규 revision + ensure_schema 지정). 마이그레이션 본문에서 partial unique index 생성 제거 반영.
- Tests: `tests/test_ledger_consolidation_integration.py`(실 DB) 추가 — idempotency 검증 이관.

#### Delivery Trace Delta
- Batches: BAT-016 (in-delivery)
- Releases: none (REL-003 등 분리 예정)

#### Revalidation Impact
- Reverification Needed: yes (BAT-016 verification은 실 DB 통합 테스트로 재수행)
- Existing Implementation Invalidated: no (구현이 본 재정의에 맞춰 수정됨)
- Status Recommendation: keep-current (Approved 유지)
- Follow-up Action: BAT-016 verification 실 DB evidence 반영

#### Validation Plan
- alembic schema 검증(AC-1/2/4/5/6/7) + 실 DB idempotency 통합 테스트(AC-3 대체)

### CHG-20260605-02
- Date: 2026-06-05
- Author: Justin Ko

#### Change Summary
- Status: Proposed → Approved

#### Intent
- 승인 게이트 통과: 필수 필드(Status/Type/Priority/Owner/Intent/Requirement/AC/Impacted Area/Change Log) 모두 충족, AC-1~7 구체성(DB schema 검증) 확인 완료, blocker 없음.

#### Acceptance Criteria Delta
- No change

#### Impacted Area Delta
- No change

#### Delivery Trace Delta
- Batches: none (미정)
- Releases: none (미정 — REL-003 등 분리 예정)

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: promote-to-approved
- Follow-up Action: batch 계획 편입 (BAT-016 후보, REQ-037/038 선행)

### CHG-20260605-01
- Date: 2026-06-05
- Author: Justin Ko

#### Change Summary
- 최초 생성 — dcy-006 confirm-discovery 후 draft-req 실행. dcy-006 FR-9~12 산출물.

#### Intent
- portfolio_ledger/ledger_trades 두 ledger 테이블을 portfolio_ledger 단일 회계 원장으로 통합하는 스키마 마이그레이션 정의.

#### Acceptance Criteria Delta
- Added:
  - AC-1~7 최초 작성

#### Impacted Area Delta
- Docs: docs/data-model.md — 최초 지정
- Modules: migrations/versions/, app/repositories/postgres.py — 최초 지정
- Tests: 마이그레이션 회귀, tests/test_v1_portfolios_ledger.py — 최초 지정

#### Delivery Trace Delta
- Batches: none (미정)
- Releases: none (미정 — REL-003 등 분리 예정)

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: keep-current
- Follow-up Action: confirm-req 후 batch 계획 편입; staging에서 DOUBLE→NUMERIC + action→side backfill dry-run

#### Validation Plan
- alembic upgrade head 후 schema 검증(AC-1~7); 개발 DB에서 ensure_schema 정합 확인