Files

T

qzl 01c36eb32e refactor: 移除前端 Mock API，新增共享组件，优化认证流程

- 删除 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 文档

2026-03-12 16:41:45 +08:00

3.6 KiB

Raw Blame History

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).

3.6 KiB Raw Blame History