portfolio-hub/docs/srs/Migration/req-033_ledger-trades-asset-id-to-portfolio-id-rename.md

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/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 측정