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,60 @@
+# Directory Structure
+
+> How frontend (Flutter) code is organized in this repository.
+
+---
+
+## Practical Conventions
+
+1. `apps/lib/main.dart` is the single root entry file.
+2. Keep second-level folders fixed to: `app/`, `core/`, `data/`, `features/`, `shared/`, `l10n/`.
+3. Put feature business code under `features/<feature>/...`; keep cross-feature infra/protocol in `core/` and shared infra in `data/`.
+4. Shared reusable UI belongs to `shared/widgets/**`, not duplicated under each feature.
+
+---
+
+## Real File Path Examples
+
+- App bootstrap and routing composition:
+  - `apps/lib/main.dart`
+  - `apps/lib/app/app.dart`
+  - `apps/lib/app/router/app_router.dart`
+- Shared infrastructure (non-feature business):
+  - `apps/lib/data/network/api_client.dart`
+  - `apps/lib/data/cache/cache_store.dart`
+  - `apps/lib/core/theme/app_theme.dart`
+- Feature-bounded implementation:
+  - `apps/lib/features/todo/data/apis/todo_api.dart`
+  - `apps/lib/features/todo/data/repositories/todo_repository.dart`
+  - `apps/lib/features/auth/presentation/bloc/auth_bloc.dart`
+
+---
+
+## Placement Checklist (before adding a file)
+
+1. Does this logic belong to exactly one feature flow?
+   - Yes -> `features/<feature>/...`
+2. Is it cross-feature protocol/orchestration (auth/session/notification/ui schema)?
+   - Yes -> `core/**`
+3. Is it shared storage/network/cache infra?
+   - Yes -> `data/**`
+4. Is it reusable widget/presentation helper with no feature business orchestration?
+   - Yes -> `shared/widgets/**` (or `shared/forms/**`)
+
+---
+
+## Anti-patterns (with evidence)
+
+- Creating feature business repositories/models under shared `apps/lib/data/**`.
+  - Existing correct pattern is feature-local repositories under `apps/lib/features/**/data/repositories/`.
+- Letting UI code bypass repositories for consistency-sensitive data flow.
+  - Correct references: `apps/lib/features/todo/data/repositories/todo_repository.dart`, `apps/lib/features/messages/data/repositories/inbox_repository.dart`.
+- Deep redundant nesting without clear ownership.
+  - Current tree generally keeps flat-by-concern organization (e.g., `data/apis`, `data/repositories`, `presentation/screens`, `presentation/widgets`).
+
+---
+
+## Uncertainties / Gaps
+
+- Some modules blend domain-specific and infrastructure concerns (for example, notification rewrite boundaries) and rely on AGENTS rules rather than strict automated folder enforcement.
+- No script currently validates folder placement rules automatically; enforcement is mostly review + convention.