# 闪送配送 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`。

## 地址对象

```json
{"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,minimumPrice,startDistanceMeters,perKmPrice,perMinutePrice,peakMultiplier,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` | `pageNum,pageSize,status?,scene?,serviceType?`；`scene=matching/progress/done/cancelled`；仅本人 |
| 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?,startPrice,minimumPrice,distanceFee,durationFee,subtotal,peakMultiplier,peakFee,amount,currency,pricingVersion`。地址快照字段为联系人、电话、市/区、交付方式、地址、详细地址和经纬度。客户端传入的金额/距离不会被使用。用户详情响应为 `order,images,logs,rider,deliveryPinCode?`，其中 PIN 仅在订单启用时向订单用户返回；骑手详情永不返回 PIN，用户仅在 `ACCEPTED`、`PICKED_UP` 阶段获得骑手位置。

## 骑手端

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

| 方法 | 路径 | 请求/说明 |
|---|---|---|
| GET | `/system/flashDelivery/rider/orders/available` | `pageNum,pageSize,serviceType?`；加急优先，仅返回下述接单前安全字段 |
| GET | `/system/flashDelivery/rider/orders/mine` | `pageNum,pageSize,status?,scene?`；`scene=pickup/delivering/completed/cancelled`；仅本人任务 |
| 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` | `{"imageUrls":["https://.../delivery.jpg"],"pinCode":"4821"}`；图片至少一张，启用 PIN 时必须正确 |

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

## 平台端

| 方法 | 路径 | 请求/说明 |
|---|---|---|
| GET | `/system/flashDelivery/admin/pricing` | 三类当前计价 |
| PUT | `/system/flashDelivery/admin/pricing/{serviceType}` | `startPrice,minimumPrice,startDistanceMeters,perKmPrice,perMinutePrice,peakMultiplier,enabled`；起步价、最低价、距离和公里价为正，每分钟价格非负，尖峰倍率不小于 1，版本原子加一；并发覆盖返回业务错误 |
| 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 |

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