---
name: Flutter App Expert
description: 包含 Flutter 开发的专家级规则、架构规范和最佳实践。
---

# Flutter App Expert Skill

此 Skill 旨在指导 AI 助手作为一名 Flutter 专家进行编码，遵循 Clean Architecture、Riverpod 状态管理和 Freezed 不可变数据模型等业界最佳实践。

## 核心原则

1.  **Clean Architecture (整洁架构)**：严格分层，依赖向内。
2.  **Immutability (不可变性)**：优先使用不可变状态和数据类。
3.  **Feature-First (功能优先)**：按功能模块而非技术层级组织代码。

---

## 1. 架构分层规范

项目必须遵循以下三层架构：

### Domain Layer (核心层)
*   **位置**: `lib/features/<feature_name>/domain/`
*   **内容**: 
    *   `Entities`: 业务对象 (使用 Freezed)。
    *   `Repositories`: 抽象接口定义 (Interface)。
    *   `Failures`: 业务错误定义。
*   **规则**: 
    *   **纯 Dart 代码**，不依赖 Flutter UI 库。
    *   不依赖 Data 层或 Presentation 层。
    *   不包含 JSON 序列化逻辑。

### Data Layer (基础设施层)
*   **位置**: `lib/features/<feature_name>/data/`
*   **内容**:
    *   `Repositories Impl`: 接口的具体实现。
    *   `Data Sources`: 远程 API (Dio) 或本地数据库 (Hive/Drift) 调用。
    *   `DTOs (Models)`: 数据传输对象，负责 JSON 序列化 (使用 json_serializable)。
*   **规则**:
    *   DTO 必须通过 Mapper 转换为 Domain Entity。
    *   Repository 实现不应直接抛出异常，应返回 `Either<Failure, T>` 或抛出自定义业务异常。

### Presentation Layer (表现层)
*   **位置**: `lib/features/<feature_name>/presentation/`
*   **内容**:
    *   `Widgets/Pages`: UI 组件。
    *   `Controllers/Notifiers`: 状态管理 (Riverpod StateNotifier/AsyncNotifier)。
    *   `States`: UI 状态定义 (使用 Freezed)。
*   **规则**:
    *   UI 组件应尽可能为 `StatelessWidget` (配合 `ConsumerWidget`)。
    *   业务逻辑必须委托给 Controller，UI 只负责渲染状态。

---

## 2. 这里的常用库与模式 (Tech Stack)

*   **状态管理**: [Riverpod] (使用 Generator 语法 `@riverpod` 优先)。
*   **数据类**: [Freezed] + [json_serializable]。
*   **导航**: [GoRouter] (强类型路由)。
*   **网络**: [Dio] + [Retrofit] (可选)。
*   **依赖注入**: [Riverpod] 本身即为 DI 容器。

---

## 3. 这里的编码规范 (Coding Rules)

### 通用
*   文件名使用 `snake_case` (如 `user_repository.dart`)。
*   类名使用 `PascalCase` (如 `UserRepository`)。
*   变量名使用 `camelCase` (如 `currentUser`)。
*   优先使用 `const` 构造函数。

### Riverpod 规范
*   避免在 Repository 中使用 `ref`。
*   优先使用 `AsyncValue` 处理异步状态 (Loading/Error/Data)。
*   **示例**:
    ```dart
    @riverpod
    class AuthController extends _$AuthController {
      @override
      FutureOr<void> build() {}

      Future<void> signIn() async {
        state = const AsyncLoading();
        state = await AsyncValue.guard(() => _repository.signIn());
      }
    }
    ```

### Freezed 规范
*   **Entity 定义**:
    ```dart
    @freezed
    class User with _$User {
      const factory User({
        required String id,
        required String name,
      }) = _User;
    }
    ```
*   **State 定义**:
    ```dart
    @freezed
    class LoginState with _$LoginState {
      const factory LoginState.initial() = _Initial;
      const factory LoginState.loading() = _Loading;
      const factory LoginState.success() = _Success;
      const factory LoginState.error(String message) = _Error;
    }
    ```

---

## 4. 这里的 AI 提示词建议 (System Prompts)

当您要求 AI 写代码时，可以附加以下指令：

> "请使用 Flutter Clean Architecture 风格，基于 Riverpod 和 Freezed 实现。请确保 Domain 层不依赖 Data 层，UI 逻辑与业务逻辑分离。"

> "生成代码时，请优先使用 Flutter 3.x 新特性，使用 GoRouter 进行路由管理。"

> "为这个功能编写 Widget Test，遵循 Given-When-Then 格式，并 Mock 相关的 Providers。"

---

## 5. 禁止行为

*   ❌ 禁止在 Domain 层引入 `flutter/material.dart`。
*   ❌ 禁止在 UI 中直接调用 API，必须通过 Controller。
*   ❌ 禁止手动编写 JSON 解析代码，必须使用 `json_serializable`。
*   ❌ 禁止使用 `GetX` (除非项目明确指定)，保持架构统一。