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,40 @@
+# BAT-025 Design
+
+## D-1. Revision graph and parent
+
+구현 시작 직전 `uv run alembic heads` 및 `uv run alembic history`로 유효 head를 재확인한다. 신규 revision은 그 실제 head 하나를 `down_revision`으로 사용하며, 문서/코드에 20260628_0027을 선결 가정으로 고정하지 않는다.
+
+## D-2. Migration idempotency
+
+신규 revision은 inspector/information_schema 기반으로 table/column 존재를 확인한다.
+
+- `portfolio_ledger`가 정상적으로 존재하는 일반 경로에서는 네 컬럼을 추가한다.
+- runtime `ensure_schema()`가 이미 컬럼을 생성한 경로에서는 컬럼 재생성 없이 nullable/default를 검증·보정한다.
+- `source`는 upgrade 전에 NULL을 `'broker'`로 backfill하고 이후 `NOT NULL DEFAULT 'broker'`를 보장한다.
+- 기존 행은 삭제·재작성하지 않으며 upgrade 전후 row count와 business field를 비교한다.
+- down migration은 운영 forward-only 정책과 충돌하지 않도록 구현 범위를 명시하고, 운영 runbook은 column deletion을 rollback으로 제시하지 않는다.
+
+## D-3. Runtime boundary
+
+`app/repositories/postgres.py:ensure_schema()`는 bootstrap safety 경로로 유지한다. Alembic revision은 persistent schema history의 source of truth로 둔다. migration 성공만으로 version table을 임의 stamp하지 않으며, schema와 Alembic current가 함께 일치하는지 검증한다.
+
+## D-4. Test matrix
+
+| 시작 상태 | 검증 |
+| --- | --- |
+| fresh Alembic schema | upgrade, 네 컬럼 타입/nullable/default, current/head |
+| 기존 ledger rows | row count/business data 보존, source broker backfill |
+| runtime-precreated columns | 중복 DDL 부재, constraints/default 정합, current/head |
+| broker write | 기존 `/ledger/trades` 회귀 없음 |
+| manual API | source/manual metadata 및 REQ-056 핵심 regression |
+| runbook | preflight 조건, 실패 중단, forward-only recovery 문서 정합 |
+
+## D-5. Operational gate
+
+이번 batch는 local/non-production verification만 수행한다. 운영 DB backup/upgrade, service restart, 신규 API activation, deploy/push/merge는 M5 Release의 별도 결재 없이는 실행하지 않는다. runbook은 실행 가능한 명령 템플릿과 중단 조건을 제공하되 실제 운영 결과를 가장하지 않는다.
+
+## Design decisions / open findings
+
+- 실제 revision ID는 구현 preflight 결과로 결정한다.
+- 실제 DB driver availability에 따라 migration integration test harness는 repository 표준 fixture 또는 isolated PostgreSQL 경로를 사용하되, 사용하지 못한 환경은 QC evidence에 명시한다.
+- stamp 필요성은 schema inspection과 version table evidence 이후에만 판단하며 자동 조치하지 않는다.
@@ -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 산출)
@@ -0,0 +1,49 @@
+# 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 승인 없이는 확보하지 않는다.
@@ -32,3 +32,4 @@
 | BAT-022 | standard | release-candidate | REQ-052, REQ-053, REQ-054 | dcy-011 | [bat-022](./bat-022_20260628_daemon-crud-self-service-credential-api/) |
 | BAT-023 | batch-lite | in-progress | REQ-055 | trex-tvr-v1 dcy-001 | [bat-023](./bat-023_20260704_portfolios-strategy-market-meta/) |
 | BAT-024 | standard | release-candidate | REQ-056 | dcy-012 | [bat-024](./bat-024_20260714_manual-ledger-api/) |
+| BAT-025 | standard | confirmed | REQ-057 | dcy-012 follow-on | [bat-025](./bat-025_20260715_portfolio-ledger-alembic-migration/) |