foodie-server/specs/024-flash-delivery/contracts/api.md

闪送配送 API 契约

通用约定

• 用户/骑手端要求请求头 token，身份字段不进入请求体。
• 平台权限：flash:pricing:list/edit、flash:order:list/query/cancel/complete。
• 响应沿用 AjaxResult：{"code":200,"msg":"...","data":...}；分页 data 为 records,total,current,size。
• 金额为 TWD 两位小数，距离为米。
• serviceType：HELP_SEND、HELP_PICKUP、URGENT。
• status：WAITING_ACCEPTANCE、ACCEPTED、PICKED_UP、DELIVERED、COMPLETED、CANCELLED。

地址对象

{"name":"王小明","phone":"0912345678","address":"台北市信义区市府路1号","addressDetail":"3楼A室","longitude":121.5645,"latitude":25.0330,"country":"TW","province":"台北市","city":"台北市","area":"信义区","annexes":""}

方法	路径	参数/说明
GET	/system/address/getaddress	header token；query keyword?；仅本人，搜索并置顶优先
GET	/system/address/getaddressxq	header token；query id；仅本人
POST	/system/address/address	header token；body 地址对象，可含 id；忽略 userId
DELETE	/system/address/{id}	header token；仅本人
POST	/system/address/{id}/top	header token；仅本人

用户端

方法	路径	请求/说明
GET	/system/flashDelivery/home	三类启用服务和计价摘要 serviceType,startPrice,startDistanceMeters,perKmPrice,pricingVersion,currency；不返回内部更新人、时间或地图密钥
POST	/system/flashDelivery/quote	serviceType,pickup,delivery
POST	/system/flashDelivery/orders	报价请求字段 + clientRequestId + userNote?；服务端重算并幂等创建
GET	/system/flashDelivery/orders	pageNum,pageSize,status?,serviceType?；仅本人
GET	/system/flashDelivery/orders/{id}	本人完整详情、凭证和日志
POST	/system/flashDelivery/orders/{id}/cancel	{"reason":"行程变化"}；仅待接/已接
POST	/system/flashDelivery/orders/{id}/confirmReceipt	无 body；仅 DELIVERED

报价响应 data：serviceType,distanceMeters,distanceSource,estimatedDurationSeconds?,amount,currency,pricingVersion。地址快照字段为联系人、电话、地址、详细地址和经纬度。客户端传入的金额/距离不会被使用。

骑手端

所有接口要求 token 用户 userType=2。

方法	路径	请求/说明
GET	/system/flashDelivery/rider/orders/available	pageNum,pageSize,serviceType?；加急优先，仅返回下述接单前安全字段
GET	/system/flashDelivery/rider/orders/mine	pageNum,pageSize,status?；仅本人任务
GET	/system/flashDelivery/rider/orders/{id}	未接单仅返回接单前安全字段；接单后仅订单骑手可见完整信息
POST	/system/flashDelivery/rider/orders/{id}/accept	原子抢单，成功返回完整详情
POST	/system/flashDelivery/rider/orders/{id}/pickup	{"imageUrls":["https://.../pickup.jpg"]}；至少一张
POST	/system/flashDelivery/rider/orders/{id}/deliver	同上；至少一张

接单前安全字段固定为：id,orderNo,serviceType,status,pickupLatitudeApprox,pickupLongitudeApprox,deliveryLatitudeApprox,deliveryLongitudeApprox,distanceMeters,amount,currency,createTime。近似经纬度只保留两位小数；不返回用户 ID、联系人、电话、文字地址、精确经纬度、备注、幂等请求号、凭证或日志。抢单成功后才向中单骑手返回完整详情。

平台端

方法	路径	请求/说明
GET	/system/flashDelivery/admin/pricing	三类当前计价
PUT	/system/flashDelivery/admin/pricing/{serviceType}	startPrice,startDistanceMeters,perKmPrice,enabled；正数，版本原子加一；并发覆盖返回业务错误
GET	/system/flashDelivery/admin/orders	分页；可按状态、类型、订单号、用户、骑手筛选
GET	/system/flashDelivery/admin/orders/{id}	完整详情、凭证、日志
POST	/system/flashDelivery/admin/orders/{id}/cancel	reason 必填；非终态可取消
POST	/system/flashDelivery/admin/orders/{id}/complete	无 body；仅 DELIVERED

本期没有支付、退款、结算、骑手收入、代购/垫付、重量、品类、件数、违禁品确认、骑手放弃或自动派单字段和接口。