docs(stagepilot): confirm BAT-025 migration planning and design

2026-07-15 11:02:08 +09:00
parent 7b9c23a377
commit 600375beca
4 changed files with 141 additions and 0 deletions
@@ -0,0 +1,51 @@
+# 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
+
+- [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
+
+- [ ] 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](./planning.md)
+- Design: [design.md](./design.md)
+- Implementation: [implementation.md](./implementation.md) (dev-impl 산출)
+- Verification: [verification.md](./verification.md) (dev-qc/lead 산출)