portfolio-hub/docs/srs/Migration/req-009_v1-api-db-schema-migration.md

req-009: v1 API 지원을 위한 DB 스키마 migration 추가

• Status: Implemented
• Type: Migration
• Priority: High
• Owner: repository-maintainers

Intent

• dcy-002에서 요구하는 4개 DB 변경(portfolios.market 컬럼, auth_tokens.runtime_id 컬럼, broker_credentials 테이블, ledger_trades 테이블)을 Alembic revision으로 구현한다.
• IF NOT EXISTS 패턴을 유지해 REQ-002 정책을 준수한다(NFR-4).

Requirement

• 다음 스키마 변경을 IF NOT EXISTS 패턴을 사용하는 신규 Alembic migration으로 추가해야 한다.
  1. portfolios 테이블에 market TEXT NULLABLE 컬럼 추가 (기존 행은 NULL로 유지)
  2. auth_tokens 테이블에 runtime_id TEXT UNIQUE NULLABLE 컬럼 추가
  3. broker_credentials 테이블 신규 생성 (user_id, broker, account_ref, encrypted_payload, credential_version, last_rotated_at 포함)
  4. ledger_trades 테이블 신규 생성 (ledger_entry_id PK, asset_id, order_id, execution_id, side, quantity, price, fee_amount, tax_amount, executed_at, recorded_at 포함, (asset_id, order_id, execution_id) unique constraint 포함)

Acceptance Criteria

1. Given alembic upgrade head 실행 후, When portfolios 테이블을 조회하면, Then market TEXT NULLABLE 컬럼이 존재해야 한다.
2. Given alembic upgrade head 실행 후, When auth_tokens 테이블을 조회하면, Then runtime_id TEXT NULLABLE UNIQUE 컬럼이 존재해야 한다.
3. Given alembic upgrade head 실행 후, Then broker_credentials 테이블이 존재해야 한다.
4. Given alembic upgrade head 실행 후, Then ledger_trades 테이블이 존재해야 한다.
5. Given (asset_id, order_id, execution_id) 동일 조합으로 ledger_trades에 두 번 삽입 시, Then UniqueViolation이 발생해야 한다.
6. Given migration을 이미 실행한 DB에 동일 migration을 재실행하면, Then 에러 없이 완료되어야 한다(IF NOT EXISTS 보장).
7. Given portfolios 테이블의 기존 행, When migration 실행 후 조회하면, Then market 값이 NULL이어야 한다(기존 데이터 보정 없음, DECIDE_MARKET_DEFAULT Answered).

Impacted Area

• Docs: docs/data-model.md (REQ-011에서 갱신 예정)
• Modules: migrations/versions/ (신규 migration 파일 추가), app/domain/models.py (Portfolio.market, AuthToken.runtime_id, BrokerCredential, LedgerTrade 모델 필드 추가), app/repositories/postgres.py (신규 테이블 쿼리 추가)
• Tests: tests/test_app.py 또는 migration 검증 테스트

Notes

• NFR-4(IF NOT EXISTS 패턴) 준수 — REQ-002 Alembic migration 정책 기반.
• broker_credentials 테이블의 encrypted_payload 컬럼은 Fernet 암호화된 ciphertext를 TEXT로 저장한다. 암복호화 로직은 REQ-010 참조.
• 컬럼 상세 타입(NUMERIC vs FLOAT, TIMESTAMPTZ 등)은 설계 단계(draft-batch-design)에서 확정한다.
• migration revision ID는 구현 시 기존 chain의 마지막 revision(20260423_0013)을 down_revision으로 참조한다.
• Source Discovery: dcy-002 (영향 범위, NFR-4, DECIDE_MARKET_DEFAULT)

Change Log

CHG-20260511-01

• Date: 2026-05-11
• Author: repository-maintainers

Change Summary

• Implemented 전환 — BAT-001 re-verified verification passed, confirm-req-implemented 게이트 통과

Intent

• BAT-001 verification.md (re-verified, 2026-05-03) AC-1~7 모두 코드 검토 PASS. DB 환경 실행 미확인은 non-blocker로 처리됨 (revision에 IF NOT EXISTS 패턴 전체 적용 확인). Blocking Issues 없음.

Acceptance Criteria Delta

• none

Impacted Area Delta

• none

Delivery Trace Delta

• Batches: BAT-001 (release-candidate)
• Releases: none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: implemented
• Follow-up Action: draft-release (BAT-001); 배포 전 Docker Compose 환경에서 실제 migration 실행 검증 권장

Validation Plan

• BAT-001 verification.md (re-verified) AC-1~7 코드 검토 evidence 연결 확인 완료

CHG-20260502-02

• Date: 2026-05-02
• Author: repository-maintainers

Change Summary

• REQ-009 confirm-req 승인 전환 (Status: Proposed → Approved)

Intent

• 필수 필드(Status, Type, Priority, Owner, Intent, Requirement, Acceptance Criteria 7개, Impacted Area, Change Log) 모두 충족 확인 후 승인

Acceptance Criteria Delta

• No change

Impacted Area Delta

• No change

Delivery Trace Delta

• Batches:
  • none
• Releases:
  • none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: suggest-batch-reqs → draft-batch

CHG-20260502-01

• Date: 2026-05-02
• Author: repository-maintainers

Change Summary

• REQ-009 최초 생성 (source Discovery: dcy-002)

Intent

• v1 API 지원에 필요한 DB 스키마 변경을 REQ backlog로 정규화

Acceptance Criteria Delta

• Added:
  • 전체 Acceptance Criteria 신규 작성

Impacted Area Delta

• Docs:
  • docs/data-model.md (REQ-011에서 갱신 예정)
• Modules:
  • migrations/versions/ 신규 migration 파일
  • app/domain/models.py 모델 필드 추가
• Tests:
  • migration 검증 테스트

Delivery Trace Delta

• Batches:
  • none
• Releases:
  • none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: confirm-req 후 batch 배정. REQ-005, REQ-006, REQ-007, REQ-008과 함께 delivery 단위 구성 필수(runtime_id, market, broker_credentials, ledger_trades 모두 이 migration에 의존).