# 闪送配送服务设计记录 本文件记录 2026-08-31 已经逐项确认的设计决策，作为后续 `plan.md`、`tasks.md` 和接口契约的输入。 ## 1. 设计来源 蓝湖“闪送”分组共 7 个页面，均已通过蓝湖 MCP 读取图片、设计标注、颜色与图层： 1. 地址薄 2. 闪送 取 3. 首页202608 4. 填写收件信息 5. 闪送 加急 6. 闪送 7. 闪送 送 最初的蓝湖 7 页明确展示三种服务、取件与收件地址、联系人和电话、地址簿、起步价格及下单入口，未展示重量和类别；2026-08-24 用户端/骑手端补充原型进一步明确包裹类别、重量档、预约配送、交付 PIN、寄件图片和费用明细。两套设计均未明确支付、代购、精确重量或件数规则。 ## 2. 架构决策 采用独立闪送订单模块，不复用 `pos_order` 或 `taxi_order`。 ```text 用户端 / 骑手端 / 平台端 | v ruoyi-admin - 用户、骑手、平台 Controller - 报价编排与地图路线适配器 - 闪送状态流转与自动完成任务 - 通知编排 | v ruoyi-system - 闪送领域实体、Mapper、Service - 计价配置、配送凭证、状态日志 - 共享地址所有权数据访问 ``` 外部地图 HTTP 集成位于 `ruoyi-admin`，保持 `ruoyi-admin -> ruoyi-system` 的模块依赖方向。SQL 只写入 `updatesql/sql.md`，由开发者手动执行。 ## 3. 接口边界 ### 3.1 用户端 - `GET /system/flashDelivery/home` - `POST /system/flashDelivery/quote` - `POST /system/flashDelivery/orders` - `GET /system/flashDelivery/orders` - `GET /system/flashDelivery/orders/{id}` - `POST /system/flashDelivery/orders/{id}/cancel` - `POST /system/flashDelivery/orders/{id}/confirmReceipt` ### 3.2 骑手端 - `GET /system/flashDelivery/rider/orders/available` - `GET /system/flashDelivery/rider/orders/mine` - `GET /system/flashDelivery/rider/orders/{id}` - `POST /system/flashDelivery/rider/orders/{id}/accept` - `POST /system/flashDelivery/rider/orders/{id}/pickup` - `POST /system/flashDelivery/rider/orders/{id}/deliver` ### 3.3 平台端 - `GET /system/flashDelivery/admin/pricing` - `PUT /system/flashDelivery/admin/pricing/{serviceType}` - `GET /system/flashDelivery/admin/orders` - `GET /system/flashDelivery/admin/orders/{id}` - `POST /system/flashDelivery/admin/orders/{id}/cancel` - `POST /system/flashDelivery/admin/orders/{id}/complete` 平台管理前端沿用 `foodie-admin-vue` 的 Vue 2、Element UI、动态菜单和权限指令，不额外引入 UI 或状态管理依赖： - “闪送管理”作为父菜单，“价格配置”和“闪送订单”作为两个子页面。 - `src/api/flashDelivery/index.js` 集中封装六个平台接口，页面不直接拼接请求。 - 价格配置页以三种服务配置表为主体，编辑弹窗承载数值校验；保存后以服务端响应刷新当前行。 - 订单页以服务端分页表格为主体，详情弹窗分区展示概况、地址、费用、凭证和日志；取消原因使用独立输入弹窗，完成操作使用二次确认。 - 操作按钮同时使用状态条件和 `v-hasPermi` 控制可见性，后端权限与状态机仍是最终安全边界。 - 所有新增文本集中在四个前端语言文件的 `flashDelivery` 对象中，key 集合保持一致。 ### 3.4 共享地址簿 - `GET /system/address/getaddress` - `GET /system/address/getaddressxq` - `POST /system/address/address` - `DELETE /system/address/{id}` - `POST /system/address/{id}/top` 地址接口继续由现有收货与闪送场景共用，但所有用户接口都必须携带 token；后端按当前登录用户限制详情、保存、删除和置顶范围。 ## 4. 数据结构方向 ### 4.1 `flash_delivery_order` 保存订单号、客户端请求号、用户、骑手、服务类型、包裹类别、重量档、配送方式、预约时段、交付 PIN、取件与收件信息快照、路线距离、距离来源、预计时长、报价金额与费用明细、币种、计价配置版本、备注、状态、并发版本号、关键操作时间与取消信息。 ### 4.2 `flash_delivery_pricing` 按服务类型保存起步价、最低价、起步距离、每公里价格、每分钟价格、尖峰倍率、启用状态、配置版本、修改人和修改时间。 ### 4.3 `flash_delivery_order_image` 保存订单、凭证类型、图片 URL、排序、操作人类型、操作人和创建时间。凭证类型包括 `SENDER`、`PICKUP` 与 `DELIVERY`。 ### 4.4 `flash_delivery_order_log` 保存变更前状态、变更后状态、操作人类型、操作人 ID、原因和时间。 ### 4.5 `info_address` 增加置顶标记和置顶时间；列表按置顶时间与既有排序规则返回。 ## 5. 计价与距离 ```text 超距公里 = max(0, 距离 - 起步距离) / 1000米 里程费 = 超距公里 * 每公里价格 时长费 = 预计时长秒 / 60 * 每分钟价格 小计 = 起步价 + 里程费 + 时长费 尖峰费 = 小计 * (尖峰倍率 - 1) 价格 = max(最低价, 小计 + 尖峰费) ``` 超距公里和路线分钟按实际小数单位计费，不向上取整；里程费、时长费、小计、尖峰费和最终价格分别使用十进制定点数并保留两位小数，尖峰倍率不得小于 1。帮送、帮取和加急送分别拥有独立配置；加急送不由客户端提交系数。报价优先使用地图路线距离，失败时降级为直线距离。创建订单时服务端必须重新报价并固化快照。 ## 6. 状态机 ```text WAITING_ACCEPTANCE | | 骑手原子抢单 v ACCEPTED | | 订单骑手 + 取件图片 v PICKED_UP | | 订单骑手 + 送达图片 v DELIVERED | | 用户确认 / 24小时自动完成 / 平台完成 v COMPLETED ``` `WAITING_ACCEPTANCE` 和 `ACCEPTED` 允许订单用户取消。`PICKED_UP` 和 `DELIVERED` 只有平台能够介入取消。任一允许取消状态进入 `CANCELLED`。`COMPLETED` 与 `CANCELLED` 为终态。 ## 7. 安全与隐私 - 用户、骑手身份只从请求头 token 解析，不从请求体读取。 - 用户订单查询和操作按 `order_id + user_id` 校验。 - 骑手履约操作按 `order_id + rider_id + expected_status` 校验。 - 骑手抢单使用数据库条件更新，避免双抢。 - 待抢订单隐藏完整电话与详细门牌；抢单后才向订单骑手展示。 - 地址操作按 `address_id + user_id` 校验，客户端 `userId` 不参与归属判断。 - Controller 使用明确 DTO、`@RequestBody`、`@RequestParam`、`@PathVariable` 和 `@RequestHeader`，不接收 Map。 - 地图密钥不返回客户端、不写日志；业务错误使用国际化消息。 ## 8. 测试方向 - 计价边界和配置版本测试。 - 地图路线成功、失败及直线降级测试。 - 地址和订单跨用户访问测试。 - 多骑手并发抢单测试。 - 取件与送达图片必填测试。 - 全部允许和禁止状态流转测试。 - 24 小时自动完成与并发幂等测试。 - 平台权限和配置校验测试。 - MyBatis XML 字段、条件更新与索引契约测试。 - 平台前端 API 路径、方法、参数和权限字符串契约测试。 - 平台前端价格校验、状态操作可见性和四语言 key 一致性测试。 - 平台前端 ESLint、生产构建和常用后台宽度的页面检查。 ## 9. 明确延期内容 支付、退款、分账、骑手收入、代购、垫付、商品金额、精确重量、件数、自动派单、动态附近骑手数、预计接单时间以及用户端、骑手端和商家端页面均不在本期范围。