63 lines
2.5 KiB
Markdown
63 lines
2.5 KiB
Markdown
|
# Quality Guidelines
|
||
|
|
|
||
|
|
> Frontend quality baseline for `apps/**` changes.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Practical Conventions
|
||
|
|
|
||
|
|
1. Run Flutter analyzer/tests for touched scope before finalizing changes.
|
||
|
|
2. Keep error logging explicit at catch sites using project logger (`getLogger(...)`).
|
||
|
|
3. Prioritize regression tests for high-risk modules: auth/session, home viewport, cache/repository, agent SSE flows.
|
||
|
|
4. Keep docs/protocol/frontend mappings aligned for API-contract changes.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Real File Path Examples
|
||
|
|
|
||
|
|
- Lint/static analysis configuration:
|
||
|
|
- `apps/analysis_options.yaml`
|
||
|
|
- `apps/pubspec.yaml` (dev dependencies: `flutter_test`, `bloc_test`, `mocktail`)
|
||
|
|
- Test suites for high-risk modules:
|
||
|
|
- `apps/test/app/router/app_router_redirect_test.dart`
|
||
|
|
- `apps/test/core/chat/ag_ui_service_test.dart`
|
||
|
|
- `apps/test/data/cache/cached_repository_test.dart`
|
||
|
|
- Logging usage examples:
|
||
|
|
- `apps/lib/features/auth/presentation/bloc/auth_bloc.dart`
|
||
|
|
- `apps/lib/features/auth/presentation/cubits/login_cubit.dart`
|
||
|
|
- `apps/lib/features/settings/presentation/cubits/automation_jobs_cubit.dart`
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Review Checklist
|
||
|
|
|
||
|
|
1. **Layering and ownership**
|
||
|
|
- No feature business logic moved into shared `data/**` infra.
|
||
|
|
2. **Error handling**
|
||
|
|
- Exceptions are either propagated or converted to typed user-safe errors.
|
||
|
|
- Catch branches include context logging where actionable.
|
||
|
|
3. **Contract alignment**
|
||
|
|
- If API/error/event contracts changed, protocol docs and mapping updates are in the same change.
|
||
|
|
4. **Regression coverage**
|
||
|
|
- Add/adjust tests for changed behavior in critical flows.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Anti-patterns (with evidence)
|
||
|
|
|
||
|
|
- Error swallowing branches that silently downgrade behavior.
|
||
|
|
- Existing examples to avoid extending:
|
||
|
|
- `apps/lib/app/di/injection.dart` refresh callback catch returns `false`.
|
||
|
|
- `apps/lib/core/chat/ag_ui_service.dart` malformed SSE payload parse catch ignores payload.
|
||
|
|
- Feature code bypassing shared feedback/loading primitives.
|
||
|
|
- Project standard primitives exist in `apps/lib/shared/widgets/toast/`, `apps/lib/shared/widgets/banner/`, `apps/lib/shared/widgets/app_loading_indicator.dart`.
|
||
|
|
- Protocol changes implemented only in one layer.
|
||
|
|
- Contract source of truth is under `docs/protocols/**` and must stay synchronized.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Uncertainties / Gaps
|
||
|
|
|
||
|
|
- The repository does not currently enforce all frontend rules via CI (for example, no strict automated checker for protocol-mapper parity).
|
||
|
|
- `analysis_options.yaml` is currently close to Flutter defaults; stricter lint rules may still be introduced incrementally.
|