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,56 @@
+# Frontend Development Guidelines (Flutter App)
+
+> Scope: `apps/**` (Flutter mobile app). This index links to project-grounded guidelines only.
+
+---
+
+## Practical Conventions (Quick Rules)
+
+1. Keep `apps/lib` second-level layout stable: `app/`, `core/`, `data/`, `features/`, `shared/`, `l10n/`.
+2. Use feature-bounded modules under `features/<domain>/...` and keep shared infra in `data/` + `core/`.
+3. Parse backend errors as RFC7807 (`code`/`params`) and keep mapping synced with protocol docs.
+4. Prefer shared UI widgets (`shared/widgets/**`) and design tokens (`AppSpacing`/`AppRadius` + `Theme.colorScheme`).
+
+---
+
+## Repository Evidence (entry files to read first)
+
+- `apps/lib/main.dart` - bootstrap entry (`configureDependencies`, `Env.init`, `runApp`)
+- `apps/lib/app/app.dart` - app shell + theme + auth lifecycle orchestration
+- `apps/lib/app/di/injection.dart` - DI registration and cross-feature singleton wiring
+- `apps/AGENTS.md` - enforced frontend domain rules
+
+## Real File Path Examples
+
+- `apps/lib/main.dart`
+- `apps/lib/app/di/injection.dart`
+- `apps/lib/data/network/error_code_mapper.dart`
+
+---
+
+## Guidelines Index
+
+| Guide | Focus |
+|---|---|
+| [Directory Structure](./directory-structure.md) | Module boundaries and placement rules |
+| [Component Guidelines](./component-guidelines.md) | Widget composition, shared components, design system usage |
+| [Hook Guidelines (Bloc/Cubit State Flows)](./hook-guidelines.md) | Flutter state flow conventions using Bloc/Cubit |
+| [Type Safety](./type-safety.md) | DTO parsing, API boundary typing, protocol alignment |
+| [Quality Guidelines](./quality-guidelines.md) | Lint/test/logging expectations and review checklist |
+
+---
+
+## Anti-patterns Observed (do not copy)
+
+- Silent/weak failure branches still exist in some paths and should not be expanded:
+  - `apps/lib/app/di/injection.dart` (`setRefreshCallback` catch branch returns `false` without logging)
+  - `apps/lib/core/chat/ag_ui_service.dart` (malformed SSE payload catch branch intentionally ignores parse error)
+- Directly hardcoding API contract assumptions outside protocol docs/mappers leads to drift:
+  - Keep `docs/protocols/common/http-error-codes.md` and `apps/lib/data/network/error_code_mapper.dart` synchronized.
+
+---
+
+## Uncertainties / Gaps
+
+- The frontend workflow doc (`.trellis/workflow.md`) still uses the historical filename `hook-guidelines.md`; this index keeps the filename for compatibility while the content is Flutter Bloc/Cubit specific.
+- There is no repository-level automated check yet proving every protocol-code change updates all three sides (backend + protocol docs + frontend mapping); this is currently review-driven.