feat: BAT-025 add portfolio ledger manual metadata migration

2026-07-15 17:58:18 +09:00
parent 600375beca
commit 1909caa22c
4 changed files with 407 additions and 0 deletions
@@ -0,0 +1,48 @@
+# 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`