Initial commit: suixinkan_ios UIKit rewrite project.

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

suixinkan_ios/Features/PunchPoint/PunchPoint.md

@@ -0,0 +1,37 @@
+# PunchPoint 模块业务逻辑
+
+## 模块职责
+
+PunchPoint 模块负责首页 `checkin_points` 打卡点管理入口。
+
+本模块包含打卡点列表、状态筛选、分页、详情、二维码、新建、编辑、删除、前台定位选点和图片 OSS 上传。打卡点列表和表单状态只保存在模块 ViewModel 内，不进入 `AppSession`、`AccountContext`、TabBar 或首页状态。
+
+## 数据来源
+
+- 当前景区 ID 从 `AccountContext.currentScenic` 读取。
+- 列表接口使用 `/api/yf-handset-app/photog/scenic-spot/list`。
+- 详情接口使用 `/api/yf-handset-app/photog/scenic-spot/info`。
+- 新建、编辑、删除分别使用 `/add`、`/edit`、`/delete`。
+- 图片上传统一使用 `OSSUploadService.uploadPunchPointImage`。
+
+## 页面流程
+
+`PunchPointListViewModel` 管理状态筛选、分页、详情兜底和删除刷新。缺少当前景区时清空列表并停止请求。
+
+`PunchPointEditorViewModel` 管理新增和编辑表单。提交前校验名称、坐标、地址和图片；本地图片会先上传 OSS，全部拿到最终 URL 后再提交打卡点接口。上传失败时不提交业务接口。
+
+编辑或删除成功后，页面会触发 `ScenicSpotContext.reload`，保证素材、样片等依赖打卡点选择器的页面能看到最新数据。
+
+## 定位边界
+
+当前实现使用 `ForegroundLocationProvider` 做前台即时定位和地址反解析，并允许手动填写经纬度。本轮不做后台定位、不缓存定位结果，也不把定位权限状态落盘。
+
+后续如果接入完整高德地图选点 UI，只需要替换编辑页的选点组件，继续把经纬度、地址回填到 `PunchPointEditorViewModel`。
+
+## 缓存边界
+
+打卡点列表、详情、表单、本地图片、上传进度和 OSS STS 都不落盘。远程图片缓存继续交给 Kingfisher 的 `RemoteImage`。
+
+## 测试要求
+
+新增打卡点逻辑时，需要同步补充 API、ViewModel 和路由测试。测试失败时先修复问题，再继续迁移后续功能。