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

BAT-025 Implementation Log

• Date: 2026-07-15
• Assignee: dev-impl
• Scope: REQ-057 portfolio_ledger 수동 장부 메타데이터 명시 Alembic migration

Implemented Changes

1. Created new Alembic revision 20260715_0028 (migrations/versions/20260715_0028_portfolio_ledger_manual_metadata.py)

   • down_revision: 20260628_0027
   • Added additive columns:
     • source TEXT NOT NULL DEFAULT 'broker'
     • target_ledger_entry_id BIGINT NULL
     • confirmation_evidence TEXT NULL
     • actor_user_id TEXT NULL
   • Added idempotent runtime compatibility logic:
     • If portfolio_ledger table missing: no-op
     • If column already exists: update source IS NULL → 'broker', enforce NOT NULL + DEFAULT
     • Add missing columns only when absent
   • downgrade is forward-only no-op

2. Added migration-focused tests tests/test_bat025_portfolio_ledger_manual_metadata_migration.py

   • Covers:
     • fresh schema add-all-columns behavior
     • precreated schema backfill + source constraint enforcement
     • missing table no-op
     • forward-only downgrade no-op

3. Added operational runbook

   • docs/runbooks/bat-025-req057-portfolio-ledger-manual-metadata-runbook.md

Preflight Evidence

• uv run alembic heads
  • output: 20260715_0028 (head)
• uv run alembic history --verbose
  • confirms 20260715_0028 parent is 20260628_0027 and it is the current tail of the migration chain.
• PYTHONPATH=. uv run pytest -q -o addopts='' tests/test_bat025_portfolio_ledger_manual_metadata_migration.py
  • output: 4 passed in 0.24s

Evidence notes

• Migration is idempotent by design: no-op if portfolio_ledger is missing, and for pre-created runtimes it backfills source and enforces NOT NULL DEFAULT 'broker'.
• No DB upgrade was executed in this scope (code-only + evidence-only in repo).

Commit

• Commit SHA: 850e970