qzl
122 lines
3.5 KiB
Markdown
122 lines
3.5 KiB
Markdown
# Flutter App Development Guidelines
|
|
|
|
> Best practices for Flutter app development in this project.
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
This directory contains guidelines for Flutter app development. Fill in each file with your project's specific conventions.
|
|
|
|
---
|
|
|
|
## Guidelines Index
|
|
|
|
| Guide | Description | Status |
|
|
|-------|-------------|--------|
|
|
| [Directory Structure](./directory-structure.md) | Module organization and file layout | Filled |
|
|
| [State Management](./state-management.md) | BLoC/Cubit, repository pattern, DI | Filled |
|
|
| [Error Handling](./error-handling.md) | ApiProblem, error parsing, l10n mapping | Filled |
|
|
| [Quality Guidelines](./quality-guidelines.md) | Code standards, forbidden patterns | Filled |
|
|
| [Logging Guidelines](./logging-guidelines.md) | Structured logging, log levels | Filled |
|
|
|
|
---
|
|
|
|
## How These Guidelines Were Filled
|
|
|
|
Each guideline file was populated based on:
|
|
|
|
1. **Existing codebase patterns** from `apps/lib/`
|
|
2. **AGENTS.md rules** from `apps/AGENTS.md`
|
|
3. **Real code examples** from `features/auth/`, `core/logging/`, etc.
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
### Directory Structure
|
|
|
|
- **Feature modules**: `features/<feature>/data/` + `features/<feature>/presentation/`
|
|
- **Core infrastructure**: `core/` (cross-feature)
|
|
- **Shared widgets**: `shared/widgets/`
|
|
- **Data layer**: `data/` (infrastructure only, not feature repositories)
|
|
|
|
### State Management
|
|
|
|
- **Pattern**: `ChangeNotifier` + immutable state
|
|
- **State**: Use `copyWith` pattern
|
|
- **DI**: Singleton blocs/repositories via ServiceLocator
|
|
|
|
### Error Handling
|
|
|
|
- **Format**: RFC 7807 (`ApiProblem`)
|
|
- **Mapping**: Error code → l10n key
|
|
- **Global**: 401 handled via `AuthBloc.handleUnauthorized401()`
|
|
|
|
### Logging
|
|
|
|
- **Library**: Custom `Logger` class
|
|
- **Module path**: `features.<feature>.<component>`
|
|
- **Error**: Always log with `error`, `stackTrace`, `message`
|
|
- **Forbidden**: PII, tokens, passwords
|
|
|
|
### Quality
|
|
|
|
- **Colors**: Semantic colors from `Theme.of(context).colorScheme`
|
|
- **Spacing**: Use `AppSpacing` / `AppRadius` tokens
|
|
- **Tests**: Unit, widget, integration tests for critical flows
|
|
|
|
---
|
|
|
|
## Key Principles
|
|
|
|
### Layer Boundaries
|
|
|
|
1. **Presentation** → **Repository** (via interface)
|
|
2. **Repository** → **Core/Infrastructure** (via DI)
|
|
3. **Core** → **Nothing** (foundation layer)
|
|
4. **Shared** → **Core** (for utilities)
|
|
5. **Feature** → **Core** + **Shared** (for cross-cutting concerns)
|
|
|
|
### Data Layer Boundary (Must)
|
|
|
|
- `data/` = infrastructure abstractions (cache/network/storage)
|
|
- `features/<feature>/data/` = feature business repositories/models
|
|
- **NEVER** mix these boundaries
|
|
|
|
### Error Code Contract (Must)
|
|
|
|
- **Single source of truth**: `docs/protocols/common/http-error-codes.md`
|
|
- **Frontend mapping**: Error code → l10n key
|
|
- **Backend updates → Frontend mapping updates** (must stay in sync)
|
|
|
|
---
|
|
|
|
## Common Anti-Patterns
|
|
|
|
### ❌ Do NOT:
|
|
|
|
1. Hardcode colors (`Color(0xFF...)`, `Colors.blue`)
|
|
2. Hardcode spacing (`Padding(padding: EdgeInsets.all(16.0))`)
|
|
3. Place feature repositories in shared `data/`
|
|
4. Import feature data layer from other features
|
|
5. Create new second-level directories under `lib/`
|
|
6. Use `print()` instead of Logger
|
|
7. Log PII/tokens/passwords
|
|
8. Catch exceptions without logging
|
|
|
|
---
|
|
|
|
## Architecture Decision Records
|
|
|
|
When making architectural decisions, document:
|
|
|
|
1. **Context**: What problem are we solving?
|
|
2. **Decision**: What approach did we choose?
|
|
3. **Consequences**: What are the trade-offs?
|
|
|
|
Add new ADRs to this directory if needed.
|
|
|
|
---
|
|
|
|
**Language**: All documentation should be written in **English**. |