2026-03-23 17:57:24 +08:00
|
|
|
# Apps Domain Rules
|
2026-02-05 15:13:06 +08:00
|
|
|
|
2026-03-23 17:57:24 +08:00
|
|
|
This file governs `apps/**` (Flutter). Keep rules strict, short, and reusable.
|
2026-02-24 18:18:42 +08:00
|
|
|
|
2026-03-23 17:57:24 +08:00
|
|
|
## Scope & Precedence
|
2026-03-12 16:41:45 +08:00
|
|
|
|
2026-03-23 17:57:24 +08:00
|
|
|
- Inherits root `AGENTS.md` and workspace runtime rules.
|
|
|
|
|
- If rules conflict, apply the stricter one.
|
|
|
|
|
- Visual language source of truth: `apps/rules/visual_design_language.md`.
|
2026-03-12 16:41:45 +08:00
|
|
|
|
2026-03-23 17:57:24 +08:00
|
|
|
## UI Design System (Must)
|
2026-02-24 18:18:42 +08:00
|
|
|
|
2026-03-23 17:57:24 +08:00
|
|
|
- Use design tokens only from `apps/lib/core/theme/design_tokens.dart` (`AppColors`, `AppSpacing`, `AppRadius`).
|
|
|
|
|
- No hardcoded visual values.
|
|
|
|
|
- If semantics are missing, add token definitions first.
|
2026-02-24 18:18:42 +08:00
|
|
|
|
2026-03-23 17:57:24 +08:00
|
|
|
## Reuse & Composition (Must)
|
2026-02-27 15:22:42 +08:00
|
|
|
|
2026-03-23 17:57:24 +08:00
|
|
|
- Prefer `apps/lib/shared/widgets/` before adding new components.
|
|
|
|
|
- Extract repeated page structures/components; do not duplicate sibling-page scaffolds.
|
|
|
|
|
- Detail page top-right actions must use shared action-menu components.
|
|
|
|
|
- Destructive confirmations must use project-consistent shared surfaces.
|
2026-02-27 15:22:42 +08:00
|
|
|
|
2026-03-23 17:57:24 +08:00
|
|
|
## Interaction & Feedback (Must)
|
|
|
|
|
|
|
|
|
|
- User feedback: `Toast` / `AppBanner` only.
|
|
|
|
|
- Loading indicators: `AppLoadingIndicator` only.
|
|
|
|
|
- Form pages should default to keyboard-overlay behavior to avoid full-page layout jumps.
|
|
|
|
|
|
|
|
|
|
## Agent Chat Protocol (Must)
|
|
|
|
|
|
|
|
|
|
- Agent chat must follow AG-UI over SSE.
|
|
|
|
|
- Lifecycle events are mandatory: `RUN_STARTED` and exactly one of `RUN_FINISHED` or `RUN_ERROR`.
|
|
|
|
|
- Text streaming flow must be `TEXT_MESSAGE_START -> TEXT_MESSAGE_CONTENT -> TEXT_MESSAGE_END`.
|
|
|
|
|
|
|
|
|
|
## High-Risk Modules (Must)
|
|
|
|
|
|
|
|
|
|
### Auth
|
|
|
|
|
|
|
|
|
|
- `AuthBloc` is the single source of truth.
|
|
|
|
|
- 401 invalidation must go through global callback chain; no feature-level token clearing or direct login navigation.
|
|
|
|
|
|
|
|
|
|
### Home Message Viewport
|
|
|
|
|
|
|
|
|
|
- Home message auto-scroll/anchor restore must be event-driven.
|
|
|
|
|
- Preserve viewport during history prepend and when user is reading above bottom.
|
|
|
|
|
|
|
|
|
|
### Cache / Repository
|
|
|
|
|
|
|
|
|
|
- Reads/writes that affect consistency must go through repository layer.
|
|
|
|
|
- Cache keys and invalidation policy belong to repository, not UI/Bloc.
|
|
|
|
|
|
|
|
|
|
## Testing Policy
|
|
|
|
|
|
|
|
|
|
- Prioritize tests for model parsing, service logic, and high-regression interaction flows.
|
|
|
|
|
- Simple static UI changes may skip tests.
|
|
|
|
|
- Auth/Home/Cache changes must include targeted regression tests.
|
