# 订单管理

## 基本信息

| 项目 | 内容 |
| --- | --- |
| 路由 | `/pages/orders/orders` |
| 页面目标 | 让商户查看不同业务类型的订单，并按核销状态与时间定位订单。 |
| 进入方式 | 首页底部“订单管理”入口。 |
| 负责人/更新时间 | 待指定 / 2026-07-30 |

## 功能点

| 编号 | 功能 | 说明 | 当前状态 |
| --- | --- | --- |
| F-001 | 业务分类 | 支持团购、到店消费、免费入住切换，对应后端稳定业务类型。 | 已接入 |
| F-002 | 状态筛选 | 使用 `all`、`pending_verification`、`pending_payment`、`completed` 枚举筛选。 | 已接入 |
| F-003 | 时间筛选 | 原生三列滚轮选择日期区间；确认后以 ISO 日期重新请求列表。 | 已接入 |
| F-004 | 订单分页 | 首屏、上滑加载、空态、首屏失败、追加失败重试和到底状态均使用统一列表数据源。 | 已接入 |
| F-005 | 订单卡 | 使用稳定订单 ID 渲染，展示后台返回的脱敏用户、金额、卡种、状态和时间。 | 已接入 |
| F-006 | 详情路由 | 非免费入住订单携带订单 ID、订单号进入已有详情页。 | 已接入路由 |
| F-007 | 开发演示 | 开发环境标题右侧提供“演示数据”开关，可在本地分页数据与真实接口之间切换。 | 已完成 |
| F-008 | 底部导航 | 与首页、商户中心同级，使用 `uni.reLaunch` 切换。 | 已完成 |
| F-009 | 观影券样式 | 「团购」里混排观影券（票包领取记录）：标题固定「观影券1张」，与人才卡等级同一行，无金额行；未核销显示「领取时间」、已核销显示「核销时间」，状态标签为「待核销 / 已核销」。 | 已接入 |
| F-010 | 观影券详情 | 点开观影券进入 `/pages/ticket-package-detail/ticket-package-detail?claimId={领取记录ID}`。 | 已接入路由 |

## 操作说明

1. 进入页面默认查看团购订单和“全部”状态。
2. 开发环境可切换“演示数据”：开启时展示本地分页卡片；关闭时请求当前登录商户和门店的真实订单。
3. 切换业务分类、状态或确认日期范围后，列表从第一页重新加载。
4. 上滑触底加载下一页；追加失败时保留已展示订单并可点击底部重试。
5. 无登录会话却关闭演示数据时，页面提示登录后加载真实订单，不将该场景误显示为空列表。
6. 点击团购待核销订单进入待核销详情；到店待支付和已完成订单进入对应详情；免费入住不提供详情入口。
7. 团购列表里的观影券来自票包领取记录（`ticket_package_claim`），和普通团购订单按时间倒序混排分页；点开进入观影券核销详情。

## 接口与数据

| 数据项/动作 | 接口标识 | 参数 | 返回字段 | 状态 |
| --- | --- | --- | --- | --- |
| 订单分页列表 | `GET /api/merchant/orders` | `page`、`size`、`category`、`status`、`startDate`、`endDate`；门店来自会话 | 订单 ID/号、分类、稳定状态、脱敏用户、金额、卡种、下单/核销时间、`total` | 已接入 |
| 观影券领取记录详情 | `GET /api/merchant/ticket-package-claims/{claimId}` | 领取记录 ID；商户来自会话 | 领取编号、券名、持卡人与卡等级、状态、领取/核销时间、当前权益 | 已接入 |
| 订单详情 | `GET /api/merchant/orders/{orderNo}` | 订单号；门店来自会话 | 商品/权益、用户摘要、金额、状态 | 服务端已有，详情页视觉后续继续深化 |
| 订单核销 | `POST /api/merchant/orders/{orderNo}/verify` | 核销方式、备注 | 核销结果 | 服务端已有，扫码核销为主流程 |

## 接口约束

- 分类只接受 `group`、`store`、`stay`；状态只接受约定枚举，后端不依赖中文文案。
- 日期采用 `yyyy-MM-dd`，结束日期按次日零点前包含整日；开始日期晚于结束日期时返回明确错误。
- `category=group` 时列表把普通团购订单与观影券混排，`sourceType=TICKET_PACKAGE` 表示这一条是观影券；分页 `total` 是两类记录之和。
- 后端按当前商户、门店权限过滤，并只向列表返回脱敏姓名和手机号。
- 列表响应使用 `records`、`page`、`size`、`total` 判断分页，不以本地长度猜测是否到底。

## 验收清单

- [x] 视觉与订单管理设计图的页头、标签、筛选栏、订单卡和导航层级一致。
- [x] 分类、状态、日期筛选和分页列表已接入商户订单接口。
- [x] 已补齐首屏/下一页加载、空态、失败重试和到底状态。
- [x] 开发环境提供独立的页面内演示数据开关。
- [x] HBuilderX 微信小程序编译和订单查询服务自动化测试通过。
- [ ] 真实商户账号、真实订单和真机详情跳转待联调验收。