qzl
01c36eb32e
- 删除 mock_api_client、mock_calendar_service、mock_history_service - 新增 fixed_length_code_input、link_button、message_composer 共享组件 - 优化登录/注册/密码重置页面使用新组件 - 简化 injection.dart 移除 mock 分支 - 更新 env.dart 配置（BACKEND_URL 替换 API_URL） - 后端 agentscope 工具和测试更新 - 重构 AGENTS.md 文档结构 - 新增 deploy/ 目录和 protocol 文档
76 lines
3.6 KiB
Markdown
76 lines
3.6 KiB
Markdown
# Flutter Mobile Development Constraints
|
|
|
|
This document defines **hard constraints** for Flutter mobile development. Treat all items as **non-negotiable** unless explicitly overridden.
|
|
|
|
## 0) Scope and Precedence (MUST)
|
|
|
|
- This file applies to all changes under `apps/**`.
|
|
- It extends root routing rules in `AGENTS.md` and workspace global runtime rules.
|
|
- If rules conflict, apply the stricter requirement.
|
|
- Keep Flutter-specific constraints in this file; avoid duplicating them in root `AGENTS.md`.
|
|
|
|
## 1) Design Tokens (MUST)
|
|
|
|
- **MUST** use design tokens from `apps/lib/core/theme/design_tokens.dart`:
|
|
- Colors: `AppColors.*`
|
|
- Spacing: `AppSpacing.*`
|
|
- Radius: `AppRadius.*`
|
|
- **MUST NOT** hardcode any visual values, including (but not limited to): colors, font sizes, spacing, padding/margins, widths/heights, radii, shadows, opacity, or “magic numbers”.
|
|
- Examples that are **NOT allowed**: `Color(0xFF...)`, `SizedBox(height: 12)`, `EdgeInsets.all(16)`, `Radius.circular(8)`.
|
|
|
|
## 2) Component Reuse (MUST)
|
|
|
|
- **MUST** prefer existing components and established page patterns over creating new UI components.
|
|
- **MUST** use:
|
|
- Buttons: `AppButton` from `apps/lib/shared/widgets/app_button.dart`
|
|
- **MUST NOT** introduce parallel UI systems (custom buttons, custom loading systems, custom input wrappers) unless explicitly required and approved.
|
|
|
|
## 3) Layout Mapping & Alignment (MUST)
|
|
|
|
- **MUST** explicitly set `crossAxisAlignment` for every `Row` / `Column` (do not rely on defaults).
|
|
- **MUST** preserve layout semantics from root to leaf:
|
|
- alignment/justification intent must be explicitly represented in Flutter widgets.
|
|
- **MUST NOT** skip necessary container layers if doing so loses layout meaning or makes mapping non-traceable.
|
|
|
|
## 4) Centering & Visual Balance (MUST)
|
|
|
|
- **MUST** evaluate centering within `SafeArea` usable bounds (not full-screen bounds).
|
|
- **MUST NOT** rely on `Spacer` / proportional flex as the only centering mechanism for critical content.
|
|
- If persistent header/footer regions exist, **MUST** center primary content within the remaining usable region.
|
|
- **MUST** prioritize *visual centering* over purely geometric centering when they differ.
|
|
|
|
## 5) Testing Strategy (MUST)
|
|
|
|
Follow lightweight testing strategy - prioritize value over coverage:
|
|
|
|
**Write tests for:**
|
|
- Model / DTO parsing (json → model)
|
|
- Service layer logic (business rules, API call handling)
|
|
- Complex custom widgets with rich interactions
|
|
|
|
**Skip for:**
|
|
- Simple UI pages, regular buttons, basic layouts
|
|
|
|
## 6) UI Feedback System (MUST)
|
|
|
|
- All user-facing feedback **MUST** use the Toast system.
|
|
- Transient notifications: `Toast.show(...)`
|
|
- Persistent inline form errors: `AppBanner`
|
|
- **MUST NOT** create custom SnackBar/Dialog/Banner feedback components.
|
|
- **MUST NOT** use raw `ScaffoldMessenger` for feedback messaging.
|
|
|
|
## 7) Agent Chat (AG-UI Protocol) (MUST)
|
|
|
|
Agent chat functionality **MUST** follow the AG-UI protocol. **Use the `ag-ui` skill** for protocol reference and implementation guidance.
|
|
|
|
- **MUST** use Server-Sent Events (SSE) for streaming.
|
|
- **MUST** emit required lifecycle events:
|
|
- `RUN_STARTED` is required for every run
|
|
- End with exactly one of: `RUN_FINISHED` or `RUN_ERROR`
|
|
- **MUST** follow standard text streaming flow:
|
|
- `TEXT_MESSAGE_START` → `TEXT_MESSAGE_CONTENT` (delta) → `TEXT_MESSAGE_END`
|
|
- **MUST** support the standard AG-UI event type set as defined in the spec.
|
|
- **MUST NOT** return non-streaming responses for agent chat.
|
|
- **MUST NOT** omit required lifecycle events.
|
|
- **MUST NOT** use non-AG-UI event formats (except where the spec explicitly allows).
|