汉秋
abcac9bfdf
将打卡点管理与位置上报从占位页迁移为完整 MVVM 流程，包含前台定位支持与单元测试。 Co-authored-by: Cursor <cursoragent@cursor.com>
38 lines
2.0 KiB
Markdown
38 lines
2.0 KiB
Markdown
# 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 和路由测试。测试失败时先修复问题，再继续迁移后续功能。
|