@dtt_siye/atool 1.3.0 → 1.3.1

package/skills/project-analyze/rules/android.md

@@ -1,282 +1,83 @@
 # Android / Kotlin 项目分析规则
 
-## 分析粒度
+> **编码规范**：本规则不包含编码规范内容。Phase 2.5 精炼阶段会自动加载 `android-conventions` skill 作为规范约束。
 
-按 Feature Module 和 MVVM+ 分层架构进行分析。
+## 模块发现策略
 
-```
-Application (Application 类)
-    ↓
-DI Module（依赖注入：Hilt / Koin）
-    ↓
-Navigation（导航：Jetpack Navigation / Compose Navigation）
-    ↓
-Activity / Fragment / Composable Screen
-    ↓
-ViewModel
-    ↓
-Repository
-    ↓
-Data Source（Remote: Retrofit + Local: Room / DataStore）
-    ↓
-Model / Entity（数据模型）
-```
-
-## 目录扫描策略
-
-### 1. 识别项目类型
-
-**信号文件检测：**
-- 单模块: `app/` 下直接包含源码
-- 多模块: `settings.gradle` 中 `include` 列表
-- Compose 项目: `build.gradle` 中 `compose = true`
-- KMP 项目: `shared/` 模块 + `build.gradle.kts`
-
-### 2. 识别架构模式
-
-- **MVVM + Repository**: ViewModel + Repository + Room
-- **MVI**: Intent → Reducer → State → View
-- **Clean Architecture**: Domain / Data / Presentation 三层
-
-### 3. 依赖提取
-
-从 `build.gradle` / `build.gradle.kts` 提取：
-
-| 类别 | 常见依赖 |
-|------|----------|
-| Compose | compose-bom, compose-ui, compose-material3 |
-| Navigation | navigation-compose, navigation-fragment |
-| DI | hilt-android, koin-android |
-| 网络 | retrofit, okhttp, ktor |
-| 图片 | coil-compose, glide |
-| 数据库 | room-runtime, datastore-preferences |
-| 异步 | kotlinx-coroutines, rxjava |
-| 序列化 | kotlin-serialization, moshi, gson |
-| DI | hilt-android-compiler, koin |
-| 测试 | junit, mockk, turbine |
-
-### 4. 按层扫描路径
-
-- **UI 层**: `*/ui/`, `*/screens/`, `*/compose/`
-- **Activity/Fragment**: `*/activities/`, `*/fragments/`
-- **ViewModel**: `*/viewmodel/`, `*/viewmodels/`
-- **Repository**: `*/repository/`, `*/repositories/`
-- **数据源**: `*/data/remote/`, `*/data/local/`, `*/datasource/`
-- **Model**: `*/model/`, `*/models/`, `*/entity/`
-- **DI**: `*/di/`, `*/hilt/`
-
-## 各层提取规则
+从 Gradle 构建文件识别模块边界：
 
-### 层 1: UI 层
+- `settings.gradle` / `settings.gradle.kts` → `include(":app", ":feature-home", ":core")` 列出所有模块
+- 单模块项目：`app/src/main/java/` 下按 `feature/` 包名识别功能边界
+- 多模块项目：每个 Gradle 子模块视为独立分析单元
+- KMP 项目：`shared/` 模块单独分析，区分 `commonMain` / `androidMain` / `iosMain`
+- `build.gradle.kts` 中 `compose = true` → Jetpack Compose 项目
+- `libs.versions.toml` → Version Catalog，提取所有依赖版本
 
-#### Jetpack Compose
+**不视为独立模块**：`MainActivity.kt` / `Application.kt`（入口文件）、`util/` / `helper/` / `extension/` 合并为一个模块、`*.generated.kt` / `BuildConfig` 跳过。
 
-**扫描文件**: `*Screen.kt`, `*Page.kt`, 含 `@Composable` 的文件
+## 入口识别
 
-**提取内容**:
-- `@Composable` 函数签名 + 参数
-- `Modifier` 链
-- 状态管理（`remember`, `mutableStateOf`, `collectAsState`）
-- 子 Composable 结构（1-2 层）
-- `@Preview` 注解
+- **Application 入口**：`AndroidManifest.xml` 中 `android:name=".XXXApplication"` → 继承 `Application` 的类
+- **Activity 入口**：`<intent-filter><action android:name="android.intent.action.MAIN" /></intent-filter>` → `MainActivity`
+- **Hilt 注入**：`@HiltAndroidApp` 注解在 Application 类上
+- **Navigation 入口**：`NavHostFragment` + `NavGraph`（`res/navigation/*.xml`）或 `NavHost` Composable
 
-**输出示例**:
-```
-### UserListScreen
-- **路径**: `ui/screens/user/UserListScreen.kt`
-- **签名**:
-  ```kotlin
-  @Composable
-  fun UserListScreen(
-      navController: NavController,
-      viewModel: UserListViewModel = hiltViewModel()
-  )
-  ```
-- **状态收集**:
-  | State | 来源 | 用途 |
-  |-------|------|------|
-  | users | viewModel.users.collectAsState() | 用户列表 |
-  | isLoading | viewModel.isLoading.collectAsState() | 加载状态 |
-  | searchQuery | viewModel.searchQuery.collectAsState() | 搜索关键词 |
-- **UI 结构**:
-  Scaffold(topBar = UserListTopBar(), floatingActionButton = AddUserFAB())
-    → LazyColumn(items = users)
-      → UserListItem(user, onClick = { nav to detail })
-- **Modifier 链**: Modifier.fillMaxSize().padding(16.dp)
-```
+## 架构模式识别
 
-#### XML Layout
+| 架构 | 识别特征 |
+|------|---------|
+| MVVM + Repository | `ViewModel` + `Repository` + `Room` / `Retrofit` |
+| MVI | `Intent` → `Reducer` → `State`（sealed class）→ View |
+| Clean Architecture | `domain/` + `data/` + `presentation/` 三层目录 |
 
-**扫描文件**: `res/layout/*.xml`
+DI 框架检测：
+- **Hilt**：`build.gradle` 中 `hilt-android` + `@HiltViewModel` / `@AndroidEntryPoint`
+- **Koin**：`koin-android` 依赖 + `startKoin { }` + `viewModel { }` DSL
 
-**提取内容**:
-- Layout 层级结构
-- include / merge 标签
-- 自定义 View
+UI 框架检测：`compose-bom` 依赖 → Jetpack Compose；`res/layout/*.xml` → XML Layout；两者并存 → 混合。
 
-### 层 2: ViewModel 层
+## 数据流模式
 
-**扫描文件**: `*ViewModel.kt`
+- **Compose + StateFlow**：`ViewModel.uiState: StateFlow<UiState>` → `collectAsState()` → Composable 重组
+- **LiveData（旧版）**：`ViewModel.liveData.observe(viewLifecycleOwner)` → Fragment/Activity 更新 UI
+- **MVI**：`viewModel.processIntent(intent)` → `reducer(state, intent)` → `emit(newState)` → UI 收集
+- **Repository 数据流**：`RemoteDataSource`（Retrofit）+ `LocalDataSource`（Room）→ Repository 聚合 → ViewModel
 
-**提取内容**:
-- ViewModel 类名 + 构造参数（`@AssistedInject`）
-- UI State 数据类（字段 + 类型）
-- Action / Intent（用户操作）
-- Effect / Event（一次性事件）
-- 依赖的 Repository
+## 分析关注点
 
-**输出示例**:
-```
-### UserListViewModel
-- **路径**: `ui/screens/user/UserListViewModel.kt`
-- **注入**: @HiltViewModel
-- **UI State**:
-  ```kotlin
-  data class UserListState(
-      val users: List<UserVO> = emptyList(),
-      val isLoading: Boolean = false,
-      val searchQuery: String = "",
-      val error: String? = null
-  )
-  ```
-- **Actions**:
-  | Action | 参数 | 说明 |
-  |--------|------|------|
-  | loadUsers | - | 初始加载 |
-  | searchUsers | query: String | 搜索过滤 |
-  | deleteUser | userId: Long | 删除用户 |
-  | refresh | - | 下拉刷新 |
-- **Effects**:
-  | Effect | 载荷 | 说明 |
-  |--------|------|------|
-  | NavigateToDetail | userId: Long | 导航到详情 |
-  | ShowToast | message: String | 显示提示 |
-- **依赖**: UserRepository
-```
+- **Gradle 模块发现**：`settings.gradle` 是多模块项目的入口，必须先解析模块依赖关系图
+- **Activity/Fragment 入口**：通过 `AndroidManifest.xml` 枚举所有 Activity，识别 exported 的入口点
+- **Jetpack Compose vs XML Layout**：`build.gradle` 中 `buildFeatures { compose = true }` 是关键标志
+- **Hilt/Dagger 注入检测**：`@Module` + `@Provides` / `@Binds` → 识别依赖注入图，影响模块耦合分析
+- **Room 数据库**：`@Database` + `@Entity` + `@Dao` → 数据层核心，需提取 Entity 关系和 Dao 方法
+- **Navigation Component**：`NavGraph`（XML 或 Composable）是页面跳转关系的权威来源
 
-### 层 3: Repository 层
+## 输出示例
 
-**扫描文件**: `*Repository.kt`
-
-**输出示例**:
-```
-### UserRepository
-- **路径**: `data/repository/UserRepositoryImpl.kt`
-- **接口**: `domain/repository/UserRepository.kt`
-- **数据源**: UserRemoteDataSource, UserLocalDataSource (Room)
-- **方法**:
-  | 方法 | 签名 | 说明 |
-  |------|------|------|
-  | getUsers | suspend () → List<User> | 先本地后远程 |
-  | getUserById | suspend (Long) → User | 查询详情 |
-  | saveUsers | suspend (List<User>) → Unit | 缓存到本地 |
 ```
-
-### 层 4: Room 数据库分析
-
-**扫描文件**: `*Entity.kt`, `*Dao.kt`, `*Database.kt`
-
-**输出示例**:
-```
-### AppDatabase
-- **文件**: `data/local/AppDatabase.kt`
-- **版本**: 3
-- **Entities**: UserEntity, SettingsEntity
-- **Dao**:
-  | Dao | 方法 | 返回类型 |
-  |-----|------|----------|
-  | UserDao | getAllUsers() | Flow<List<UserEntity>> |
-  | UserDao | getUserById(id) | Flow<UserEntity?> |
-  | UserDao | insertUsers(users) | List<Long> |
-  | UserDao | deleteUser(id) | Int |
-- **Migration**: 2→3 (添加 avatar 字段)
-```
-
-### 层 5: DI 分析
-
-**扫描文件**: `*Module.kt` (Hilt), `*Module.kt` (Koin)
-
-**输出示例**:
-```
-### Hilt Modules
+### 模块结构（多模块）
+settings.gradle 模块:
+  :app          → 主模块（Application + MainActivity）
+  :feature:home → 首页功能模块
+  :feature:user → 用户功能模块
+  :core:network → 网络层（Retrofit + OkHttp）
+  :core:database→ 数据库层（Room）
+  :core:common  → 公共工具
+
+模块依赖图:
+  :app → :feature:home, :feature:user
+  :feature:* → :core:network, :core:database, :core:common
+
+### 技术栈检测
+- UI: Jetpack Compose (compose-bom 2024.01.00)
+- 架构: MVVM + Clean Architecture
+- DI: Hilt (hilt-android 2.48)
+- 数据库: Room 2.6.1
+- 网络: Retrofit 2.9.0 + OkHttp 4.12
+
+### DI 模块概览
 | Module | Provides | Scope |
 |--------|----------|-------|
-| NetworkModule | OkHttpClient, Retrofit, ApiServices | Singleton |
-| DatabaseModule | AppDatabase, UserDAO | Singleton |
-| RepositoryModule | UserRepository | Singleton |
-```
-
-### 层 6: Navigation 分析
-
-**扫描文件**: `NavGraph.kt`, 含 `NavHost` 的文件
-
-**输出示例**:
-```
-### 导航图
-| 路由 | 目标 | 参数 | 动画 |
-|------|------|------|------|
-| user_list | UserListScreen | - | - |
-| user_detail | UserDetailScreen | userId: Long | slideInRight |
-| user_edit | UserEditScreen | userId: Long? | slideInRight |
+| NetworkModule | OkHttpClient, Retrofit | Singleton |
+| DatabaseModule | AppDatabase, UserDao | Singleton |
 ```
-
-## 输出模板
-
-### README.md 章节结构
-
-```markdown
-# {App 名称}
-
-## 项目概述
-App 功能描述
-
-## 技术栈
-| 技术 | 版本 | 用途 |
-|------|------|------|
-
-## 架构设计
-### 架构图（ASCII）
-### 数据流图
-
-## 模块结构
-Gradle 模块依赖关系
-
-## 导航结构
-路由表 + 参数
-
-## 数据模型
-Entity + DTO + UI State
-
-## DI 配置
-Hilt / Koin 模块
-
-## 构建 & 部署
-Gradle 命令 + 变体
-```
-
-## 模块边界识别
-
-以下目录模式下的每个子目录视为独立模块（L2+ 分析时生成 MODULE-DOC.md）：
-
-| 层 | 扫描路径 | 模块判定规则 | MODULE-DOC slug 来源 |
-|----|----------|-------------|---------------------|
-| UI 层 | `app/src/main/java/**/ui/`, `app/src/main/java/**/screens/` | 每个子目录 | 目录名 kebab-case |
-| Repository 层 | `app/src/main/java/**/repository/` | 每个子目录 | 目录名 kebab-case |
-| ViewModel 层 | `app/src/main/java/**/viewmodel/` | 每个子目录 | 目录名 kebab-case |
-| 组件层 | `app/src/main/java/**/components/` | 3+ 文件的子目录 | 目录名 kebab-case |
-| 数据模型层 | `app/src/main/java/**/model/` | 每个文件 | 文件名去后缀 kebab-case |
-
-**不视为独立模块的情况**：
-- 单文件入口（如 `MainActivity.kt`, `Application.kt`）
-- 纯导出桶文件（仅有 re-export）
-- 工具函数目录（`util/`, `helper/`, `extension/`）— 合并为一个模块
-- 生成文件（`*.generated.kt`, `BuildConfig`）跳过
-
-## Token 管理
-
-- 大模块（>20 文件）拆分为子任务
-- 每个子任务分析 ≤10 文件
-- `build.gradle` 依赖分析单独一个子任务
-- layout XML / Compose 文件单独分组分析
-- 生成文件（`*.generated.kt`, `BuildConfig`）跳过
-- 测试文件（`androidTest/`, `test/`）单独分析