portfolio-hub/docs/batches/bat-025_20260715_portfolio-ledger-alembic-migration/index.md

BAT-025 — portfolio_ledger 명시 Alembic migration

• Batch ID: BAT-025
• Profile: standard
• Status: confirmed
• Discovery: dcy-012_20260714_manual-ledger-write-api-owner-scoped (REQ-057 follow-on)
• Included REQ: REQ-057
• Folder: docs/batches/bat-025_20260715_portfolio-ledger-alembic-migration/
• Created: 2026-07-15

Summary

REQ-056/BAT-024가 사용한 portfolio_ledger additive metadata 네 컬럼을 runtime ensure_schema() 자동 DDL에만 의존하지 않고 명시 Alembic revision으로 추적·검증한다. 기존 broker/manual 데이터 보존, runtime-precreated schema 호환성, 운영 migration runbook 및 독립 QC를 delivery 범위로 둔다.

Scope

• source TEXT NOT NULL DEFAULT 'broker'
• target_ledger_entry_id BIGINT NULL
• confirmation_evidence TEXT NULL
• actor_user_id TEXT NULL
• fresh/기존/runtime-precreated schema migration compatibility
• broker ledger regression 및 manual ledger regression
• backup/preflight/current/schema/lock/smoke/forward-only recovery runbook

DoR

• REQ-057 Approved (Justin Ko)
• REQ-056 Implemented 및 BAT-024 release-candidate 유지 확인
• implementation 시점 alembic heads/graph 재확인 요구사항 확인
• 운영 DB upgrade·service activation은 별도 M5 Release gate로 분리

DoD

• confirmed planning/design 문서 local main commit
• dev-impl의 migration/code/test/runbook commit
• dev-qc 독립 diff review 및 test rerun PASS
• lead verification confirmation evidence 기록
• M5 Release 미착수

Gate / Constraints

• 운영 DB, deploy, service activation, push/merge, credential/account disclosure 금지.
• down migration/column deletion은 운영 rollback 경로로 사용하지 않는다. 복구는 호환 코드 rollback + additive schema 유지의 forward-only 정책이다.
• migration 구현 전 실제 단일 head와 graph를 재확인하고, 결과를 implementation/verification evidence에 기록한다.

Documents

• Planning: planning.md
• Design: design.md
• Implementation: implementation.md (dev-impl 산출)
• Verification: verification.md (dev-qc/lead 산출)