# 前端接口契约：统一订单列表（uni-app 用户端）

**Date**: 2026-09-20 | **Spec**: [spec.md](../spec.md)

> 外卖 + 闪送订单合并为一个列表。前端滚动加载游标分页，卡片复用现有两种样式混排，按 `sourceType` 渲染、按 `role` 加"我收的"标签。

## 1. 接口

```
GET /system/unifiedOrder/list
Header: token
Query:
  tab     可选，枚举 all/unpaid/active/completed/cancelled/refund，默认 all
  source  可选，枚举 all/takeaway/dinein/pickup/flash，默认 all
          takeaway=仅外送单(type=0)；dinein=堂食(type=2)；pickup=自取(type=1)；all=全部混排
  cursor  可选，首页不传；后续传上一页返回的 nextCursor 原样透传
  size    可选，默认 10，服务端钳制 1-50
```

## 2. 返回

```json
{
  "code": 200,
  "data": {
    "list": [ /* UnifiedOrderListItem[] */ ],
    "hasMore": true,
    "nextCursor": "1726812345000_flash_1024"
  }
}
```

- 滚动逻辑：`hasMore=false` 停止加载；`nextCursor` 为不透明字符串，**不要解析、不要修改**，仅透传。
- 错误（code=500）：游标非法 / 参数非法，提示后重置回首页重新加载。

## 3. 列表项 UnifiedOrderListItem

### 公共字段

| 字段 | 类型 | 说明 |
|---|---|---|
| sourceType | String | `takeaway` 外卖 / `flash` 闪送 —— **卡片样式分支依据** |
| role | String | `sender`/`receiver`，仅闪送有区分意义（"我收的"标签） |
| orderId | Long | 源订单 ID（与 sourceType 联用才唯一） |
| orderNo | String | 外卖=ddId、闪送=orderNo —— **详情跳转键** |
| unifiedStatus | String | unpaid/active/completed/cancelled/refund（all 下为该单实际归属） |
| createTime | Long | 下单时间毫秒 |
| amount / currency | Long/String | 金额与币种 |
| hasAfterSale | Boolean | 外卖售后角标；闪送恒 false |

### takeaway 渲染块（字段值语义与现有外卖列表完全一致，渲染逻辑直接复用）

`type`(0外送/1自取/2堂食)、`state`(0待处理/1已接单/2已出餐/3已完成/4已取消)、`deliveryStatus`(0待接/1已接/2配送中/3已送达)、`payStatus`(0未付/1已付/2已退)、`payType`(1到付/2OMG/3LINE/4现金/5余额/6转账)、`afterSaleStatus`(0-6)、`storeName`(店铺名称，按门店查 pos_store，非商家昵称)、`storeAvatar`(店铺头像 logo)、`goodsCount`(商品件数，food 快照 number 求和)、`collectPayment`

### flash 渲染块（对齐现有闪送列表卡片）

`status`(WAITING_ACCEPTANCE/ACCEPTED/PICKED_UP/DELIVERED/COMPLETED/CANCELLED)、`orderVersion`(闪送乐观锁版本，用户编辑待接单订单须回传)、`serviceType`、`deliveryType`、`vehicleType`、`deliveryMode`(NOW/SCHEDULED)、`scheduledPickupStartAt/scheduledPickupEndAt`、`pickupAddress/pickupDetailAddress`、`deliveryAddress/deliveryDetailAddress`、`packageType`、`quantity`、`tipAmount`

## 4. tab 归类语义（前端文案对照）

| tab | 含义 | 外卖 | 闪送 |
|---|---|---|---|
| all 全部 | 所有订单 | ✅ | ✅ |
| unpaid 待付款 | 在线支付未付（货到付款不在此列） | ✅ | —（永空） |
| active 进行中 | 履约中 | ✅ | 非终态（待接/已接/已取件/已送达） |
| completed 已完成 | 终态·完成 | ✅ | COMPLETED |
| cancelled 已取消 | 终态·取消 | ✅ | CANCELLED |
| refund 退款/售后 | 售后流程中/已退款 | ✅ | —（永空） |

## 5. 前端行为要点

1. **排序**：列表已按下单时间倒序排好，前端直接顺序渲染，勿再排序。
2. **详情跳转**：`sourceType=takeaway` → 现有外卖详情（`orderNo`=ddId）；`sourceType=flash` → 现有闪送详情（`orderId` 或 `orderNo`）。
3. **角色标签**：`sourceType=flash && role=receiver` 的卡片显示"我收的"标识。
4. **角标**：`hasAfterSale=true` 的外卖卡片显示售后角标。
5. **空 tab**：待付款/退款售后里没有闪送单是正常现象，空态文案正常展示即可。
6. **堂食/自取筛选**：`source=dinein/pickup` 下卡片仍是 `sourceType=takeaway` 外卖样式，堂食/自取身份按卡片的 `type` 字段（2/1）渲染文案。
7. 旧的 `/system/userOrder/orderList` 与 `/system/flashDelivery/orders` 不下线，其它页面继续用。

## 6. 联调自测清单

1. 同一账号混有外卖+闪送单 → 全部 tab 按时间倒序混排，两种卡片正确渲染。
2. 连续滚动到底 → 与该账号实际订单总数一致，无重复无遗漏。
3. 6 个 tab × 5 个来源筛选逐一核对归类（重点：待付款不含货到付款；售后单只在退款/售后 tab；takeaway/dinein/pickup 三筛选取舍：外送单不出现在堂食/自取筛选，反之亦然）。
4. A 寄给 B 的闪送单：A、B 各自列表都出现，角色分别为寄件/收件；自己寄给自己只出现一条。
5. 非法 cursor（手改字符串）→ 报错提示，重置回首页可用。
6. 旧外卖列表页/闪送列表页（若有保留入口）行为不变。