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。
• packageType：DOCUMENT、GIFT、CLOTHING、BEAUTY、DAILY_NECESSITIES、FOOD_INGREDIENTS、ELECTRONICS、SMALL_APPLIANCE、OTHER。
• packageSize：SMALL（不超过 5kg）、MEDIUM（不超过 12kg）、LARGE（不超过 20kg）；不提交精确重量。
• deliveryMode：NOW、SCHEDULED。预约起止时间使用 ISO 日期时间，时段固定 30 分钟且开始时间不晚于三天后。
• 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,pricingId,startTime,endTime,startingDistance,startingFare,distance,freight,pricingVersion,currency；不返回内部更新人、时间或地图密钥
POST	/system/flashDelivery/quote	serviceType,packageType,packageSize,pickup,delivery
POST	/system/flashDelivery/orders	报价请求字段 + clientRequestId,deliveryMode,scheduledPickupStartAt?,scheduledPickupEndAt?,pinRequired?,senderImageUrls?,userNote?；服务端重算并幂等创建
GET	/system/flashDelivery/orders	page,size；仅本人，按创建时间倒序返回全部状态的用户列表摘要
GET	/system/flashDelivery/orders/{id}	本人 App 订单详情；data 直接为订单字段，不返回原始状态日志
POST	/system/flashDelivery/orders/{id}/cancel	{"reason":"行程变化"}；仅待接/已接
POST	/system/flashDelivery/orders/{id}/confirmReceipt	无 body；仅 DELIVERED

用户列表摘要字段固定为：id,orderNo,serviceType,status,packageType,deliveryMode,scheduledPickupStartAt,scheduledPickupEndAt,pickupAddress,pickupDetailAddress,deliveryAddress,deliveryDetailAddress,estimatedDurationSeconds,amount,currency,deliveredAt,createTime。列表不返回联系人、电话、精确坐标、照片、日志或计价审计字段。

报价响应 data：serviceType,pricingId,startTime,endTime,distanceMeters,distanceSource,estimatedDurationSeconds?,startingDistance,startingFare,distance,freight,billableDistance,distanceFee,amount,currency,pricingVersion。billableDistance 为按外卖规则处理 0.5 公里边界后的计费公里数，distanceFee 与 amount 为整数 TWD。地址快照字段为联系人、电话、市/区、交付方式、地址、详细地址和经纬度。客户端传入的金额/距离不会被使用。用户创建和详情响应的 data 直接为订单详情字段，照片分别为 senderImageUrls,pickupImageUrls,deliveryImageUrls，不返回原始状态日志；deliveryPinCode 仅在启用时向订单用户返回，用户仅在 ACCEPTED、PICKED_UP 阶段获得骑手位置。

骑手端

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

方法	路径	请求/说明
GET	/system/flashDelivery/rider/orders	page,size,tab,longitude?,latitude?；参数方式与骑手外卖列表一致，tab=newTask/toPickup/delivering/completed/cancelled；坐标用于新任务附近范围、取件点距离和排序
GET	/system/flashDelivery/rider/orders/{id}	data 直接为稳定的骑手订单详情；未接单隐藏敏感字段，接单后仅订单骑手可见完整履约信息
POST	/system/flashDelivery/rider/orders/{id}/accept	原子抢单，成功后 data 直接返回骑手订单详情
POST	/system/flashDelivery/rider/orders/{id}/pickup	{"imageUrls":["https://.../pickup.jpg"]}；至少一张
POST	/system/flashDelivery/rider/orders/{id}/deliver	{"imageUrls":["https://.../delivery.jpg"],"pinCode":"4821"}；图片至少一张，启用 PIN 时必须正确

骑手页签状态映射：newTask=WAITING_ACCEPTANCE、toPickup=ACCEPTED、delivering=PICKED_UP、completed=DELIVERED+COMPLETED、cancelled=CANCELLED。除 newTask 外只返回当前骑手本人任务；闪送没有 refund 页签。

骑手列表摘要字段固定为：id,orderNo,serviceType,status,packageType,packageSize,deliveryMode,scheduledPickupStartAt,scheduledPickupEndAt,pinRequired,pickupAddress,pickupDetailAddress,deliveryAddress,deliveryDetailAddress,pickupDistanceMeters,distanceMeters,estimatedDurationSeconds,amount,currency,createTime。newTask 分页 data 在 records,total,current,size 外增加 nearbyTaskCount,highestOrderAmount；不返回尖峰倍率或骑手收入字段。

骑手接单前可按原型查看完整取送文字地址，但不返回用户 ID、联系人、电话、实际 PIN、精确经纬度、备注、幂等请求号、履约凭证或日志。抢单成功后才向中单骑手返回完整联系方式、坐标和有权限查看的照片数组。骑手详情在接单前后使用同一个直接 DTO，不返回 {order,images,logs} 包装，也不要求 App 判断 data.order。

平台端

方法	路径	请求/说明
GET	/system/flashDelivery/admin/pricing	返回全部运价时段，按服务类型和开始时间排序
POST	/system/flashDelivery/admin/pricing	serviceType,startTime,endTime,startingDistance,startingFare,distance,freight；保存即生效
PUT	/system/flashDelivery/admin/pricing/{id}	与新增相同的完整请求体；版本原子加一，并发覆盖返回业务错误
DELETE	/system/flashDelivery/admin/pricing/{id}	删除运价时段并立即停止用于报价
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

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

运价时段使用业务当地时间和 HH:mm 格式，采用开始时间包含、结束时间不包含的匹配语义；24:00 只允许作为结束时间，跨午夜时段必须拆成两个配置。同一服务类型的时间段不得重叠。起送距离和计价距离必须为正数，起送价格和计价金额必须为正整数；当前时间没有匹配时段时，用户首页不返回该服务，报价和创建接口返回“当前时段暂无可用运价”。