chore: bootstrap trellis workspace and sync deployment settings

2026-04-20 17:15:50 +08:00
parent 0842e04c39
commit eeed737949
82 changed files with 16522 additions and 11 deletions
@@ -0,0 +1,59 @@
+# 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.