137 lines
8.6 KiB
Markdown
137 lines
8.6 KiB
Markdown
# Agent Development Rules
|
|
|
|
These rules are **NON-NEGOTIABLE**. They are designed to prevent architectural degradation by automated agents.
|
|
|
|
## 1. File Creation & Structure
|
|
|
|
1. **Feature-First Packaging**:
|
|
* **DO**: Create new features as independent packages in `apps/mobile/packages/features/<app_name>/<feature_name>`.
|
|
* **DO NOT**: Add features to `apps/mobile/packages/core` or existing apps directly.
|
|
* **DO NOT**: Create cross-feature or cross-app dependencies.
|
|
2. **Path Conventions**:
|
|
* Entities: `apps/mobile/packages/domain/lib/src/entities/<entity>.dart`
|
|
* Repositories (Interface): `apps/mobile/packages/features/<app_name>/<feature>/lib/src/domain/repositories/<name>_repository_interface.dart`
|
|
* Repositories (Impl): `apps/mobile/packages/features/<app_name>/<feature>/lib/src/data/repositories_impl/<name>_repository_impl.dart`
|
|
* Use Cases: `apps/mobile/packages/features/<app_name>/<feature>/lib/src/application/<name>_usecase.dart`
|
|
* BLoCs: `apps/mobile/packages/features/<app_name>/<feature>/lib/src/presentation/blocs/<name>_bloc.dart`
|
|
* Pages: `apps/mobile/packages/features/<app_name>/<feature>/lib/src/presentation/pages/<name>_page.dart`
|
|
* Widgets: `apps/mobile/packages/features/<app_name>/<feature>/lib/src/presentation/widgets/<name>_widget.dart`
|
|
3. **Barrel Files**:
|
|
* **DO**: Use `export` in `lib/<package_name>.dart` only for public APIs.
|
|
* **DO NOT**: Export internal implementation details in the main package file.
|
|
|
|
## 2. Naming Conventions
|
|
|
|
Follow Dart standards strictly.
|
|
|
|
| Type | Convention | Example |
|
|
| :--- | :--- | :--- |
|
|
| **Files** | `snake_case` | `user_profile_page.dart` |
|
|
| **Classes** | `PascalCase` | `UserProfilePage` |
|
|
| **Variables** | `camelCase` | `userProfile` |
|
|
| **Interfaces** | terminate with `Interface` | `AuthRepositoryInterface` |
|
|
| **Implementations** | terminate with `Impl` | `AuthRepositoryImpl` |
|
|
|
|
## 3. Logic Placement (Strict Boundaries)
|
|
|
|
* **Business Rules**: MUST reside in **Use Cases** (Domain/Feature Application layer).
|
|
* *Forbidden*: Placing business rules in BLoCs or Widgets.
|
|
* **State Logic**: MUST reside in **BLoCs** or **StatefulWidgets** (only for ephemeral UI state).
|
|
* *Forbidden*: `setState` in Pages for complex state management.
|
|
* **Recommendation**: Pages should be `StatelessWidget` with state delegated to BLoCs.
|
|
* **Data Transformation**: MUST reside in **Repositories** (Data Connect layer).
|
|
* *Forbidden*: Parsing JSON in the UI or Domain.
|
|
* **Pattern**: Repositories map Data Connect models to Domain entities.
|
|
* **Navigation Logic**: MUST reside in **Flutter Modular Routes** and use **Safe Navigation**.
|
|
* *Forbidden*: `Navigator.push` with hardcoded widgets or direct `Modular.to.pop()` / `Modular.to.navigate()`.
|
|
* **Pattern**: Use `popSafe()`, `safeNavigate()`, `safePush()`, etc., from `NavigationExtensions`. Prefer **Typed Navigators** (e.g., `Modular.to.toHome()`).
|
|
* **Fallback**: All navigation MUST have a fallback to the Home page implemented in `NavigationExtensions`.
|
|
* **Session Management**: MUST reside in **DataConnectService** via **SessionHandlerMixin**.
|
|
* **Pattern**: Automatic token refresh, auth state listening, and role-based validation.
|
|
* **UI Reaction**: **SessionListener** widget wraps the entire app and responds to session state changes.
|
|
|
|
## 4. Localization (core_localization) Integration
|
|
|
|
All user-facing text MUST be localized using the centralized `core_localization` package:
|
|
|
|
1. **String Management**:
|
|
* Define all user-facing strings in `apps/mobile/packages/core_localization/lib/src/l10n/`
|
|
* Use `slang` or similar i18n tooling for multi-language support
|
|
* Access strings in presentation layer via `context.strings.<key>`
|
|
2. **BLoC Integration**:
|
|
* `LocaleBloc` manages the current locale state
|
|
* Apps import `core_localization.LocalizationModule()` in their module imports
|
|
* Wrap app with `BlocProvider<LocaleBloc>()` to expose locale state globally
|
|
3. **Feature Usage**:
|
|
* Pages and widgets access localized strings: `Text(context.strings.buttonLabel)`
|
|
* Build methods receive `BuildContext` with access to current locale
|
|
* No hardcoded English strings in feature packages
|
|
4. **Error Messages**:
|
|
* Use `ErrorTranslator` from `core_localization` to map domain failures to user-friendly messages
|
|
* **Pattern**: Failures emitted from BLoCs are translated to localized strings in the UI
|
|
|
|
## 5. Data Connect Integration Strategy
|
|
|
|
All backend access is centralized through `DataConnectService` in `apps/mobile/packages/data_connect`:
|
|
|
|
1. **Repository Interface First**: Define `abstract interface class <Name>RepositoryInterface` in the feature's `domain/repositories/` folder.
|
|
2. **Repository Implementation**: Implement the interface in `data/repositories_impl/` using `_service.run()` wrapper.
|
|
* **Pattern**: `await _service.run(() => connector.<query>().execute())`
|
|
* **Benefit**: Automatic auth validation, token refresh, and error handling.
|
|
3. **Session Handling**: Use `DataConnectService.instance.initializeAuthListener(allowedRoles: [...])` in app main.dart.
|
|
* **Automatic**: Token refresh with 5-minute expiry threshold.
|
|
* **Retry Logic**: 3 attempts with exponential backoff (1s → 2s → 4s) before emitting error.
|
|
* **Role Validation**: Configurable per app (e.g., Staff: `['STAFF', 'BOTH']`, Client: `['CLIENT', 'BUSINESS', 'BOTH']`).
|
|
4. **Session State Management**: Wrap app with `SessionListener` widget to react to session changes.
|
|
* **Dialogs**: Shows session expired or error dialogs for user-facing feedback.
|
|
* **Navigation**: Routes to login on session loss, to home on authentication.
|
|
|
|
## 5. Prototype Migration Rules
|
|
|
|
You have access to `prototypes/` folders. When migrating code:
|
|
|
|
1. **Extract Assets**:
|
|
* You MAY copy icons, images, and colors. But they should be tailored to the current design system. Do not change the colours and typgorahys in the design system. They are final. And you have to use these in the UI.
|
|
* When you matching colous and typography, from the POC match it with the design system and use the colors and typography from the design system. As mentioned in the `apps/mobile/docs/03-design-system-usage.md`.
|
|
2. **Extract Layouts**: You MAY copy `build` methods for UI structure.
|
|
3. **REJECT Architecture**: You MUST **NOT** copy the `GetX`, `Provider`, or `MVC` patterns often found in prototypes. Refactor immediately to **Bloc + Clean Architecture with Flutter Modular and Melos**.
|
|
|
|
## 6. Handling Ambiguity
|
|
|
|
If a user request is vague:
|
|
|
|
1. **STOP**: Do not guess domain fields or workflows.
|
|
2. **ANALYZE**:
|
|
- For architecture related questions, refer to `apps/mobile/docs/01-architecture-principles.md` or existing code.
|
|
- For design system related questions, refer to `apps/mobile/docs/03-design-system-usage.md` or existing code.
|
|
3. **DOCUMENT**: If you must make an assumption to proceed, add a comment `// ASSUMPTION: <explanation>` and mention it in your final summary.
|
|
4. **ASK**: Prefer asking the user for clarification on business rules (e.g., "Should a 'Job' have a 'status'?").
|
|
|
|
## 7. Dependencies
|
|
|
|
* **DO NOT** add 3rd party packages without checking `apps/mobile/packages/core` first.
|
|
* **DO NOT** add `firebase_auth` or `firebase_data_connect` to any Feature package. They belong in `data_connect` only.
|
|
* **Service Locator**: Use `DataConnectService.instance` for singleton access to backend operations.
|
|
* **Dependency Injection**: Use Flutter Modular for BLoC (never use `addSingleton` for Blocs, always use `add` method) and UseCase injection in `Module.routes()`.
|
|
|
|
## 8. Error Handling
|
|
|
|
* **Domain Failures**: Define custom `Failure` classes in `domain/failures/`.
|
|
* **Data Connect Errors**: Map Data Connect exceptions to Domain failures in repositories.
|
|
* **User Feedback**: BLoCs emit error states; UI displays snackbars or dialogs.
|
|
* **Session Errors**: SessionListener automatically shows dialogs for session expiration/errors.
|
|
|
|
## 9. Testing
|
|
|
|
* **Unit Tests**: Test use cases and repositories with real implementations.
|
|
* **Widget Tests**: Use `WidgetTester` to test UI widgets and BLoCs.
|
|
* **Integration Tests**: Test full feature flows end-to-end with Data Connect.
|
|
* **Pattern**: Use dependency injection via Modular to swap implementations if needed for testing.
|
|
|
|
## 10. Follow Clean Code Principles
|
|
|
|
* Add doc comments to all classes and methods you create.
|
|
* Keep methods and classes focused and single-responsibility.
|
|
* Use meaningful variable names that reflect intent.
|
|
* Keep widget build methods concise; extract complex widgets to separate files.
|