60 lines
2.6 KiB
Markdown
60 lines
2.6 KiB
Markdown
|
# Hook Guidelines (Bloc/Cubit State Flows)
|
||
|
|
|
||
|
|
> This repository is Flutter-based. This file defines state-flow conventions using Bloc/Cubit.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Practical Conventions
|
||
|
|
|
||
|
|
1. Treat `AuthBloc` as the global auth source of truth; auth invalidation should flow through its event chain.
|
||
|
|
2. Keep Cubit/Bloc states immutable and updated via `copyWith`.
|
||
|
|
3. Catch-and-handle branches should log errors with module-scoped logger names.
|
||
|
|
4. For async flow handoff (auth/session switch, SSE stream lifecycle), ensure race ordering is explicit (queues/epoch tokens/cancel semantics).
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Real File Path Examples
|
||
|
|
|
||
|
|
- Auth state source of truth and transitions:
|
||
|
|
- `apps/lib/features/auth/presentation/bloc/auth_bloc.dart`
|
||
|
|
- `apps/lib/features/auth/presentation/bloc/auth_event.dart`
|
||
|
|
- `apps/lib/features/auth/presentation/bloc/auth_state.dart`
|
||
|
|
- Feature-local form/interaction state:
|
||
|
|
- `apps/lib/features/auth/presentation/cubits/login_cubit.dart`
|
||
|
|
- `apps/lib/features/settings/presentation/cubits/automation_jobs_cubit.dart`
|
||
|
|
- Multi-step async orchestration with explicit stream/session control:
|
||
|
|
- `apps/lib/features/chat/presentation/bloc/chat_bloc.dart`
|
||
|
|
- `apps/lib/core/chat/ag_ui_service.dart`
|
||
|
|
- `apps/lib/app/app.dart`
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## State-Flow Checklist
|
||
|
|
|
||
|
|
Before adding/changing state logic:
|
||
|
|
|
||
|
|
1. Is state ownership clear (global vs feature-local)?
|
||
|
|
2. Are transitions serialized when order matters?
|
||
|
|
3. Are recoverable failures surfaced to UI state and logged?
|
||
|
|
4. Are side effects (cache reset, prewarm, SSE cancel/restart) bound to lifecycle events, not random UI callbacks?
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Anti-patterns (with evidence)
|
||
|
|
|
||
|
|
- Feature-level auth reset/navigation bypassing global auth flow.
|
||
|
|
- Correct path: `ApiClient` auth-failure callback -> `AuthSessionInvalidated` event (`apps/lib/app/di/injection.dart`, `apps/lib/features/auth/presentation/bloc/auth_bloc.dart`).
|
||
|
|
- Silent exception handling in async orchestration.
|
||
|
|
- Existing weak branches to avoid copying:
|
||
|
|
- `apps/lib/app/di/injection.dart` refresh callback catches and returns `false` without structured logging.
|
||
|
|
- `apps/lib/core/chat/ag_ui_service.dart` ignores malformed SSE payload parsing errors by design.
|
||
|
|
- Emitting mutable/partially-updated state objects.
|
||
|
|
- Current state classes use immutable fields + `copyWith` (`LoginState`, `ChatState`, `AutomationJobsState`).
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Uncertainties / Gaps
|
||
|
|
|
||
|
|
- The codebase uses both Bloc and Cubit; exact selection criteria (when to pick Bloc vs Cubit) are not formally codified beyond existing patterns.
|
||
|
|
- Some cancellation/retry branches return error strings directly (e.g., chat flow) and may need future standardization if UX/error taxonomy requirements tighten.
|