Initial commit: suixinkan_ios UIKit rewrite project.

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

suixinkan_ios/Features/Orders/Orders.md

@@ -0,0 +1,49 @@
+# Orders 模块业务逻辑
+
+## 模块职责
+
+Orders 模块负责登录后的订单 Tab。当前已覆盖订单管理、核销订单和押金订单相关入口，提供列表展示、筛选、分页、刷新、订单详情、扫码核销、手动核销、押金核销、押金退款、普通订单退款、历史拍摄、任务上传和尾片入口闭环。
+
+当前仍不迁移独立视频播放器增强、尾片审核进度、上传后自动关联订单尾片等后端未体现的能力；这些能力后续按明确接口再补。
+
+## 核心对象
+
+- `OrdersView`：订单 Tab 根视图，读取 `AccountContext`、`PermissionContext`、`AppRouter` 和 `OrdersAPI`。
+- `OrdersViewModel`：管理订单子入口、筛选条件、分页状态、加载状态和手动核销状态。
+- `OrderDetailViewModel`：管理订单详情接口加载、错误提示和列表摘要兜底展示。
+- `DepositOrderListViewModel`：管理押金订单分页、核销、退款和操作后刷新。
+- `DepositOrderDetailViewModel`：管理押金订单详情加载，缺少门店时不发起请求。
+- `DepositOrderShootingInfoViewModel`：管理押金订单单个打卡点的底片、成片和评价。
+- `OrderRefundViewModel`：管理普通订单退款入口判断、全额/部分退款金额校验和提交保护。
+- `HistoricalShootingInfoViewModel`：管理多点位订单历史拍摄媒体展示。
+- `MultiTravelTaskUploadViewModel`：管理多点旅拍任务上传的订单号、已核销打卡点、云盘附件、本地附件、OSS 上传和提交。
+- `OrdersAPI`：封装订单列表、核销订单列表和订单核销接口。
+- `OrdersEntry`：表示订单 Tab 内部入口，包含订单管理和核销订单。
+- `OrdersRoute`：表示订单模块二级页面路由，包含订单详情和核销订单详情。
+- `OrderNumberParser`：负责从扫码内容中解析订单号，支持 URL query、键值文本和纯订单号。
+
+## 数据流程
+
+订单页面从 `AccountContext.currentScenic` 读取当前景区 ID，从 `PermissionContext.currentRole` 读取角色 ID。景区管理员角色 `roleId == 53` 使用景区管理员订单接口，其他角色使用摄影师订单接口。
+
+订单管理支持状态筛选、手机号搜索、开始/结束日期筛选。筛选变更后从第一页重新加载，滚动到列表底部时加载下一页。
+
+订单管理点击订单卡片进入订单详情。详情页优先用 `/api/app/store/order/detail` 按 `store_id + order_number` 拉取完整数据；缺少门店 ID 或接口失败时，保留列表卡片摘要作为兜底展示，并提示当前详情不完整。
+
+核销订单支持扫码和手动输入订单号。扫码使用 AVFoundation，不缓存扫码结果；扫码成功后先用 `OrderNumberParser` 提取订单号，命中当前核销列表时滚动定位并高亮卡片，未命中时填入订单号并允许继续核销。核销前统一弹确认框，确认后调用核销接口。核销成功后重新拉取第一页核销订单，并重置分页状态；核销失败只清理提交状态，不刷新列表。
+
+押金订单入口由首页 `deposit_order_detail`、`deposit_order`、`deposit_order_shooting_info` 进入。没有订单上下文时先展示押金订单页，用户可以手输订单号进入详情，也可以从列表进入详情。押金详情复用门店订单详情接口，按当前门店 ID 和订单号加载；拍摄点列表进入拍摄信息页，展示评价、底片和成片。
+
+普通订单退款只在 `orderStatus == 18 || orderStatus == 30`、`orderType != 19` 且可退金额大于 0 时展示入口。全额退款使用可退金额，部分退款要求金额大于 0、最多两位小数且不能超过可退金额。押金退款要求填写退款原因，普通退款和押金退款都不保存表单数据，提交成功后刷新对应订单数据。
+
+历史拍摄按订单号请求 `/api/yf-handset-app/photog/order/multi-travel/shoot-history`，仅展示项目、拍摄点和已有媒体，不做上传、下载、删除或编辑。
+
+任务上传仅对 `orderType == 19` 的多点旅拍订单展示。页面先按订单号请求 `/api/yf-handset-app/photog/order/multi-travel/verified-scenic-spot-list` 获取已核销打卡点，再支持选择云盘素材和本地图片/视频；本地素材先通过 `OSSUploadService.uploadTaskFile` 上传，成功后和云盘文件一起提交到 `/api/yf-handset-app/photog/order/multi-travel/upload-material`。
+
+视频预告和尾片上传按旧工程现状统一进入 `OrderTrailerView`，该页只做订单尾片流程引导，并打开已迁移的 `AlbumTrailerEntryView` 完成相册预览上传，不新增独立订单尾片接口。
+
+## 路由边界
+
+首页 `photographer_orders` 和 `/scenic-order-manage` 会进入订单管理，`verification_order` 会进入核销订单，`deposit_order_detail`、`deposit_order`、`deposit_order_shooting_info` 会进入押金订单页。订单详情、核销订单详情、押金详情、押金拍摄信息、历史拍摄、任务上传和订单尾片已接入 `AppRoute.orders` 真实路由，push 后继续隐藏 TabBar。
+
+未明确接口的订单后续能力继续进入占位页，避免入口崩溃。