From 9ba681e3c7ec44e84926c1eb2776b84a8a3bcd1c Mon Sep 17 00:00:00 2001
From: leavy <leavysong@gmail.com>
Date: Fri, 12 Jun 2026 00:34:16 +0800
Subject: [PATCH] docs: plan 1.0.2 local database product loop

---
 .../v1.0.2-local-database-product-loop.md     | 146 ++++++++++++++++++
 1 file changed, 146 insertions(+)
 create mode 100644 docs/roadmaps/v1.0.2-local-database-product-loop.md

diff --git a/docs/roadmaps/v1.0.2-local-database-product-loop.md b/docs/roadmaps/v1.0.2-local-database-product-loop.md
new file mode 100644
index 0000000..33af19b
--- /dev/null
+++ b/docs/roadmaps/v1.0.2-local-database-product-loop.md
@@ -0,0 +1,146 @@
+# 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.