# Quickstart: 用户端统一订单列表

**Date**: 2026-09-20 | **Spec**: [spec.md](spec.md) | **契约**: [contracts/api-contract.md](contracts/api-contract.md)

## 前置条件

1. **索引核实（上线前置）**：按 `data-model.md` §5 在库上 `SHOW INDEX` 核实三处索引，缺则执行 updatesql/sql.md 中对应条目（本功能除索引外零 DB 变更）。
2. **JDK**：
   ```bash
   export JAVA_HOME="$HOME/.jdks/graalvm-jdk-21.0.12+7.1"
   export PATH="$JAVA_HOME/bin:$PATH"
   ```
3. 测试数据：目标用户名下构造样本——外卖（在线支付未付 / 货到付款各状态 / 售后中 / 已取消 / 已完成）+ 闪送（六态各一 + 一单寄件人=收件人 + 一单 A 寄 B）。

## 自动化验证

```bash
mvn -pl ruoyi-admin -am test -Dtest='UnifiedOrder*Test,UnifiedCursorTest' -Dsurefire.failIfNoSpecifiedTests=false
mvn -pl ruoyi-admin -am compile
```

预期：全绿（含翻页完整性——测试内多次滚动聚合断言与样本全集一致）。

## 手动端到端（服务起本地，token 为登录凭证）

```bash
# 1. 首页：混排 + 倒序
curl 'http://localhost:8080/system/unifiedOrder/list?tab=all&source=all&size=10' -H 'token: <t>'
# 预期：list 内 createTime 严格非递增；takeaway/flash 混排；hasMore/nextCursor 正确

# 2. 滚动第二页（透传 nextCursor）
curl 'http://localhost:8080/system/unifiedOrder/list?cursor=<nextCursor>' -H 'token: <t>'

# 3. tab 归类抽查
curl '.../list?tab=unpaid'   # 仅外卖在线支付未付单
curl '.../list?tab=refund'  # 仅外卖售后单
curl '.../list?tab=active'  # 外卖履约中 + 闪送非终态

# 4. 来源筛选 + 收件视角
curl '.../list?source=flash' -H 'token: <B的token>'   # 含 A 寄 B 的单，role=receiver
curl '.../list?source=takeaway'                        # 仅外送单（type=0，不含堂食/自取）
curl '.../list?source=dinein'                          # 仅堂食（type=2，卡片 sourceType 仍为 takeaway）
curl '.../list?source=pickup'                          # 仅自取（type=1）

# 5. 非法游标
curl '.../list?cursor=garbage'                          # 参数错误提示
```

## 回归（必须零差异）

- 旧接口 `GET /system/userOrder/orderList`、`GET /system/flashDelivery/orders` 原测试全绿 + 手工抽查不变。
- `mvn -pl ruoyi-admin -am test`（全模块）无新增失败（已知基线红：flash payType 白名单，见项目记忆）。

## 通过标准

- 自动化全绿；§手动场景逐条与契约一致；旧接口零回归。