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

Date: 2026-09-20 | Spec: 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. 返回

{
  "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. 前端行为要点

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

6. 联调自测清单

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

api-contract.md 4.9 KB Постоянная ссылка История Исходник