@dtt_siye/atool 1.3.0 → 1.4.0

package/skills/project-analyze/rules/mobile-flutter.md

@@ -1,315 +1,80 @@
 # Flutter / Dart 项目分析规则
 
-## 分析粒度
+> **编码规范**：本规则不包含编码规范内容。Phase 2.5 精炼阶段会自动加载 `flutter-conventions` skill 作为规范约束。
 
-按 Feature 模块和分层架构（Pages / Widgets / Providers / Services / Models）进行分析。
+## 模块发现策略
 
-```
-MaterialApp / runApp
-    ↓
-Navigator / GoRouter（路由）
-    ↓
-Pages / Screens（页面）
-    ↓
-Widgets（组件）
-    ↓
-ChangeNotifier / Riverpod / Bloc（状态管理）
-    ↓
-Repository / Service（数据层）
-    ↓
-Models / Entities（数据模型）
-```
-
-## 目录扫描策略
-
-### 1. 识别项目结构
-
-**信号文件检测：**
-- `pubspec.yaml` → Flutter/Dart 项目
-- `lib/` → Dart 源码目录
-- `android/`, `ios/`, `web/`, `macos/`, `linux/`, `windows/` → 平台目录
-
-### 2. 识别状态管理方案
-
-**从 `pubspec.yaml` 的 dependencies 检测：**
-- Provider: `provider` 依赖
-- Riverpod: `flutter_riverpod`, `hooks_riverpod` 依赖
-- BLoC: `flutter_bloc`, `equatable` 依赖
-- GetX: `get` 依赖
-- MobX: `mobx`, `flutter_mobx` 依赖
-
-### 3. 识别路由方案
-
-- GoRouter: `go_router` 依赖 + `GoRouter` 配置
-- AutoRoute: `auto_route` 依赖 + `@RoutePage()` 注解
-- Navigator 1.0: `Navigator.push()` 调用
-- GetX: `Get.to()` / `GetPage()` 调用
-
-### 4. 依赖提取
-
-从 `pubspec.yaml` 提取：
-
-| 类别 | 常见依赖 |
-|------|----------|
-| 网络 | dio, http, retrofit |
-| 状态管理 | provider, riverpod, flutter_bloc, get |
-| 路由 | go_router, auto_route |
-| 本地存储 | shared_preferences, hive, isar, drift |
-| DI | get_it, injectable, riverpod |
-| UI | cached_network_image, shimmer, lottie |
-| 序列化 | json_serializable, freezed, dart_mappable |
-
-### 5. 按层扫描路径
-
-- **Pages/Screens**: `lib/screens/`, `lib/pages/`, `lib/views/`
-- **Widgets**: `lib/widgets/`, `lib/components/`, `lib/ui/`
-- **状态管理**: `lib/providers/`, `lib/bloc/`, `lib/cubit/`, `lib/notifiers/`
-- **Models**: `lib/models/`, `lib/entities/`
-- **Services**: `lib/services/`, `lib/repositories/`
-- **Routes**: `lib/routes/`, `lib/navigation/`, `lib/app_router.dart`
-- **Utils**: `lib/utils/`, `lib/helpers/`, `lib/constants/`
-- **Theme**: `lib/theme/`, `lib/styles/`
-
-## 各层提取规则
-
-### 层 1: 路由层
-
-**扫描文件**: `lib/app_router.dart`, `lib/routes/**/*.dart`, `lib/navigation/**/*.dart`
-
-**提取内容**:
-- 路由配置（路径 + 对应 Widget + 参数）
-- 嵌套路由（ShellRoute / 子路由）
-- 路由守卫（重定向逻辑、认证检查）
-- Deep Link 配置
-
-**输出示例**:
-```
-### 路由结构（GoRouter）
-- **文件**: `lib/app_router.dart`
-- **路由配置**:
-  | 路径 | 目标 Widget | 参数 | 守卫 |
-  |------|-------------|------|------|
-  | / | SplashScreen | - | - |
-  | /login | LoginPage | - | 已登录→重定向/home |
-  | /home | HomePage | - | 需认证 |
-  | /profile/:userId | ProfilePage | userId: String | 需认证 |
-  | /settings | SettingsPage | - | 需认证 |
-- **嵌套路由**: /home 下包含 /home/feed, /home/search, /home/profile (BottomNavigation)
-- **认证守卫**: redirect 检查 authProvider.isAuthenticated
-```
-
-### 层 2: 页面层
-
-**扫描文件**: `lib/pages/**/*.dart`, `lib/screens/**/*.dart`
-
-**提取内容**:
-- 页面 Widget 类名 + 路径
-- State 管理方式（StatefulWidget / StatelessWidget + Provider）
-- `build()` 方法中的主要子 Widget（1-2 层）
-- 生命周期方法（initState, dispose）
-- 使用的 Provider / Bloc
-
-**输出示例**:
-```
-### HomePage
-- **路径**: `lib/pages/home/home_page.dart`
-- **类型**: StatefulWidget
-- **State**: _HomePageState
-- **build() 主要结构**:
-  Scaffold(
-    appBar: AppBar(title: Text('首页')),
-    body: _buildBody(),    // TabBarView(FeedPage, SearchPage, ProfilePage)
-    bottomNavigationBar: MainBottomNavBar(onTap: _onTabTapped),
-  )
-- **Provider 依赖**: feedProvider (Watch), authProvider (Read)
-- **生命周期**:
-  | 方法 | 行为 |
-  |------|------|
-  | initState() | 初始化 TabController, 加载用户信息 |
-  | dispose() | 释放 TabController |
-```
-
-### 层 3: Widget 层
+从 `pubspec.yaml` 和 `lib/` 目录结构识别模块边界：
 
-**扫描文件**: `lib/widgets/**/*.dart`, `lib/components/**/*.dart`
+- `pubspec.yaml` → 解析 `dependencies` / `dev_dependencies`，识别状态管理和路由方案
+- `lib/features/{name}/` → Feature-first 目录结构，每个 feature 子目录视为独立模块
+- `lib/screens/` / `lib/pages/` → 每个子目录视为独立模块
+- `lib/services/` / `lib/repositories/` → 数据层模块
+- `lib/widgets/` / `lib/components/` → 3+ 文件的子目录视为独立组件模块
+- 平台目录（`android/`, `ios/`, `web/`）→ 跳过，不分析原生代码
 
-**提取内容**:
-- Widget 类名 + 类型（StatefulWidget / StatelessWidget）
-- 构造参数（命名参数 + 类型 + 默认值）
-- `build()` 方法中的子 Widget
-- 动画配置（AnimationController, Tween）
+**不视为独立模块**：`main.dart` / `app.dart`（入口文件）、纯 re-export 桶文件、`lib/utils/` / `lib/helpers/` 合并为一个模块、`*.g.dart` / `*.freezed.dart` 生成文件跳过。
 
-**输出示例**:
-```
-### UserAvatar
-- **路径**: `lib/widgets/user_avatar.dart`
-- **类型**: StatelessWidget
-- **构造参数**:
-  | 参数 | 类型 | 必填 | 默认值 | 说明 |
-  |------|------|------|--------|------|
-  | avatarUrl | String? | No | null | 头像 URL |
-  | size | double | No | 48.0 | 头像尺寸 |
-  | name | String | Yes | - | 用于生成默认头像 |
-- **子 Widget**: CachedNetworkImage + fallback (首字母头像)
-```
-
-### 层 4: 状态管理层
-
-#### Provider
-
-**扫描文件**: `lib/providers/**/*.dart`
-
-**提取内容**:
-- Provider 名称 + 类型（ChangeNotifier / FutureProvider / StateNotifier）
-- State 字段（名称 + 类型）
-- 方法（签名 + 说明）
-
-**输出示例**:
-```
-### AuthProvider（ChangeNotifier）
-- **路径**: `lib/providers/auth_provider.dart`
-- **State**:
-  | 字段 | 类型 | 说明 |
-  |------|------|------|
-  | user | User? | 当前用户 |
-  | isLoading | bool | 加载状态 |
-  | isAuthenticated | bool | 是否已认证（getter） |
-- **方法**:
-  | 方法 | 签名 | 说明 |
-  |------|------|------|
-  | login | (String email, String password) → Future<void> | 登录 |
-  | logout | () → Future<void> | 登出 |
-  | updateProfile | (UpdateProfileDTO) → Future<void> | 更新资料 |
-- **持久化**: SharedPreferences (token), Hive (user)
-```
+## 入口识别
 
-#### BLoC
+- **App 入口**：`lib/main.dart` → `runApp(...)` → `MaterialApp` / `CupertinoApp` / `WidgetsApp`
+- **路由入口**：`MaterialApp(home:)` 或 `MaterialApp.router(routerConfig:)`
+- **GoRouter**：`app_router.dart` 中 `GoRouter(routes:)` 定义，含 `initialLocation`
+- **AutoRoute**：`@AutoRouterConfig()` 注解 + `AppRouter.gr.dart` 生成文件
 
-**扫描文件**: `lib/bloc/**/*.dart`, `lib/cubit/**/*.dart`
+## 架构模式识别
 
-**提取内容**:
-- Bloc/Cubit 名称
-- State 类（字段 + 类型）
-- Event/输入（名称 + 关联字段）
-- Emitted States（每个 Event 触发的 State 变化）
+从 `pubspec.yaml` dependencies 检测状态管理方案：
 
-**输出示例**:
-```
-### AuthBloc
-- **路径**: `lib/bloc/auth/auth_bloc.dart`
-- **State**: `AuthState(user: User?, status: AuthStatus, error: String?)`
-- **Events**:
-  | Event | 字段 | 触发的 State 变化 |
-  |-------|------|-------------------|
-  | AuthLoginRequested | email, password | status: loading → authenticated / failure |
-  | AuthLogoutRequested | - | status: authenticated → unauthenticated |
-  | AuthRefreshRequested | - | 重新获取用户信息 |
-```
+| 状态管理 | 识别依赖 | 目录特征 |
+|---------|---------|---------|
+| Provider | `provider` | `lib/providers/` |
+| Riverpod | `flutter_riverpod` / `hooks_riverpod` | `lib/providers/` + `@riverpod` 注解 |
+| BLoC | `flutter_bloc` + `equatable` | `lib/bloc/` / `lib/cubit/` |
+| GetX | `get` | `lib/controllers/` + `Get.to()` |
+| MobX | `mobx` + `flutter_mobx` | `lib/stores/` + `@observable` |
 
-### 层 5: Service / Repository 层
+路由方案检测：`go_router` → GoRouter；`auto_route` → AutoRoute；`Get.to()` → GetX；无路由库 → Navigator 1.0。
 
-**扫描文件**: `lib/services/**/*.dart`, `lib/repositories/**/*.dart`
+整体架构判断：`lib/features/` 存在 → Feature-first；`lib/data/` + `lib/domain/` + `lib/presentation/` → Clean Architecture；无明显分层 → 扁平结构。
 
-**提取内容**:
-- 类名 + 依赖注入方式
-- 方法签名 + API 端点映射
-- 错误处理策略
+## 数据流模式
 
-**输出示例**:
-```
-### UserRepository
-- **路径**: `lib/repositories/user_repository.dart`
-- **依赖**: Dio (http client), UserLocalDataSource
-- **方法**:
-  | 方法 | HTTP | 路径 | 返回类型 |
-  |------|------|------|----------|
-  | getUserProfile() | GET | /api/user/profile | Future<User> |
-  | updateProfile(data) | PUT | /api/user/profile | Future<User> |
-  | changePassword(data) | POST | /api/user/password | Future<void> |
-```
+- **Provider/Riverpod**：`ChangeNotifier.notifyListeners()` → `Consumer` / `ref.watch()` 重建
+- **BLoC**：`Event` → `Bloc.add()` → `emit(State)` → `BlocBuilder` 重建
+- **GetX**：`Rx` 变量 + `.obs` → `Obx(() => ...)` 响应式重建
+- **数据层**：Repository 模式 → `Dio` / `http` 网络请求 → JSON 序列化（`json_serializable` / `freezed`）
 
-### 层 6: 样式/主题层
+## 分析关注点
 
-**扫描文件**: `lib/theme/**/*.dart`, `lib/styles/**/*.dart`
+- **`lib/` 目录结构**：是理解项目架构的核心，需完整列出一级和二级目录
+- **Widget 树入口**：`runApp()` → 根 Widget → 路由配置，是所有页面的起点
+- **`pubspec.yaml` 依赖**：完整提取 dependencies 和 dev_dependencies，识别框架版本
+- **Flutter Bloc/Provider/Riverpod 检测**：状态管理方案决定数据流分析策略
+- **生成文件识别**：`*.g.dart` / `*.freezed.dart` 跳过分析，但需识别其对应的源文件
+- **平台特定代码**：`android/` / `ios/` 中的原生模块仅在有 MethodChannel 桥接时分析
 
-**提取内容**:
-- ThemeData 配置
-- 颜色定义（ColorScheme）
-- 字体配置（TextTheme）
-- 间距系统
-- 自定义组件主题
+## 输出示例
 
-**输出示例**:
-```
-### AppTheme
-- **文件**: `lib/theme/app_theme.dart`
-- **颜色**:
-  | Token | 值 | 用途 |
-  |-------|------|------|
-  | primaryColor | Color(0xFF6750A4) | 主色调 |
-  | onPrimaryColor | Color(0xFFFFFFFF) | 主色上的文字 |
-  | errorColor | Color(0xFFB3261E) | 错误色 |
-- **字体**:
-  | 用途 | 字体族 | 字号 | 字重 |
-  |------|--------|------|------|
-  | headlineLarge | Roboto | 32sp | Bold |
-  | bodyMedium | Roboto | 14sp | Normal |
 ```
+### 项目结构（Feature-first）
+lib/
+  features/
+    auth/       → 认证模块（login, register, forgot_password）
+    home/       → 首页模块（feed, search）
+    profile/    → 用户模块（view, edit, settings）
+  shared/
+    widgets/    → 公共组件
+    services/   → 网络/存储服务
 
-## 输出模板
+### 技术栈检测
+- 状态管理: Riverpod (flutter_riverpod 2.4.0) + hooks_riverpod
+- 路由: GoRouter (go_router 12.1.1), initialLocation: /splash
+- 网络: Dio (dio 5.3.2) + Retrofit
+- 序列化: freezed + json_serializable
 
-### README.md 章节结构
-
-```markdown
-# {项目名}
-
-## 项目概述
-App 功能描述
-
-## 技术栈
-| 技术 | 版本 | 用途 |
-|------|------|------|
-
-## 架构设计
-### 架构图（ASCII）
-### 数据流图
-
-## 路由结构
-路由树 + 参数 + 守卫
-
-## 状态管理
-Provider/BLoC 关系图
-
-## 模块详解
-按 Feature 分组
-
-## 依赖管理
-pubspec.yaml 关键依赖
+### 数据流（Riverpod）
+用户操作 → ref.read(provider.notifier).method()
+  → StateNotifier.state = newState
+  → ref.watch(provider) 重建 UI
 ```
-
-## 模块边界识别
-
-以下目录模式下的每个子目录视为独立模块（L2+ 分析时生成 MODULE-DOC.md）：
-
-| 层 | 扫描路径 | 模块判定规则 | MODULE-DOC slug 来源 |
-|----|----------|-------------|---------------------|
-| 页面/视图层 | `lib/features/{name}/`, `lib/screens/` | 每个子目录 | 目录名 kebab-case |
-| API/服务层 | `lib/services/`, `lib/repositories/` | 每个子目录或文件 | 名称 kebab-case |
-| 状态管理层 | `lib/providers/`, `lib/notifiers/` | 每个文件 | 文件名去后缀 kebab-case |
-| 组件层 | `lib/widgets/` | 3+ 文件的子目录 | 目录名 kebab-case |
-| 数据模型层 | `lib/models/` | 每个文件 | 文件名去后缀 kebab-case |
-
-**不视为独立模块的情况**：
-- 单文件入口（如 `main.dart`, `app.dart`）
-- 纯导出桶文件（仅有 re-export）
-- 工具函数目录（`lib/utils/`, `lib/helpers/`）— 合并为一个模块
-- 生成文件（`*.g.dart`, `*.freezed.dart`）跳过
-- 平台目录（`android/`, `ios/`）跳过
-
-## Token 管理
-
-- 大模块（>20 文件）拆分为子任务
-- 每个子任务分析 ≤10 文件
-- `pubspec.yaml` 分析单独一个子任务
-- 生成的文件（`*.g.dart`, `*.freezed.dart`）跳过或简要分析
-- 平台目录（android/, ios/）不分析