diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index ac932dc..369efcf 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -13,7 +13,7 @@ This milestone transforms SimpleFinanceDash from a visually polished but cogniti Decimal phases appear between their surrounding integers in numeric order. - [ ] **Phase 5: Design System Token Rework** - Replace rounded corners with sharp edges and refine OKLCH pastel tokens across all 9 pages -- [ ] **Phase 6: Preset Data, First-Run Detection, and DB Safety** - Seed preset library, build first-run hook, and add DB uniqueness constraints that protect against duplicate data +- [x] **Phase 6: Preset Data, First-Run Detection, and DB Safety** - Seed preset library, build first-run hook, and add DB uniqueness constraints that protect against duplicate data - [ ] **Phase 7: Setup Wizard** - 3-step first-run wizard with income, pre-filled recurring items, and review — skippable, state-persisted, bilingual - [ ] **Phase 8: Auto-Budget Creation** - Auto-create current month's budget from template on dashboard visit, with correct currency and first-creation toast - [ ] **Phase 9: Inline Add and Dashboard Simplification** - Replace Quick Add page with inline Sheet panel, simplify dashboard to at-a-glance view, add empty states @@ -47,9 +47,9 @@ Plans: 5. `src/data/presets.ts` contains ~15-20 curated budget items with sensible default amounts, grouped by category type, with both English and German i18n translation keys defined **Plans:** 3 plans Plans: -- [ ] 06-01-PLAN.md — DB migrations (uniqueness constraints + setup_completed column + Profile type update) -- [ ] 06-02-PLAN.md — Preset library (src/data/presets.ts) and i18n translations (en.json + de.json) -- [ ] 06-03-PLAN.md — useFirstRunState hook, DB schema push, and verification checkpoint +- [x] 06-01-PLAN.md — DB migrations (uniqueness constraints + setup_completed column + Profile type update) +- [x] 06-02-PLAN.md — Preset library (src/data/presets.ts) and i18n translations (en.json + de.json) +- [x] 06-03-PLAN.md — useFirstRunState hook, DB schema push, and verification checkpoint ### Phase 7: Setup Wizard **Goal**: A new user can set up their budget template in under 3 minutes by following a guided 3-step wizard with pre-filled common items and a live running balance @@ -130,7 +130,7 @@ Phases execute in numeric order: 5 → 6 → 7 → 8 → 9 | Phase | Plans Complete | Status | Completed | |-------|----------------|--------|-----------| | 5. Design System Token Rework | 0/3 | Planned | - | -| 6. Preset Data, First-Run Detection, DB Safety | 0/? | Not started | - | +| 6. Preset Data, First-Run Detection, DB Safety | 3/3 | Complete | 2026-04-20 | | 7. Setup Wizard | 0/? | Not started | - | | 8. Auto-Budget Creation | 0/? | Not started | - | | 9. Inline Add and Dashboard Simplification | 0/? | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index a2ecf17..a3d8ca3 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -4,14 +4,14 @@ milestone: v2.0 milestone_name: milestone status: executing stopped_at: Roadmap created — ready to plan Phase 5 -last_updated: "2026-04-20T15:26:04.261Z" -last_activity: 2026-04-20 +last_updated: "2026-04-20T15:46:32.529Z" +last_activity: 2026-04-20 -- Phase 06 execution started progress: total_phases: 5 completed_phases: 1 - total_plans: 3 - completed_plans: 3 - percent: 100 + total_plans: 6 + completed_plans: 4 + percent: 67 --- # Project State @@ -21,16 +21,16 @@ progress: See: .planning/PROJECT.md (updated 2026-04-02) **Core value:** Opening the app should feel like opening a beautifully designed personal spreadsheet — clean pastel colors, clear data layout, approachable and visually delightful. The UI IS the product. -**Current focus:** Phase 05 — design-system-token-rework +**Current focus:** Phase 06 — preset-data-first-run-detection-and-db-safety ## Current Position -Phase: 6 -Plan: Not started -Status: Executing Phase 05 -Last activity: 2026-04-20 +Phase: 06 (preset-data-first-run-detection-and-db-safety) — EXECUTING +Plan: 3 of 3 (COMPLETE) +Status: Phase 06 complete +Last activity: 2026-04-20 -- Completed plan 06-03 (useFirstRunState + DB push) -Progress: [░░░░░░░░░░░░░░░░░░░░] 0/? plans (0%) +Progress: [████████████████████] 3/3 plans (100%) ## Performance Metrics @@ -79,6 +79,6 @@ None yet. ## Session Continuity -Last session: 2026-04-02 -Stopped at: Roadmap created — ready to plan Phase 5 +Last session: 2026-04-20 +Stopped at: Completed 06-03-PLAN.md — Phase 06 fully executed Resume file: None diff --git a/.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-03-SUMMARY.md b/.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-03-SUMMARY.md new file mode 100644 index 0000000..3e368b1 --- /dev/null +++ b/.planning/phases/06-preset-data-first-run-detection-and-db-safety/06-03-SUMMARY.md @@ -0,0 +1,87 @@ +--- +phase: 06 +plan: 03 +subsystem: first-run-detection +tags: [hooks, supabase, migrations, first-run] +started: "2026-04-20T17:32:09Z" +completed: "2026-04-20T18:07:20Z" +status: complete +dependency_graph: + requires: [06-01, 06-02] + provides: [useFirstRunState-hook, db-schema-live] + affects: [phase-07-wizard] +tech_stack: + added: [] + patterns: [derived-state-hook, loading-guard-pattern] +key_files: + created: + - src/hooks/useFirstRunState.ts + modified: [] +decisions: + - "Hook derives state from existing React Query caches (useCategories + useTemplate) with zero additional network calls" + - "DB migrations applied manually by user via supabase db push after checkpoint gate" +metrics: + duration: ~35min (including checkpoint wait) + tasks_completed: 3 + files_created: 1 + files_modified: 0 +--- + +# Phase 06 Plan 03: useFirstRunState Hook and DB Schema Push Summary + +Derived first-run detection hook reading from React Query cache with loading guard to prevent spurious redirects, plus live DB schema with uniqueness constraints and setup_completed column. + +## What Was Built + +### useFirstRunState Hook (src/hooks/useFirstRunState.ts) + +A read-only derived state hook that composes `useCategories()` and `useTemplate()` to determine whether the current user is a first-run user (no categories or no template items). Returns `{ isFirstRun: boolean, loading: boolean }`. The `loading` flag is critical -- callers in Phase 7 must check `!loading && isFirstRun` before redirecting to prevent false positives while queries are in flight. + +### DB Schema Push (migrations 006 + 007) + +User applied both migrations via `supabase db push`: +- Migration 006: UNIQUE constraints on `budgets(user_id, start_date)` and `categories(user_id, name)` with safe deduplication +- Migration 007: `setup_completed` boolean column on `profiles` with backfill for existing users + +## Task Execution + +| Task | Name | Commit | Status | +|------|------|--------|--------| +| 1 | Create useFirstRunState.ts | 0c1105f | Complete | +| 2 | DB schema push (migrations 006+007) | Manual (user) | Complete - user applied | +| 3 | Human verification checkpoint | N/A | Approved by user | + +## Decisions Made + +1. **Zero-network-call design** -- Hook reads from existing React Query caches rather than making its own Supabase calls, avoiding redundant fetches. +2. **Manual DB push** -- `supabase db push` required interactive confirmation; user ran it manually after checkpoint gate. + +## Deviations from Plan + +None -- plan executed exactly as written. + +## Known Stubs + +None -- hook is fully wired to existing data sources. + +## Verification Results + +- `export function useFirstRunState` found in hook file +- Both `useCategories` and `useTemplate` imports present +- `npx tsc --noEmit` passes with zero errors +- Migration files 006 and 007 exist in supabase/migrations/ +- User confirmed DB constraints and setup_completed column are live in Supabase dashboard + +## Requirements Covered + +- **AUTO-01**: useFirstRunState provides first-run detection for auto-budget flow +- **AUTO-03**: No hardcoded currency -- amounts are plain numbers throughout +- **SETUP-01**: setup_completed column + backfill (plan 01) + useFirstRunState detection (plan 03) +- **SETUP-02**: Preset library with 19 items delivered in plan 02 + +## Self-Check: PASSED + +- [x] src/hooks/useFirstRunState.ts exists +- [x] Commit 0c1105f verified in git log +- [x] TypeScript compiles cleanly +- [x] Migration files present on disk