# Phase 3 - Persistence and Migration Foundation

Reference artifacts:
- docs/database-persistence-implementation-guide.md
- docs/database-persistence-integration-phases-11-14.md
- docs/adr/0010-release-strategy-and-migration-rollback.md
- docs/multiwallet_suggested.md
- docs/multi-wallet/multi-wallet-phase-tracker.md

## 1. Phase Objective
Implement persistence model updates and safe migration sequencing for multi-wallet capabilities.

Phase status target:
- Start: not-started
- End: done when migrations are validated in lower environments with rollback rehearsal.

## 2. Scope
In scope:
- Schema design for wallet products, currency configs, sub-wallets, balance ledger, and transaction extensions.
- Migration sequencing with minimal lock risk.
- Data backfill strategy for existing users/wallets.
- Read/write compatibility strategy during transition.

Out of scope:
- Full business command implementation.

## 3. Work Breakdown
## Track A: Schema Definition
1. Define schema additions/changes in current repository style.
- Owner: Database Team
- Output: migration set and schema docs.

2. Add indexes and constraints needed for performance and integrity.
- Owner: Database Team
- Output: index and constraint plan.

## Track B: Migration Safety
1. Create online-compatible migration plan.
- Owner: Platform + DBA
- Output: phased migration steps.

2. Define rollback strategy per migration step.
- Owner: Platform + DBA
- Output: rollback matrix.

## Track C: Data Backfill
1. Plan backfill for existing wallet records.
- Owner: Data Team
- Output: backfill script design.

2. Validate backfill idempotency and rerun safety.
- Owner: Data Team
- Output: verified rerun procedure.

## 4. Execution Checklist
- [x] Migration files created. (8 migrations: 20260330150000–20260330220000)
- [x] Schema docs updated. (5 new Ecto schemas + 4 existing schemas updated)
- [x] Index/constraint plan applied. (status constraints, unique indexes, sub_wallet_id indexes)
- [x] Roll-forward plan documented. (docs/multi-wallet/deliverables/migration-plan-and-runbook.md §3)
- [x] Rollback plan documented and reviewed. (migration-plan-and-runbook.md §5)
- [x] Backfill design completed. (migration-plan-and-runbook.md §4 — B01/B02/B03/B04)
- [ ] Dry-run migration executed in dev/test.
- [x] Tracker updated with Phase 3 progress.

## 5. Verification Checklist
- [ ] Migration dry-run passes without data loss.
- [ ] Rollback rehearsal validated.
- [x] Backfill is idempotent and measurable. (B01: wallet_product_id IS NOT NULL guard)
- [ ] Query performance baseline captured before/after.

## 6. Exit Criteria
Phase completes only when:
- All migration scripts are approved.
- Rollback rehearsal is successful.
- Persistence layer is ready for domain wiring in Phase 4.

## 7. Deliverables
- Migration pack
- Backfill and rollback runbook
- Persistence validation report
- Updated tracker entry