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

BAT-025 Planning

Objective

REQ-057의 명시 Alembic migration과 운영 runbook을 구현·검증한다. BAT-024의 API 계약과 Implemented 상태는 변경하지 않는다.

Delivery sequence

1. Preflight — uv run alembic heads, uv run alembic history, revision graph 및 ensure_schema() DDL 소유 경계를 확인하고 실제 head를 evidence로 고정한다.
2. Migration — 실제 head를 parent로 하는 신규 revision을 작성한다. fresh/기존/runtime-precreated schema에서 중복 DDL 없이 네 컬럼, source backfill, NOT NULL/default를 보장한다.
3. Runtime compatibility — ensure_schema() 선행 생성 경로와 Alembic version tracking의 상호작용을 테스트한다. 임의 stamp는 schema/version evidence와 승인된 절차 없이 사용하지 않는다.
4. Regression tests — 기존 broker ledger write, manual ledger API, row/data preservation, schema metadata/current 정합을 검증한다.
5. Runbook — backup, current, schema/row count, active query/lock, upgrade, post-check, smoke, 실패 대응 및 forward-only recovery를 문서화하고 dry-run 검토한다.
6. Independent QC — dev-qc가 committed diff를 직접 검토하고 표준 테스트 및 migration-focused 테스트를 재실행한다.

Work packets

WP-1: Batch artifacts (lead)

• 이 문서와 design.md, index.md를 confirmed 상태로 작성한다.
• docs/batches/index.md에 BAT-025를 confirmed로 등록한다.
• local main에 docs-only commit을 남긴다.

WP-2: Implementation (dev-impl)

• 신규 Alembic revision, 필요한 runtime compatibility 수정, tests, docs/runbooks/ runbook을 작성한다.
• implementation log와 실행 명령/결과를 기록하고 implementation commit을 반환한다.
• 운영 DB나 서비스 activation은 실행하지 않는다.

WP-3: QC (dev-qc)

• dev-impl committed diff와 문서/REQ 정합성을 독립 검토한다.
• uv run pytest 및 가능한 migration-focused checks를 재실행한다.
• blocker가 있으면 PASS가 아닌 명시적 finding으로 반환한다.

Acceptance evidence targets

• AC-1: head/graph preflight 출력
• AC-2~5: fresh/legacy/runtime-precreated schema upgrade와 source backfill/중복 오류 부재
• AC-6: alembic current, information_schema, row count 결과
• AC-7~9: runbook preflight/실패 대응/forward-only recovery 검토 evidence
• AC-10: 운영 실행을 하지 않았다는 scope evidence 및 release gate 기록
• AC-11: implementation + tests + QC committed evidence

Risks / blockers

• local repository의 schema graph와 runtime-created schema가 서로 다른 시작 상태를 가질 수 있다.
• ensure_schema()와 Alembic 양쪽 소유 경계 변경은 기존 broker flow 회귀 위험이 있다.
• 실제 PostgreSQL 운영 DB evidence는 이번 batch 밖이며 M5 Release 승인 없이는 확보하지 않는다.