gp/docs/roadmaps/v1.0.2-local-database-product-loop.md

Focus Seed 1.0.2 Local Database Product Loop

Decision Header

• Objective: move Focus Seed from a simple local MVP into a richer offline-first product with durable history, user-facing settings, and basic retention feedback.
• Worth doing: yes. History and statistics need relational data; the current JSON document is no longer the right foundation.
• Scale: large-high-risk. This changes persistence, state loading, settings IA, and Journey value.
• Mode: full workflow with checkpoints.
• Success evidence: flutter analyze, flutter test, release AAB build, manifest permission review, mojibake scan, and emulator smoke on Today/Journey/Me.
• Key assumption: no account, no cloud, no server, no ads/billing SDKs, no media permissions in this release.

Product Boundary

Focus Seed remains a private local focus companion. The 1.0.2 goal is not to add breadth for its own sake; it is to close the daily loop:

1. Pick one daily priority.
2. Complete focused time.
3. Mark a few habits.
4. Capture one reflection.
5. See meaningful progress over time.

Explicit Non-Goals

• No LLM.
• No account or cloud sync.
• No ads, subscriptions, billing, Firebase, or analytics SDK.
• No user photo/video editing in 1.0.2. Media would add storage, privacy, permission, backup, and UI complexity before the core loop is strong enough.
• No user-facing JSON import/export. JSON can remain a debug-only migration tool if needed.

Data Architecture

Use Drift + SQLite as the local persistence boundary.

Tables:

• daily_intentions: daily priority text by date.
• focus_sessions: planned minutes, actual seconds, start/end timestamps, completion status.
• habits: title, sort order, archived timestamp.
• habit_logs: habit completion by date.
• reflections: mood, note, date.
• app_settings: small key/value settings such as default focus duration.

Repository boundary:

• UI and controllers talk to a repository/store interface.
• Drift implementation owns queries and migrations.
• Existing AppState can remain as an application snapshot while the database becomes source of truth.
• V1 JSON document is migrated once into SQLite, then the app reads from SQLite.

Settings IA

User-facing settings:

• Appearance: theme.
• Focus preferences: default session duration.
• Privacy and data: local-only explanation, clear today's data, clear all local data.
• About: version and privacy summary.

Debug-only settings:

• Language switch.
• Developer data tools only if needed for migration QA.

Remove from user-facing UI:

• Export JSON.
• Import JSON.

Journey Enhancements

P0 for Journey:

• Show useful progress at a glance, not just raw recent records.

Add:

• Current streak.
• Focus minutes this week.
• Habit completion this week.
• Reflection count this week.
• Recent focus sessions.
• Recent reflections.

Today Enhancements

Copy:

• Replace "Choose one outcome" with user language: "What matters today?" / "写下今天最重要的一件事".
• Replace "Today's intention" with "Today's priority" / "今日重点".

Interaction:

• Add small success feedback after completing a focus session, habit, or reflection.
• Keep P0 action visible; no decorative element may compete with the timer or priority.
• Use implicit animations only; no continuous distracting motion.

Workflow

Phase 0: Plan checkpoint

• Create branch.
• Add this plan.
• Commit the plan.

Phase 1: Database foundation

• Add Drift dependencies.
• Create database tables and DAO/repository.
• Add migration from existing local JSON state.
• Keep controllers stable by returning an AppState snapshot.
• Tests: migration, CRUD, statistics.
• Commit.

Phase 2: Settings cleanup

• Remove user-facing JSON import/export.
• Add clear today's data and clear all data confirmations with impact text.
• Keep language switch debug-only.
• Tests: settings visibility and destructive confirmations.
• Commit.

Phase 3: Retention value

• Add Journey summary cards and history sections backed by database queries.
• Add focus preference for default duration if safe.
• Tests: statistics and visible Journey labels.
• Commit.

Phase 4: QA and release artifact

• Mojibake scan.
• flutter analyze.
• flutter test.
• flutter build appbundle --release.
• Emulator smoke for Today/Journey/Me.
• Commit final polish.

Acceptance Gate

1. No user-facing JSON wording.
2. No new Android runtime permissions.
3. Existing installed 1.0.1 data migrates.
4. New install starts with local database seed data.
5. Journey gives at least three useful progress signals.
6. Settings reads as user product settings, not developer tools.
7. Worktree is clean after checkpoint commit.