suixinkan_ios_uikit/AGENTS.md

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 引用

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
• 参考工程：../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'