4.4 KiB
4.4 KiB
Agent Instructions
本文件用于向 AI Agent 提供项目级指导。Cursor 会在处理本项目时自动读取此文件。
如需按文件类型或目录生效的规则，可使用
.cursor/rules/*.mdc（支持 globs 与条件触发）。
项目概述
这是一个 iOS 项目，最低支持 iOS 16，使用 Swift + UIKit 开发。
工程目的： 将同目录下的 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
- 参考工程：
../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'