foodie-server/specs/006-orderstate/frontend-api-guide.md

订单列表接口前端对接文档

通用说明

• 三个端各自独立的 orderList 接口，通过 tab 参数区分 Tab
• 返回格式统一：{ code, msg, data: { records, total, page, size } }
• records 中每条数据为 PosOrder 全字段，新增字段：
  • deliveryStatus — 配送状态（Long，自取/堂食为 null）
  • payStatus — 支付状态（Long）
  • afterSaleStatus — 售后状态（Long）
• 状态展示文字由前端根据 type + state + deliveryStatus + payStatus + afterSaleStatus 组合计算，后端不返回 statusText
• 所有接口需要 token Header

---

一、用户端

接口: GET /system/userOrder/orderList

参数

参数	类型	必填	说明
token	Header	是	用户身份
page	int	是	页码，从 1 开始
size	int	是	每页条数
tab	String	是	见下表
type	String	否	订单类型筛选：0 外送 / 1 自取 / 2 堂食，不传查所有

Tab 列表

Tab 名称	tab 值	含义	请求示例
待付款	unpaid	仅外送未支付订单	?tab=unpaid&page=1&size=10
进行中	active	进行中的订单	?tab=active&page=1&size=10
已完成	completed	已完成订单	?tab=completed&page=1&size=10
已取消	cancelled	已取消订单	?tab=cancelled&page=1&size=10
退款/售后	refund	有售后记录的订单	?tab=refund&page=1&size=10

前端展示文字对照表

根据返回字段组合显示用户看到的文字：

type	state	payStatus	deliveryStatus	afterSaleStatus	显示文字
0(外送)	0	0	-	0	待付款
0(外送)	0	1	-	0	待商家确认
0(外送)	1	1	-	0	商家备餐中
0(外送)	2	1	0	0	待骑手配送
0(外送)	2	1	1	0	骑手已接单
0(外送)	2	1	2	0	配送中
0(外送)	2	1	3	0	已送达
0(外送)	3	1	-	0	已完成
0(外送)	*	*	*	1	退款申请中
0(外送)	*	*	*	2	退款中
0(外送)	4	2	-	3	已退款
0(外送)	4	-	-	0	已取消
1(自取)	0	0	null	0	待商家确认
1(自取)	1	1	null	0	商家备餐中
1(自取)	2	1	null	0	待取餐（请到店取餐）
1(自取)	3	1	null	0	已完成
1(自取)	4	-	null	0	已取消
2(堂食)	0	0	null	0	待商家确认
2(堂食)	1	1	null	0	商家备餐中
2(堂食)	2	1	null	0	备餐完成
2(堂食)	3	1	null	0	已完成
2(堂食)	4	-	null	0	已取消

* 表示该字段值不影响展示文字，优先展示 afterSaleStatus 对应文字

---

二、商家端

接口: GET /system/orderShOprate/orderList

参数

参数	类型	必填	说明
token	Header	是	商家身份
page	int	是	页码，从 1 开始
size	int	是	每页条数
tab	String	是	见下表
mdId	Long	是	门店 ID
type	String	否	订单类型筛选：0 / 1 / 2，不传显示全部

Tab 列表

Tab 名称	tab 值	含义	请求示例
待受理	pending	已支付待接单（自取/堂食下单即可见）	?tab=pending&page=1&size=10&mdId=100
待出餐	preparing	已接单备餐中	?tab=preparing&page=1&size=10&mdId=100
已出餐	ready	出餐完成待取/待配送	?tab=ready&page=1&size=10&mdId=100
已完成	completed	已完成订单	?tab=completed&page=1&size=10&mdId=100
已取消	cancelled	已取消订单	?tab=cancelled&page=1&size=10&mdId=100
退款/售后	refund	有售后记录的订单	?tab=refund&page=1&size=10&mdId=100

商家端操作接口

操作	接口	方法	参数	说明
接单	/system/orderShOprate/acceptOrder	POST	id(订单ID)	state 0→1
出餐	/system/orderShOprate/dispatchOrder	GET	id(订单ID)	state 1→2，外送额外设 deliveryStatus=0
完成(自取/堂食)	/system/orderShOprate/completeOrder	POST	id(订单ID)	state 2→3，payStatus 0→1
取消	/system/orderShOprate/cancelOrder	POST	id(订单ID)	state→4，仅限 state=0 或 1

---

三、骑手端

接口: GET /system/orderQsOprate/orderList

参数

参数	类型	必填	说明
token	Header	是	骑手身份（JwtUtil 解析即 qsId）
page	int	是	页码，从 1 开始
size	int	是	每页条数
tab	String	是	见下表
longitude	BigDecimal	条件必填	骑手当前经度（newTask Tab 必填）
latitude	BigDecimal	条件必填	骑手当前纬度（newTask Tab 必填）

Tab 列表

Tab 名称	tab 值	含义	排序	请求示例
新任务	newTask	可抢的外送订单	距离从近到远	?tab=newTask&page=1&size=10&longitude=106.7&latitude=10.8
待取货	toPickup	已接单待取餐	时间从旧到新	?tab=toPickup&page=1&size=10
配送中	delivering	正在配送	时间从旧到新	?tab=delivering&page=1&size=10
已完成	completed	已完成订单	时间从新到旧	?tab=completed&page=1&size=10
已取消	cancelled	已取消订单	时间从新到旧	?tab=cancelled&page=1&size=10
退款/售后	refund	有售后记录的订单	时间从新到旧	?tab=refund&page=1&size=10

骑手端操作接口

操作	接口	方法	参数	说明
接单	/system/orderQsOprate/acceptOrder	POST	id(订单ID)	deliveryStatus→1，绑定 qsId
取餐	/system/orderQsOprate/pickupOrder	POST	id(订单ID)	deliveryStatus→2
送达	/system/orderQsOprate/deliverOrder	POST	id(订单ID)	deliveryStatus→3，state→3

---

四、字段值速查

state（订单状态）

值	含义
0	待处理
1	已接单
2	已出餐
3	已完成
4	已取消

deliveryStatus（配送状态，仅外送 type=0）

值	含义
null	自取/堂食不适用
0	待接单（等待骑手）
1	骑手已接单
2	配送中
3	已送达

payStatus（支付状态）

值	含义
0	未支付
1	已支付
2	已退款

afterSaleStatus（售后状态）

值	含义
0	无售后
1	申请中
2	退款中
3	已退款
4	退款拒绝
5	客服介入
6	售后完成

type（订单类型）

值	含义
0	外送
1	自取
2	堂食