# REQ-033: ledger_trades.asset_id → portfolio_id 컬럼명 정합화

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

## Intent
- `ledger_trades` 테이블의 `asset_id` 컬럼이 실제로는 portfolio_id를 저장하지만 컬럼명이 의미와 불일치하여 schema reader가 assets 테이블 참조로 오해할 수 있다.
- REQ-029 구현(POST /v1/portfolios/{id}/ledger/trades 이전) 시점의 잔여 명명 정합화를 마무리한다.

## Requirement
- Alembic 신규 revision을 작성해 `ledger_trades.asset_id` 컬럼을 `portfolio_id`로 rename한다(`ALTER TABLE ledger_trades RENAME COLUMN asset_id TO portfolio_id`).
- 기존 데이터는 동일 의미(portfolio_id 저장)이므로 backfill 불요.
- `app/repositories/postgres.py`의 ledger_trades INSERT/SELECT/RETURNING SQL에서 컬럼명을 `portfolio_id`로 갱신한다.
- `app/domain/models.py`의 `LedgerTrade` dataclass에 `asset_id` 필드가 있다면 `portfolio_id`로 rename한다(있는 경우).
- `app/api/v1_portfolios.py` ledger route handler에서 응답에 `asset_id` 노출이 있다면 `portfolio_id`로 정합화한다(있는 경우).
- 마이그레이션 lock 시간을 운영 영향 < 1초로 유지하기 위해 짧은 단일 `ALTER COLUMN RENAME` 트랜잭션으로 처리한다.

## Acceptance Criteria
1. Given 신규 Alembic revision 적용 후, When `\d ledger_trades` 실행, Then `portfolio_id` 컬럼이 존재하고 `asset_id` 컬럼은 존재하지 않는다.
2. Given AC-1 환경, When 기존 `POST /v1/portfolios/{id}/ledger/trades` 호출, Then INSERT/SELECT 회귀 테스트가 모두 통과한다.
3. Given codebase grep `grep -rn "ledger_trades\..*asset_id\|asset_id.*ledger_trades" app/repositories/postgres.py app/domain/models.py app/api/v1_portfolios.py`, When 본 REQ 구현 후, Then 결과는 0건이다.
4. Given 마이그레이션 staging dry-run, When `ALTER COLUMN RENAME` 실행 시간 측정, Then 측정 시간 < 1초 (NFR-1 정합).
5. Given 본 REQ 구현 후 전체 pytest 회귀, When 실행, Then 기존 통과 케이스 모두 유지 + ledger_trades 의존 케이스 통과.

## Impacted Area
- Docs:
  - `docs/data-model.md` — ledger_trades 컬럼 명세에 `portfolio_id` 반영, `asset_id` 표기 제거
  - (선택) `docs/interface-contract.md` — ledger 응답에 `asset_id` 노출이 있다면 `portfolio_id`로 갱신
- Modules:
  - `migrations/versions/` — 신규 revision (예: `20260601_NNNN_ledger_trades_portfolio_id_rename.py`)
  - `app/repositories/postgres.py` — ledger_trades INSERT/SELECT/RETURNING 컬럼명 갱신([app/repositories/postgres.py:1284-1314](../../app/repositories/postgres.py#L1284-L1314))
  - `app/domain/models.py` — `LedgerTrade` dataclass 필드명 (있다면)
  - `app/api/v1_portfolios.py` — ledger route handler 응답 매핑 (있다면)
- Tests:
  - 갱신 `tests/test_v1_portfolios_ledger.py` — 컬럼명 변경 회귀 검증
  - (선택) 신규 마이그레이션 dry-run 회귀

## Notes
- 본 REQ는 dcy-005 FR-1 산출물. 정합화 묶음 trigger.
- 외부 client(trex-basic 등)는 HTTP API(`POST /v1/portfolios/{id}/ledger/trades`)만 호출하므로 DB 컬럼명 의존 없음 추정. 마이그레이션 전 외부 query 의존성 확인.
- 본 REQ는 별도 REL-002로 분리 배포(dcy-005 OQ-3 결정, 2026-06-01).
- Source: dcy-005 FR-1, REQ-029 Notes follow-up.

## Change Log

### CHG-20260601-03
- Date: 2026-06-01
- Author: Justin Ko

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

#### Intent
- BAT-015 confirm-batch-verification 완료(2026-06-05). AC-2/3/5 PASSED, AC-1/4 staging Deferred(blocker 아님). 마이그레이션 + 코드/스키마/도메인/라우트/테스트/문서 정합화 모두 evidence 확보.

#### Acceptance Criteria Delta
- No change

#### Impacted Area Delta
- No change

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

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: implemented
- Follow-up Action: REL-002 staging 시점에 AC-1 (`\d ledger_trades` 컬럼 검증) + AC-4 (마이그레이션 lock < 1초) evidence 수집. 본 워크스페이스 ledger_trades 테이블 미생성 상태 자체는 별도 후속 항목(BAT-011 mock verification 후속) 등록 후보.

### CHG-20260601-02
- Date: 2026-06-01
- Author: Justin Ko

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

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

#### Acceptance Criteria Delta
- No change

#### Impacted Area Delta
- No change

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

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: promote-to-approved
- Follow-up Action: batch 계획 편입 (BAT-015 후보)

### CHG-20260601-01
- Date: 2026-06-01
- Author: Justin Ko

#### Change Summary
- 최초 생성 — dcy-005 confirm-discovery 후 draft-req 실행. dcy-005 FR-1 산출물.

#### Intent
- ledger_trades.asset_id 컬럼명을 의미에 맞게 portfolio_id로 정합화.

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

#### Impacted Area Delta
- Docs: docs/data-model.md, (선택) docs/interface-contract.md — 최초 지정
- Modules: migrations/versions/, app/repositories/postgres.py, app/domain/models.py, app/api/v1_portfolios.py — 최초 지정
- Tests: tests/test_v1_portfolios_ledger.py — 최초 지정

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

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: keep-current
- Follow-up Action: confirm-req 후 batch 계획 편입; staging 환경에서 ALTER COLUMN RENAME dry-run으로 lock 시간 측정

#### Validation Plan
- pytest로 AC-1~5 검증 + staging dry-run AC-4 측정