# Agent Instructions

本文件用于向 AI Agent 提供项目级指导。Cursor 会在处理本项目时自动读取此文件。

> 如需按文件类型或目录生效的规则，可使用 `.cursor/rules/*.mdc`（支持 globs 与条件触发）。

---

## 项目概述

这是一个 iOS 项目，最低支持 **iOS 16**，使用 **Swift + UIKit** 开发。

**工程目的：** 将同目录下的 [`suixinkan_ios_new`](../suixinkan_ios_new)（SwiftUI 工程）的功能，使用 Swift + UIKit 重写一遍。

- 当前工程：`suixinkan_ios_new_uikit`
- 参考工程：`../suixinkan_ios_new`（SwiftUI）
- 平台：iOS 16+
- 语言：Swift
- UI 框架：UIKit

---

## 重写原则

- 功能、业务流程、API、数据模型以参考工程 `suixinkan_ios_new` 为准
- UI 使用 UIKit 实现，交互与表现应与参考工程保持一致
- 实现时可参考参考工程的模块划分与命名，但视图层须用 UIKit 重写，不使用 SwiftUI

---

## 架构

采用 **MVVM** 设计模式：

- **View**：UIView / UIViewController，负责 UI 展示与用户交互
- **ViewModel**：处理业务逻辑与状态，向 View 提供数据与命令
- **Model**：数据模型与网络/持久化层

View 与 ViewModel 之间通过命令式方式绑定（如 delegate、closure、KVO 或直接属性赋值），不使用 Combine。

---

## 编码规范

- 使用**命令式编码**风格，逻辑清晰、步骤明确，避免过度函数式或声明式写法
- 异步逻辑优先使用 `async/await`
- View 层只负责展示与事件转发，业务逻辑放在 ViewModel
- ViewModel 不直接持有 UIView / UIViewController 引用

### Swift 并发

- 工程已将编译选项 **`SWIFT_DEFAULT_ACTOR_ISOLATION`** 设置为 **`nonisolated`**（见 Xcode Build Settings）
- 即类型与方法**默认不**隔离到 `@MainActor`；需要主线程/UI 相关逻辑时，再显式标注 `@MainActor` 或使用 `MainActor.assumeIsolated` / `await MainActor.run`
- 仅在确实需要脱离默认隔离（如 delegate 回调、静态工具方法）时再显式写 `nonisolated`，避免冗余标注

### 注释

- 定义的**类**、**结构体**、**方法**均须添加注释，说明其职责、用途或行为
- 方法内涉及较复杂的业务逻辑、分支判断、状态流转或非直观实现时，须补充行内或块注释，便于后续维护
- 注释应简洁准确，说明「为什么」与业务含义；避免重复代码字面含义的无意义注释

---

## 列表视图

- **复杂列表**（多 section、多布局、网格/混排、频繁局部刷新等）尽量使用 **UICollectionView**
- **简单列表**（单列、结构固定、交互简单）可以使用 **UITableView**
- UICollectionView 的数据驱动与刷新统一使用 **Diffable Data Source**（`UICollectionViewDiffableDataSource` + `NSDiffableDataSourceSnapshot`）
- 数据变更时通过 snapshot diff 应用更新，保留插入、删除、移动等**动画效果**；避免 `reloadData()` 全量刷新
- Item / Section 需遵循 `Hashable`，保证 diff 计算正确

---

## 第三方库

**SnapKit**
- 用于 Auto Layout 约束布局
- UI 布局优先使用 SnapKit，避免手写 NSLayoutConstraint

**Kingfisher**
- 用于加载与展示网络图片
- 网络图片统一通过 Kingfisher 处理，避免自行实现图片下载与缓存

---

## 模块文档

每个功能目录下需创建一个 Markdown 业务说明文档，用于描述该模块的业务与代码逻辑。

- 文档建议命名为 `README.md` 或 `<模块名>.md`
- 文档需说明：模块职责、核心业务流程、主要页面 / ViewController / ViewModel / API / Model 的关系
- 新增或修改模块业务逻辑时，需同步更新对应文档
- 文档只描述业务逻辑，避免记录临时实现细节或无关调试信息

---

## 测试

添加功能或修改功能后，需同步补充或更新单元测试。

- 测试用例需覆盖核心成功路径、失败路径和关键边界条件
- 修改现有业务逻辑时，需同步调整相关测试
- 完成改动后需运行测试，**全部通过**后方可视为完成
- 测试不通过时，需修复代码并重新运行测试，直到全部通过

---

## 禁止事项

- 不要使用 SwiftUI（本工程为 UIKit 重写）
- 不要使用 **Combine** 库（包括 `@Published`、`PassthroughSubject`、`ObservableObject` 等）
- 不要修改参考工程 `suixinkan_ios_new` 的代码，除非明确要求

---

## 工作流程

- 新增或修改功能 → 更新模块文档 → 补充单元测试 → 运行测试直至全部通过

---

## 其他说明

- 同步进度详见 [功能同步Checklist.md](功能同步Checklist.md)
- 参考工程：`../suixinkan_ios_new`（SwiftUI）
- 高德 Key：在 `suixinkan_ios/Info.plist` 的 `AMapAPIKey` 填入控制台 Key（真机地图生效）
- 构建：`xcodebuild -workspace suixinkan_ios.xcworkspace -scheme suixinkan_ios build`
- 测试：`xcodebuild test -workspace suixinkan_ios.xcworkspace -scheme suixinkan_ios -destination 'platform=iOS Simulator,name=iPhone 17'`