# BAT-025 — portfolio_ledger 명시 Alembic migration

- Batch ID: BAT-025
- Profile: standard
- Status: release-candidate
- 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

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

## DoD

- [x] confirmed planning/design 문서 local main commit (`600375b`)
- [x] dev-impl의 migration/code/test/runbook commit (`f6195ff`, remediation `779d6f7`)
- [x] dev-qc 독립 diff review 및 test rerun PASS (`deleg_6b805aa0`)
- [x] lead verification confirmation evidence 기록 (2026-07-15)
- [x] M5 Release 미착수 — 별도 release approval 전 운영 migration/deploy/service activation 금지

## 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](./planning.md)
- Design: [design.md](./design.md)
- Implementation: [implementation.md](./implementation.md) (dev-impl 산출)
- Verification: [verification.md](./verification.md) (dev-qc/lead 산출)