@dtt_siye/atool 1.3.0 → 1.4.0

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

@@ -1,323 +1,78 @@
 # iOS / Swift 项目分析规则
 
-## 分析粒度
+> **编码规范**：本规则不包含编码规范内容。Phase 2.5 精炼阶段会自动加载 `swift-conventions` skill 作为规范约束。
 
-按 Feature 模块和 MVVM / MVVM+Coordinator 层次进行分析。
+## 模块发现策略
 
-```
-App Entry Point
-    ↓
-Coordinator / Router（导航）
-    ↓
-ViewController / SwiftUI View（视图）
-    ↓
-ViewModel / ObservableObject（逻辑）
-    ↓
-Model / Entity（数据）
-    ↓
-Service / Repository（网络/持久化）
-    ↓
-Extensions / Utils（工具）
-```
-
-## 目录扫描策略
-
-### 1. 识别项目类型
-
-**信号文件检测：**
-- `.xcodeproj` / `.xcworkspace` → Xcode 项目
-- `Package.swift` → Swift Package
-- 依赖管理：SPM（Package Dependencies）、CocoaPods（`Podfile`）、Carthage（`Cartfile`）
-
-### 2. 识别架构模式
-
-- **MVVM**: ViewModels 目录 + Bindings / Combine
-- **MVC**: Controllers 目录，无 ViewModel
-- **VIPER**: View / Interactor / Presenter / Entity / Router 目录
-- **Clean Architecture**: Domain / Data / Presentation 分层
-- **SwiftUI + TCA**: Reducers / Effects / Store 模式
-
-### 3. 识别 UI 框架
-
-- **UIKit**: `import UIKit`, `.storyboard`, `.xib`, `ViewController`
-- **SwiftUI**: `import SwiftUI`, `ContentView: View`, `@StateObject`
-- **混合**: 两者并存（`UIHostingController` 桥接）
-
-### 4. 依赖提取
-
-从 `Package.swift` / `Podfile` / `Cartfile` 提取：
-
-| 类别 | 常见依赖 |
-|------|----------|
-| 网络 | Alamofire, Moya, URLSession |
-| 响应式 | RxSwift, Combine |
-| DI | Swinject, Kodein, Factory |
-| 存储 | CoreData, Realm, SwiftData, UserDefaults |
-| 导航 | RxFlow, Coordinator Pattern |
-| UI | SnapKit, Kingfisher, Lottie |
-| 测试 | XCTest, Quick/Nimble, OHHTTPStubs |
-
-### 5. 按层扫描路径
-
-- **View 层**: `*/Views/`, `*/Screens/`, `*/UI/`, `*/Scenes/`
-- **ViewModel 层**: `*/ViewModels/`, `*/Presenters/`, `*/Reducers/`
-- **Model 层**: `*/Models/`, `*/Entities/`, `*/DTOs/`
-- **Coordinator/Router 层**: `*/Coordinators/`, `*/Routers/`, `*/Navigation/`
-- **Service 层**: `*/Services/`, `*/Network/`, `*/API/`, `*/Repositories/`
-- **Extensions**: `*/Extensions/`, `*/+Extensions/`
-- **Resources**: `*/Resources/`, `*/Assets.xcassets/`
-
-## 各层提取规则
-
-### 层 1: Coordinator / Router 导航层
-
-**扫描文件**: `*Coordinator.swift`, `*Router.swift`, `*Navigator.swift`
-
-**提取内容**:
-- Coordinator 类名 + 管理的页面列表
-- 导航方法（方法签名 + 目标页面 + 传递的参数）
-- 导航模式（push / present / modal / sheet）
-- Deep Link 处理
-
-**输出示例**:
-```
-### AppCoordinator
-- **路径**: `Coordinators/AppCoordinator.swift`
-- **管理的页面**: LoginFlow → MainTabBar → (Home, Profile, Settings)
-- **导航方法**:
-  | 方法 | 目标 | 参数 | 导航方式 |
-  |------|------|------|----------|
-  | start() | LoginViewController | - | window.rootViewController |
-  | showMain() | MainTabBarController | UserSession | rootViewController 替换 |
-  | showProfile(userId:) | ProfileViewController | userId: String | push |
-  | showSettings() | SettingsViewController | - | present (modal) |
-  | showEditProfile() | EditProfileViewController | - | present (fullScreen) |
-```
-
-### 层 2: ViewController / SwiftUI View 层
-
-**扫描文件**: `*ViewController.swift`, `*View.swift`（SwiftUI）
-
-#### UIKit ViewController
-
-**提取内容**:
-- 类名 + 继承关系
-- IBOutlet 列表（属性名 + 类型）
-- IBAction 列表（方法名 + 关联事件）
-- 生命周期方法（viewDidLoad, viewWillAppear 等）
-- 使用的 ViewModel
-- UI 配置逻辑（UITableView 代理/数据源、UICollectionView 等）
-
-**输出示例**:
-```
-### UserListViewController
-- **路径**: `Scenes/User/UserListViewController.swift`
-- **继承**: UIViewController
-- **ViewModel**: UserListViewModel
-- **IBOutlet**:
-  | 属性 | 类型 | 关联 UI |
-  |------|------|---------|
-  | tableView | UITableView | 用户列表 |
-  | searchController | UISearchController | 搜索栏 |
-  | activityIndicator | UIActivityIndicatorView | 加载指示器 |
-- **IBAction**:
-  | 方法 | 关联事件 | 说明 |
-  |------|----------|------|
-  | @IBAction addButtonTapped | UIBarButtonItem.tap | 新增用户 |
-- **生命周期**:
-  | 方法 | 行为 |
-  |------|------|
-  | viewDidLoad() | 绑定 ViewModel、配置 tableView、触发初始加载 |
-  | viewWillAppear() | 刷新数据 |
-- **UITableView 配置**:
-  - Cell: UserTableViewCell (register nib)
-  - 高度: 80pt (自动布局)
-  - 下拉刷新: UIRefreshControl → viewModel.reload()
-```
+从构建文件识别模块边界：
 
-#### SwiftUI View
+- `.xcodeproj` / `.xcworkspace` → 扫描 Targets 和 Schemes
+- `Package.swift` → 解析 `.target()` / `.product()` 声明
+- `Podfile` → 解析 `pod` 依赖列表，识别 CocoaPods 模块
+- `Cartfile` → 识别 Carthage 依赖模块
+- 多 Target 项目：每个 Target 视为独立模块
+- Swift Package Manager 本地 package：`dependencies:` 中的 `.package(path:)` 引用
 
-**提取内容**:
-- View 结构体名
-- `@State` / `@Binding` / `@ObservedObject` / `@EnvironmentObject` 属性
-- `body` 中的主要子视图（1-2 层）
-- `.modifier()` 链（导航、样式修饰）
-- `.sheet()` / `.fullScreenCover()` / `.navigationDestination()` 修饰
+**不视为独立模块**：单文件入口（`App.swift`, `main.swift`）、`Utils/`/`Helpers/` 合并为一个模块、`*.generated.swift` 跳过。
 
-**输出示例**:
-```
-### UserProfileView
-- **路径**: `Views/Profile/UserProfileView.swift`
-- **属性**:
-  | 属性 | 包装器 | 类型 | 说明 |
-  |------|--------|------|------|
-  | viewModel | @StateObject | UserProfileViewModel | 页面 VM |
-  | isEditing | @State | Bool | 编辑模式 |
-  | router | @EnvironmentObject | AppRouter | 导航 |
-- **body 主要结构**:
-  ScrollView {
-    VStack {
-      ProfileHeaderView(viewModel: viewModel)
-        .sheet(isPresented: $isEditing) { EditProfileView() }
-      StatsGridView(stats: viewModel.stats)
-      SettingsListView(items: viewModel.settings)
-    }
-  }
-  .navigationTitle(viewModel.userName)
-  .task { await viewModel.loadProfile() }
-```
+## 入口识别
 
-### 层 3: ViewModel 层
+| 类型 | 识别特征 | 文件 |
+|------|---------|------|
+| UIKit App | `@UIApplicationMain` / `@main` + `AppDelegate: UIResponder` | `AppDelegate.swift` |
+| Scene-based UIKit | `UIWindowSceneDelegate` + `SceneDelegate.swift` | `SceneDelegate.swift` |
+| SwiftUI App | `@main struct XXXApp: App` + `WindowGroup` | `XXXApp.swift` |
+| Swift Package | `Package.swift` 中的 executable target | `main.swift` |
 
-**扫描文件**: `*ViewModel.swift`, `*Presenter.swift`, `*Reducer.swift`
+页面入口：`*Coordinator.swift` / `*Router.swift`（导航层）→ `*ViewController.swift` / `*View.swift`（视图层）。
 
-**提取内容**:
-- 类名 + 遵循的协议（ObservableObject, Observable）
-- Published / @Observable 属性（名称 + 类型 + 说明）
-- Input / Action（用户操作触发的动作）
-- Output / State 变化
-- 依赖的 Service / Repository
+## 架构模式识别
 
-**输出示例**:
-```
-### UserListViewModel
-- **路径**: `ViewModels/UserListViewModel.swift`
-- **协议**: ObservableObject
-- **Published 属性**:
-  | 属性 | 类型 | 初始值 | 说明 |
-  |------|------|--------|------|
-  | users | [UserVO] | [] | 用户列表 |
-  | isLoading | Bool | false | 加载状态 |
-  | errorMessage | String? | nil | 错误信息 |
-  | searchText | String | "" | 搜索关键词 |
-- **方法**:
-  | 方法 | 参数 | 返回值 | 说明 |
-  |------|------|--------|------|
-  | loadUsers() | - | async | 加载用户列表 |
-  | deleteUser(_:) | UserVO | async | 删除用户 |
-  | searchUsers(_:) | String | - | 搜索过滤 |
-- **依赖**: UserRepository（网络请求）, UserCacheService（本地缓存）
-```
+| 架构 | 识别特征 |
+|------|---------|
+| MVVM | `ViewModels/` 目录 + `ObservableObject` / `@Observable` 协议 |
+| MVC | `Controllers/` 目录，无 ViewModel |
+| VIPER | `View/Interactor/Presenter/Entity/Router` 五个目录或文件后缀 |
+| Clean Architecture | `Domain/Data/Presentation` 三层目录 |
+| TCA (The Composable Architecture) | `Reducers/`、`Effects/`、`Store` 模式 |
+| SwiftUI + TCA | `@Reducer`、`ComposableArchitecture` import |
 
-### 层 4: Model / Entity 层
+UI 框架检测：`import UIKit` + `.storyboard`/`.xib` → UIKit；`import SwiftUI` + `: View` → SwiftUI；两者并存（`UIHostingController`）→ 混合。
 
-**扫描文件**: `Models/**/*.swift`, `Entities/**/*.swift`
+## 数据流模式
 
-**提取内容**:
-- struct / class 名 + 遵循的协议（Codable, Identifiable, Hashable）
-- 属性列表（名称 + 类型 + 编码键）
-- 关联模型（嵌套结构体、关联关系）
-
-**输出示例**:
-```
-### User
-- **路径**: `Models/User.swift`
-- **类型**: struct, Codable, Identifiable
-- **属性**:
-  | 属性 | 类型 | CodingKey | 说明 |
-  |------|------|-----------|------|
-  | id | String | "id" | 唯一标识 |
-  | name | String | "name" | 用户名 |
-  | email | String | "email" | 邮箱 |
-  | avatar | URL? | "avatar_url" | 头像 |
-  | createdAt | Date | "created_at" | 注册时间 |
-```
+- **Combine**：`@Published`、`PassthroughSubject`、`AnyPublisher` → 响应式数据流
+- **RxSwift**：`Observable`、`Driver`、`Signal`、`DisposeBag`
+- **async/await**：`async func` + `await` + `Task { }` → 结构化并发
+- **状态管理**：`@StateObject`（所有者）/ `@ObservedObject`（借用）/ `@EnvironmentObject`（全局）
 
-### 层 5: Service / Repository 层
+## 分析关注点
 
-**扫描文件**: `Services/**/*.swift`, `Network/**/*.swift`, `Repositories/**/*.swift`
+- **Target/Scheme 发现**：多 Target 项目需枚举所有 Target，区分 App/Framework/Test Target
+- **UIKit vs SwiftUI 混合**：检测 `UIHostingController` 和 `UIViewRepresentable` 桥接点
+- **App Delegate vs Scene Delegate**：iOS 13+ 迁移到 Scene-based lifecycle，需识别两种入口
+- **SPM 本地模块**：`Package.swift` 中 `.package(path: "../")` 引用的本地 package 视为独立模块
+- **Coordinator/Router 层**：是导航逻辑的核心，需完整提取页面跳转关系图
+- **依赖注入**：Swinject / Factory / 手动 DI → 影响模块间耦合分析
 
-**提取内容**:
-- 协议定义（方法签名）
-- 实现类（网络层使用 Alamofire / URLSession）
-- API 端点映射
-- 请求/响应模型
-- 错误处理策略
+## 输出示例
 
-**输出示例**:
 ```
-### UserRepository
-- **协议文件**: `Repositories/UserRepositoryProtocol.swift`
-- **实现文件**: `Repositories/UserRepository.swift`
-- **API 方法**:
-  | 方法 | HTTP | 路径 | 参数 | 返回类型 |
-  |------|------|------|------|----------|
-  | getUsers(page:limit:) | GET | /api/users | page, limit | Result<[User], APIError> |
-  | getUser(id:) | GET | /api/users/:id | id | Result<User, APIError> |
-  | createUser(_:) | POST | /api/users | UserCreateDTO | Result<User, APIError> |
-```
-
-### 层 6: 响应式链分析（RxSwift / Combine）
-
-**扫描文件**: 含 `Observable`, `Publisher`, `Driver`, `Signal` 的文件
-
-**提取内容**:
-- 响应式链的输入/输出
-- 操作符链（map, flatMapLatest, filter, debounce 等）
-- 线程调度（MainScheduler, DispatchQueue.main）
-- DisposeBag / cancel 管理
-
-## 输出模板
-
-### README.md 章节结构
-
-```markdown
-# {项目名}
-
-## 项目概述
-App 功能描述 + 目标用户 + 核心价值
-
-## 技术栈
-| 技术 | 版本 | 用途 |
-|------|------|------|
-| Swift | 5.9 | 开发语言 |
-| UIKit + SwiftUI | iOS 17+ | UI 框架 |
-| Combine | - | 响应式 |
-
-## 架构设计
-### 架构图（ASCII）
-### 数据流图
-用户操作 → ViewController → ViewModel → Repository → API → 解码 → Model → ViewModel → UI 更新
-
-## 目录结构
-按 Feature 模块组织的文件树
-
-## 导航结构
-Coordinator 层级 + 页面流转图
-
-## 模块详解
-按 Feature 分组，每个包含 View/ViewModel/Model/Service
-
-## 依赖管理
-SPM / CocoaPods 依赖列表
-
-## 构建 & 部署
-Xcode 版本 + Certificate + Scheme
+### 模块结构（SPM）
+- Package.swift Targets: AppCore, AppUI, NetworkKit, StorageKit
+- 本地依赖: AppUI → AppCore → NetworkKit
+
+### 导航结构（Coordinator）
+AppCoordinator
+  ├── LoginCoordinator → LoginViewController
+  └── MainCoordinator
+        ├── HomeViewController
+        ├── ProfileCoordinator → ProfileViewController → EditProfileViewController
+        └── SettingsViewController
+
+### 架构模式
+- UI 框架: SwiftUI + UIKit 混合（UIHostingController 桥接）
+- 架构: MVVM + Coordinator
+- 响应式: Combine (@Published + sink)
+- DI: Factory 框架
 ```
-
-## 模块边界识别
-
-以下目录模式下的每个子目录视为独立模块（L2+ 分析时生成 MODULE-DOC.md）：
-
-| 层 | 扫描路径 | 模块判定规则 | MODULE-DOC slug 来源 |
-|----|----------|-------------|---------------------|
-| 页面/视图层 | `Sources/{Module}/`, `Screens/` | 每个子目录 | 目录名 kebab-case |
-| API/服务层 | `Services/`, `Network/` | 每个子目录 | 目录名 kebab-case |
-| 状态管理层 | `ViewModels/`, `Stores/` | 每个子目录或文件 | 名称 kebab-case |
-| 组件层 | `Views/`, `UIComponents/` | 3+ 文件的子目录 | 目录名 kebab-case |
-| 扩展层 | `Extensions/` | 所有文件合并 | extensions |
-
-**不视为独立模块的情况**：
-- 单文件入口（如 `App.swift`, `main.swift`）
-- 纯导出桶文件（仅有 re-export）
-- 工具函数目录（`Utils/`, `Helpers/`）— 合并为一个模块
-- 生成文件（`*.generated.swift`）跳过
-
-## Token 管理
-
-- 大模块（>20 文件）拆分为子任务
-- 每个子任务分析 ≤10 文件
-- Storyboard / XIB 文件跳过（二进制格式）
-- Assets.xcassets 只分析目录结构，不分析图片内容
-- Package.swift / Podfile 依赖分析单独一个子任务
-- 生成的文件（`*.generated.swift`, `*.xcassets` 详情）跳过