首次远程推送

2026-09-27 23:40:22 +08:00
parent 2e0bf3c784
commit 8afa47952a
70 changed files with 8603 additions and 4502 deletions
@@ -1,6 +1,6 @@
 # Focus Seed Architecture

-Status: refactored from single-file prototype into modular Flutter structure.
+Status: current release architecture for Focus Seed 1.0.2.

 ## Directory Layout

@@ -8,77 +8,71 @@ Status: refactored from single-file prototype into modular Flutter structure.
 lib/
  main.dart
  src/
-    app/
-      focus_seed_app.dart
-      app_theme.dart
-    core/
-      date_keys.dart
-      iterable_extensions.dart
-      json_utils.dart
-    data/
-      focus_seed_store.dart
-    models/
-      app_state.dart
-      focus_session.dart
-      habit.dart
-      mood.dart
-      reflection_entry.dart
-    services/
-      analytics_provider.dart
-      monetization_provider.dart
-    features/
-      shell/
-        focus_seed_home.dart
-      home/
-        home_screen.dart
-      timer/
-        timer_screen.dart
-      habits/
-        habits_screen.dart
-      reflection/
-        reflection_screen.dart
-      settings/
-        settings_screen.dart
-    widgets/
-      app_scaffold.dart
-      dialogs.dart
-      empty_state.dart
-      habit_row.dart
-      inline_editable_text.dart
-      loading_view.dart
-      metric_tile.dart
-      section_label.dart
-      seed_card.dart
-      settings_tile.dart
-      weekly_progress.dart
+    app/          app shell, theme, ambience, localization setup
+    application/  product controllers and timer lifecycle
+    core/         date keys, focus durations, ambience, utilities
+    data/         local persistence boundary
+    data/local/   Drift SQLite database
+    models/       immutable product models and derived state
+    services/     no-op analytics and monetization interfaces
+    features/     Today, Focus, Records, Me, habits, onboarding, reflection, shell
+    widgets/      reusable panels, dialogs, headers, loading, illustrations
 ```

 ## Responsibility Boundaries

 - `main.dart`: process entry only.
- `src/app`: app shell and theme.
- `src/models`: serializable domain objects.
- `src/data`: persistence boundary using `shared_preferences`.
- `src/services`: no-op interfaces for analytics and monetization.
- `src/features/shell`: state orchestration and feature routing.
+- `src/app`: app-level theme, locale policy, ambience updates, and shell bootstrapping.
+- `src/application`: user commands, save rollback, local analytics events, and timer lifecycle.
+- `src/core`: framework-light utilities and product constants.
+- `src/data`: persistence boundary used by controllers.
+- `src/data/local`: Drift tables, SQLite connection, and product-data clearing.
+- `src/models`: product snapshots, sessions, habits, reflections, mood, records, and progress models.
+- `src/services`: SDK-light interfaces with no-op implementations.
+- `src/features/shell`: top-level navigation and controller wiring.
 - `src/features/*`: screen-level UI and user flows.
- `src/widgets`: reusable UI components and dialogs.
- `src/core`: framework-light utilities.
+- `src/widgets`: reusable UI primitives.
+
+Widgets render state and forward intent. Controllers own commands. `FocusSeedStore` is the durable persistence boundary. Feature UI does not write to SQLite directly.
+
+## Current Product Structure
+
+Primary destinations:
+
+- Today: daily focus, timer entry, habit summary, reflection prompt, and loop progress.
+- Focus: immersive timer and active-session context.
+- Records: completed focus sessions, reflections, and lightweight history.
+- Me: preferences, privacy, local data controls, and about/legal surfaces.
+
+Habits are a Today support flow, not a primary tab. Growth/Journey was removed from the V1 primary surface; review belongs in Records until a future feature has enough depth to justify a dedicated destination.
+
+## Persistence
+
+Focus Seed is offline-first and stores product data locally with Drift/SQLite:
+
+- `daily_intentions`
+- `focus_sessions`
+- `habits`
+- `habit_logs`
+- `reflections`
+- `app_settings`
+
+The current user-facing app exposes no manual data transfer tools. Existing legacy local preference data is migrated once into SQLite when present, then removed. Small app preferences such as appearance and development language selection remain local preferences.

 ## Current Design Decisions

 - No real ad SDK in V1.
 - No real billing SDK in V1.
 - No analytics SDK in V1.
- No network dependency.
- JSON import/export uses copy/paste to avoid file permissions.
- Shell owns state until a future state-management package is justified.
+- No account, server, or network dependency.
+- Default focus duration is a user-facing local setting.
+- Clear today resets only today's loop.
+- Delete all data clears local product records while preserving app preference behavior where appropriate.

 ## Upgrade Path

-Next modularization steps when needed:
-
- Move `src/app`, `src/core`, `src/models`, `src/services`, and `src/widgets` into shared packages.
- Replace shell state with Riverpod once multiple apps/features share the same state patterns.
- Add real `AnalyticsProvider`, `MonetizationProvider`, and remote config implementations only with privacy/Data safety updates.
- Add golden tests for key screens before scaling the app factory.
+- Keep Drift as the local source of truth while the product remains offline-first.
+- Add DAO-style query methods before history grows large enough to make whole-snapshot writes inefficient.
+- Add Riverpod or a repository package only when multiple apps or features need shared state patterns.
+- Add real analytics, ads, billing, remote config, or sync only with privacy, Data safety, policy, and tests in the same release.
+- Add golden or screenshot tests before scaling launch screenshots or visual variants.