# 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 和路由测试。测试失败时先修复问题，再继续迁移后续功能。