building-flutter-apps（building Flutter apps 命令行）

MANDATORY — Read Before Writing Any Code

Read this section + linked refs before code.

1. MUST copy analysis-options.md analysis_options.yaml verbatim into every project root.
2. MUST read architecture.md BEFORE creating any feature module, entity, model, datasource, or repository.
3. MUST read freezed-sealed.md BEFORE creating any Freezed class.
4. MUST read state-management.md BEFORE creating any notifier.
5. MUST read performance.md BEFORE writing any widget tree or provider.
6. NEVER use dynamic, _buildXxx() helpers, hardcoded strings, shrinkWrap: true, value!, or abstract class with Freezed.
7. ALWAYS check if (!ref.mounted) return; after every await in notifiers.
8. NEVER read state (incl. state.copyWith) in sync Notifier before build() returns. Seed via returned constructor, defer async init via Future.microtask. See state-management.md.
9. ALWAYS init repositories inside mutation methods (create*, update*, delete*, set*, reorder*) via _ensureRepository()/_ensureDependencies() helper. NEVER rely only on build()/_init() timing for write paths.
10. When touching guided tours, MUST read showcase-tours.md first. NEVER filter startShowCase() keys with key.currentContext checks.

Core Stack

Architecture

graph LR
  P[Presentation] --> R[Repository]
  R --> Do[Domain]
  R --> Da[Data]
  Da -.-> Do

lib/
├── core/           # Shared: theme, utils, widgets, navigation, services
├── features/
│   └── feature_x/
│       ├── data/           # Models, datasources (API/local)
│       ├── domain/         # Entities (pure Dart, no dependencies)
│       ├── repositories/   # Map models → entities
│       └── presentation/   # Notifiers, screens, widgets
└── main.dart

Critical Rules

1. Codegen only — @riverpod / @Riverpod(keepAlive: true). NEVER legacy StateProvider, StateNotifierProvider.
2. Sealed classes — sealed class with Freezed. NEVER abstract class.
3. No prop drilling — child widgets watch providers direct.
4. Guard async — if (!ref.mounted) return; after EVERY await in notifiers. if (!context.mounted) return; in widgets.
5. Single Ref — Riverpod 3.0 unified Ref types. NEVER AutoDisposeRef, FutureProviderRef.
6. Select in leaves — ref.watch(provider.select((s) => s.field)) in leaf widgets.
7. One primary class per file — exception: Freezed state + notifier may share file.
8. Interface contracts — abstract interface class for every repo + datasource. Constructors take interfaces, NEVER concrete types.
9. No dynamic — use Object? or proper type. Exception: Map<String, dynamic> in JSON.
10. Widget classes only — NEVER _buildXxx() helpers. Extract to named widget classes.
11. No hardcoded strings — *Strings constants classes with static const.
12. ref.watch in build, ref.read in callbacks.
13. Provider naming — codegen strips "Notifier": FooNotifier → fooProvider.
14. No shrinkWrap: true — use Sliver variants or constrained containers.
15. Mixins for capabilities, interfaces for contracts — see mixins.md.
16. No null-bang — NEVER value!. Use if (value case final v?).
17. abstract final class for static-only namespaces — NEVER Class._(). Exception: const Entity._() in Freezed.
18. ref.invalidate not ref.refresh when no return value needed.
19. Persistence SSOT — Default to repository/data persistence. Notifier persistence opt-in. One persistence owner per feature state.
20. Pop safely with GoRouter — For dismiss/back on pushable or deep-linkable screens, guard context.pop() with context.canPop(). If true, pop + return. Else navigate to typed fallback (const MyRoute().go(context)).
21. No silent mutation no-op — Mutation methods must not return early just because cached repo field null; lazily init deps first, then proceed or fail explicit.
22. Route-param safety in widgets — NEVER throw from widget build() for missing route IDs. Use nullable by-id providers + fallback UI. See common-patterns.md.
23. Navigation-critical mutation sequencing — In wizard/deep-link flows: persist write → targeted state sync → navigate. See common-patterns.md and state-management.md.
24. Showcase replay safety — Pass full ordered key list to startShowCase(). Do not gate by key.currentContext!= null / mounted checks; readiness is handled by scope registration + scheduling.

Provider Decision Tree

graph TD
  Q1{Repository, datasource, or service?} -->|Yes| A1["@Riverpod(keepAlive: true)"]
  Q1 -->|No| Q2{Feature notifier with mutable state?}
  Q2 -->|Yes| A2["@Riverpod(keepAlive: true) class XNotifier"]
  Q2 -->|No| Q3{Computed value or one-time fetch?}
  Q3 -->|Yes| Q5{All deps keepAlive?}
  Q5 -->|Yes| A5["@Riverpod(keepAlive: true)"]
  Q5 -->|No| A3["@riverpod — auto-disposes"]
  Q3 -->|No| Q4{Needs parameters?}
  Q4 -->|Yes| A4["Add params to function — family via codegen"]

Family + keepAlive caveat. Family + @Riverpod(keepAlive: true) keeps every key forever. Cache can grow unbounded. Prefer @riverpod.

Nested computed hop warning. Avoid computed -> computed chain in pause-sensitive paths (aProvider watches bProvider(param)). Riverpod 3.2.x offstage nav can throw TickerMode pause/resume assertion.

If chain required, flatten in parent provider:

• watch base state directly
• derive via pure helpers
• avoid provider -> provider indirection on hot navigation paths

Exception: Riverpod 3.2.x has TickerMode assertion bug (rrousselGit/riverpod#4709). If hit, keepAlive: true workaround allowed. Add inline note: // keepAlive: Riverpod 3.2.x #4709 workaround. Remove after upstream fix.

Anti-Patterns

Full patterns: common-patterns.md | extensions-utilities.md

Class Modifiers

Code Generation

dart run build_runner watch -d   # Watch mode (recommended)
dart run build_runner build -d   # One-time build
dart run build_runner clean && dart run build_runner build -d  # Clean build

References

Read before generating code for that topic.

Pre-Flight — Before Returning Any Code

• analysis_options.yaml from analysis-options.md in project root
• if (!ref.mounted) return; after EVERY await in notifiers
• if (!context.mounted) return; after EVERY await in widgets
• No _buildXxx() helpers — extracted to widget classes
• No hardcoded strings — *Strings constants classes
• No dynamic — Object? or proper types
• No value! — if (value case final v?)
• ref.watch() in build(), ref.read() only in callbacks
• Sync Notifier.build() never reads state before first state= — loading flags seeded via returned constructor; async init dispatched with Future.microtask; no fireImmediately: true listener that reads state without prior direct state = assignment
• Every notifier mutation method lazily inits repositories/deps (_ensureRepository/_ensureDependencies) before writes
• Route-param lookups in widget build() are nullable (no throw-on-missing-id)
• Wizard/deep-link mutation sequence: persist → targeted sync → navigate
• If showcase code changed: startShowCase() uses full ShowcaseKeys.*Tour list (no key.currentContext filtering), and replay/reset path follows showcase-tours.md