Initial commit: suixinkan_ios UIKit rewrite project.

Co-authored-by: Cursor <cursoragent@cursor.com>

AGENTS.md

@@ -0,0 +1,121 @@
+# 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 引用
+
+### 注释
+
+- 定义的**类**、**结构体**、**方法**均须添加注释，说明其职责、用途或行为
+- 方法内涉及较复杂的业务逻辑、分支判断、状态流转或非直观实现时，须补充行内或块注释，便于后续维护
+- 注释应简洁准确，说明「为什么」与业务含义；避免重复代码字面含义的无意义注释
+
+---
+
+## 列表视图
+
+- **复杂列表**（多 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）
+- 构建：`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'`