qzl
57 lines
2.6 KiB
Markdown
57 lines
2.6 KiB
Markdown
# 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.
|