5.7 KiB
Orders 模块业务逻辑
模块职责
Orders 模块负责登录后的订单 Tab 与订单相关二级页面。当前已对齐 Android zhiflyfollow 订单列表能力：主订单列表（摄影师/非店长）、店长押金式订单 Tab、独立核销管理页，以及押金订单独立入口、历史拍摄、任务上传、尾片入口和 orderType 11/14 订单来源（带客单绑定）闭环。
订单 Tab 内不再展示「订单管理 / 核销订单」分段；核销管理通过首页菜单、TabBar 扫码或路由 push 进入独立页面。
门店订单详情页与核销订单详情页暂未接入，列表卡片仅展示摘要信息与卡片内操作。
当前仍不迁移独立视频播放器增强、尾片审核进度、上传后自动关联订单尾片等后端未体现的能力；多点位核销的定位 + 打卡点 Sheet 若 iOS 尚无完整能力，列表内仅预留扫码入口。
页面结构
| 场景 | 视图 | 说明 |
|---|---|---|
| 订单 Tab · 非店长 | StoreOrderListView |
对齐 Android OrderListScreen |
| 订单 Tab · 店长 | StoreAdminOrderListView |
对齐 Android DepositOrderListScreen |
| 核销管理 | WriteOffListView |
对齐 Android WriteOffListScreen，独立 push 页 |
| 押金订单入口 | DepositOrderEntryView |
首页 deposit_order* 仍保留独立入口 |
OrdersRootView 按 AppRoleCode.storeAdmin 分流店长 Tab 与主订单 Tab。
核心对象
StoreOrderListView：主订单 Tab 根视图，组合OrderListHeaderView、OrderListCardView与OrdersViewModel。StoreAdminOrderListView：店长订单 Tab，组合共享头部与店长卡片，使用StoreAdminOrderListViewModel。WriteOffListView：核销管理页，使用WriteOffListViewModel，含横向状态 pill、日期筛选与扫码/手动核销。OrderListHeaderView：白底状态/日期筛选头部；手机号搜索使用系统.searchable。OrderListCardView：主订单卡片，对齐 AndroidOrderView展示顺序与操作区。OrderListComponents：状态 Chip、信息行、操作按钮、精修单选等共享组件。OrderDialogViews：退款、赠送修图/视频、店长退款、核销确认弹窗。OrdersViewModel：主订单列表分页、筛选、卡片操作（退款/核销/精修/取消/赠送）与订单来源。StoreAdminOrderListViewModel：店长订单列表与storeOrderList/storeOrderRefund。WriteOffListViewModel：核销列表筛选、分页与核销提交。DepositOrderListViewModel：押金订单分页、核销、退款（独立押金入口）。OrderRefundViewModel：普通订单退款金额校验与提交。OrdersAPI：订单列表、核销列表、精修更新、取消、赠送、店长列表/退款等接口。OrdersEntry：订单 Tab 内部入口枚举，保留verificationOrders供测试/推送兼容。OrdersRoute：二级路由，含writeOffList、押金详情、历史拍摄、任务上传、尾片入口。OrderNumberParser：从扫码内容解析订单号。
数据流程
主订单列表
从 AccountContext.currentScenic 读取景区 ID，从 PermissionContext.currentAppRole 读取角色。景区管理员（scenicAdmin）使用景区管理员订单接口且卡片只读（隐藏退款/核销/拨号/精修/赠送/取消）。
支持状态筛选（含精修筛选项）、手机号搜索、日期范围 Sheet 筛选。筛选变更后从第一页重新加载，滚动到底加载下一页。
卡片展示订单号、状态、创建时间、类型、订单来源、操作行、上传任务条（orderType 19）、精修单选、信息行、条件行、退款信息、备注、历史拍摄缩略图与取消订单按钮。操作受 hideOrderWriteActions 控制。
店长订单 Tab
从 AccountContext.currentStore 读取门店 ID，调用 GET /api/app/store/order/list。筛选为全部/已支付/已完成/已退款。卡片展示项目、金额、时间、UID、手机号与退款/部分退款；线下产品订单额外展示核销按钮。仅 orderType == 19 可进详情。
核销管理
独立页面，调用 writeOffList 并支持 order_status、order_verify_status、start_time、end_time、user_phone 查询参数。横向 pill：全部/已支付/已完成/已核销/未核销。
扫码使用 OrderCodeScannerView，命中列表时滚动高亮；核销前弹确认框，成功后刷新第一页。TabBar 全局扫码通过 pendingOrderScanCode 交给核销页消费。
押金订单（独立入口）
首页 deposit_order_detail、deposit_order、deposit_order_shooting_info 进入 DepositOrderEntryView，与 Tab 内店长列表 UI 分离但共用部分 API。
订单来源（带客单绑定）
仅对 orderType == 11 或 14 展示，景区管理员只读。绑定接口 POST .../sale-user/bind-referral-order；退款成功后若存在带客单则异步更新状态。
历史拍摄与任务上传
历史拍摄：GET .../photog/order/multi-travel/shoot-history。任务上传：仅 orderType 19，先拉已核销打卡点再上传素材。
路由边界
| 入口 | 目标 |
|---|---|
photographer_orders、/scenic-order-manage |
订单 Tab · 主列表或店长列表 |
verification_order |
push OrdersRoute.writeOffList（核销管理） |
deposit_order* |
push 押金订单页 |
| TabBar 扫码 | 核销管理页消费扫码结果 |
AppRouter.routeToOrderVerification 切换订单 Tab 并 push 核销页，不再设置 selectedOrdersEntry。
未明确接口的订单能力继续占位，避免入口崩溃。
设计常量
订单列表专用色值与间距定义在 AppDesign（页面背景 #F5F5F5、输入背景 #F4F4F4、状态 Chip 色等与 Android 对齐）。