Home Explore Help
Sign In
fa88
/
foodie-server
1
0
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Tree: b7f4fe2b2d
Branches Tags
foodie-server
/
specs
/
024-flash-delivery
/
plan.md

plan.md 19 KB
History Raw

实施计划：闪送配送服务

分支：test | 日期：2026-08-31 | 规格：spec.md

摘要

在既有独立闪送模块上补充包裹类别/重量档、立即或预约配送、可选 PIN 交付、寄件图片、费用明细、页面状态分组、骑手公开摘要和角色安全响应。服务端继续负责路线报价、骑手原子抢单、取件/送达图片、用户签收、24 小时自动完成和平台介入；支付、退款、结算、骑手收入与自动派单仍不在本期范围。

技术上下文

  • 语言/版本：Java 21
  • 主要依赖：Spring Boot、Spring MVC、Spring Security、MyBatis/MyBatis-Plus、Apache HttpClient 4、fastjson2
  • 存储：MySQL；迁移仅记录在 updatesql/sql.md
  • 测试：JUnit 5、Mockito、Spring MockMvc、MyBatis XML 解析测试
  • 目标平台：现有 RuoYi 多模块 REST API 服务端
  • 性能目标：列表分页；抢单和状态流转单条条件更新；地图超时后立即降级
  • 约束：保持 ruoyi-admin -> ruoyi-system；Controller 不接收 Map；App 身份只从 token 解析；业务错误全部 i18n；不执行数据库迁移
  • 范围：24 个闪送/地址端点、4 张新表、1 张地址表增量、五套语言资源、定向自动化测试

规范检查

  • 独立 flash_delivery_* 模型，不复用 pos_order/taxi_order
  • HTTP 集成只放在 ruoyi-admin
  • Controller 使用显式 DTO 和参数注解
  • 用户与骑手接口通过 token 取身份，平台接口使用明确权限
  • 金额、距离和状态由服务端计算与校验
  • 地址、订单和凭证执行所有权/角色校验
  • SQL 只写 updatesql/sql.md
  • 支付能力明确延期

源码结构

ruoyi-system/src/main/java/com/ruoyi/system/
├── domain/flash/                 # 订单、计价、图片、日志实体
└── mapper/flash/                 # 持久化、原子抢单、条件状态流转
ruoyi-system/src/main/resources/mapper/flash/*.xml

ruoyi-admin/src/main/java/com/ruoyi/app/flashdelivery/
├── controller/                   # 用户、骑手、平台 Controller
├── dto/                          # 明确请求 DTO 与响应视图
├── service/                      # 报价、状态机、权限和脱敏
├── route/                        # Google Routes 与直线降级
└── task/                         # 送达 24 小时自动完成

ruoyi-admin/src/test/java/com/ruoyi/app/flashdelivery/
ruoyi-system/src/test/java/com/ruoyi/system/mapper/flash/

地址簿沿用 InfoAddress、IInfoAddressService 和 InfoAddressController，增加请求 DTO、置顶字段、按用户条件查询/更新及所有权测试。

核心实现决策

  1. FlashDeliveryApplicationService 是事务边界；报价只读，创建和每个状态操作同时写订单与日志。
  2. 抢单执行带 status='WAITING_ACCEPTANCE' AND rider_id IS NULL 的单条 UPDATE；受影响行数不是 1 即已被抢走。
  3. 其余状态变更携带订单、操作者、预期状态和版本条件，阻止并发覆盖。
  4. (user_id, client_request_id) 唯一键保证创建幂等；冲突时返回原订单。
  5. Google Routes API 字段掩码仅取距离与时长；异常、非 2xx、空路线或无效距离降级为 Haversine。
  6. 待抢单使用专用脱敏视图；抢单后只有订单骑手可见完整电话和详细地址。
  7. 寄件图片在创建事务中写入；取件/送达图片在状态更新事务中写入。三类凭证均校验 1 至 9 个 HTTP(S) URL，取件和送达不得为空。
  8. 预约订单沿用 WAITING_ACCEPTANCE，可抢查询和原子抢单 SQL 同时限制 scheduled_pickup_start_at <= now，不增加仅为调度使用的新状态。
  9. PIN 默认启用并由服务端生成四位数字；用户详情可见，骑手响应始终剔除，送达事务先校验 PIN 再写凭证和状态。
  10. 用户/骑手使用业务视图，平台详情保留完整审计实体；待抢视图只增加类别、重量档、配送时段、预计时长和市/区级路线信息。
  11. 自动任务扫描送达满 24 小时订单并逐条条件完成，和用户/平台并发时只允许一次成功。

补充原型增量实施批次

  1. 更新规格、API、数据模型和 updatesql/sql.md，明确旧表增量字段及索引。
  2. 先扩展计价器、Mapper XML、应用服务和 Controller 契约测试并确认红灯。
  3. 增加请求/响应 DTO、实体字段、计价明细与角色安全映射。
  4. 实现预约可抢条件、PIN 校验、寄件凭证和状态分组分页。
  5. 使用 JDK 21 运行闪送定向测试、MyBatis XML 测试、模块构建与差异检查。

验证策略

测试先行：先写测试并确认因实现缺失而失败，再添加最小生产代码。最终统一执行：

$env:JAVA_HOME='C:\Users\qmj\.jdks\graalvm-jdk-21.0.7'
$env:PATH="$env:JAVA_HOME\bin;$env:PATH"
mvn -pl ruoyi-system -am -Dtest=FlashDeliveryMapperXmlTest -Dsurefire.failIfNoSpecifiedTests=false test
mvn -pl ruoyi-admin -am -Dtest='FlashDelivery*Test,InfoAddressControllerSecurityTest' -Dsurefire.failIfNoSpecifiedTests=false test
mvn -pl ruoyi-admin -am -DskipTests package
git diff --check

复杂度跟踪

无规范违例。四张新表分别承担订单快照、可变计价、图片凭证和审计日志；应用层留在 admin 是外部 HTTP 依赖和模块边界共同决定的。

平台管理前端增量（2026-09-01）

目标与架构

目标：在 foodie-admin-vue 增加可直接运营的闪送价格配置和订单管理入口，完整消费现有六个平台 API，不修改后端接口语义。

架构：继续使用若依动态菜单加载两个 Vue 2 + Element UI 页面。API 请求集中在一个模块，状态/服务类型映射、分页归一化、操作可见性和价格校验集中在可直接由 Node 测试的纯函数模块；订单详情拆为独立展示组件，避免列表页面同时承担全部渲染职责。

技术栈：Vue 2.6、Element UI 2.15、Vue i18n 8、若依 request、动态 sys_menu、Node 内置 node:test。

全局约束

  • 不新建分支或 worktree，后端与平台前端均在当前 test 分支工作。
  • 不增加 npm 依赖，不引入新的 UI 或状态管理框架。
  • 所有新增用户可见文本使用 flashDelivery.*，并同步简中、繁中、英文、越南文。
  • 前端文件保留 CRLF；只修改本功能文件，不格式化既有大文件。
  • 菜单和权限 SQL 只追加到 foodie_server/updatesql/sql.md，不直接执行数据库变更。
  • 后端分页响应读取 data.records 和 data.total，不得套用若依传统 rows/total 响应。
  • 操作成功后重新读取服务端数据；操作失败不提前修改本地订单状态或价格。

文件结构

foodie-admin-vue/
├── package.json                                      # 增加闪送定向契约测试命令
├── tests/flash-delivery.test.cjs                    # 请求配置、页面规则和四语言真实行为
└── src/
    ├── api/flashDelivery/contracts.js               # 可执行的六个平台请求配置构造器
    ├── api/flashDelivery/index.js                   # 调用若依 request 的六个平台接口
    ├── views/flashDelivery/shared.js                # 枚举、分页、价格校验、操作可见性
    ├── views/flashDelivery/pricing/index.vue        # 三种服务价格列表与编辑弹窗
    ├── views/flashDelivery/orders/index.vue         # 筛选、分页、取消和完成
    ├── views/flashDelivery/orders/OrderDetail.vue   # 完整详情、图片和日志
    └── api/language/language.{zh_CN,zh_TW,en_US,vi}.js

foodie_server/
├── specs/024-flash-delivery/{spec,design,plan,tasks}.md
└── updatesql/sql.md                                 # 父菜单、两个页面及六项权限归位

接口和页面数据流

  1. GET /system/flashDelivery/admin/pricing 返回数组；价格页只显示服务端实际存在的配置，不创建前端默认价格。
  2. PUT /system/flashDelivery/admin/pricing/{serviceType} 提交七个完整字段。弹窗先执行纯函数校验，成功响应覆盖列表对应行。
  3. GET /system/flashDelivery/admin/orders 原样提交 pageNum,pageSize,status,serviceType,orderNo,userId,riderId；normalizePage 从 response.data 提取 records,total,current,size。
  4. GET /system/flashDelivery/admin/orders/{id} 返回 {order,images,logs}；打开详情前先清空旧数据，失败时保持弹窗关闭。
  5. POST .../{id}/cancel 提交 {reason}，只对非 COMPLETED/CANCELLED 状态显示并要求二次确认。
  6. POST .../{id}/complete 无请求体，只对 DELIVERED 状态显示并要求二次确认。

交互设计

  • 价格页使用紧凑表格展示三种服务和版本信息；“编辑”打开宽度 640px 的表单弹窗，金额两位小数、距离单位为米、倍率最小为 1。
  • 订单页顶部使用可折叠行内筛选，表格展示订单号、服务、状态、用户、骑手、距离、金额和创建时间。
  • 详情使用 960px 弹窗，按“订单概况、取送地址、费用与路线、履约与 PIN、图片凭证、状态日志”分区；图片支持预览，空集合显示空状态。
  • 状态使用 Element UI 标签，同时显示本地化文字，避免只靠颜色传达。
  • 表格设置固定操作列和横向滚动容器；页面自身不产生横向溢出。

错误处理

  • 列表和价格请求使用 finally 关闭 loading；后端统一错误拦截负责消息提示。
  • 价格校验失败由表单显示本地化字段错误，不发送请求。
  • 详情请求开始时清空旧详情，请求失败不打开弹窗。
  • 取消原因去除首尾空白后必须非空；取消/完成成功关闭操作层并刷新列表，若详情仍打开则重新读取详情。

测试驱动批次

  1. 先创建 tests/flash-delivery.test.cjs 和 npm 命令，直接执行请求配置构造器、分页、价格校验、状态操作与四语言对象；运行后必须因目标模块不存在而失败。
  2. 实现 API 请求配置、API 封装和 shared.js，使请求、分页、价格校验和状态规则测试转绿。
  3. 实现价格页面与四语言资源，使价格字段和语言一致性测试转绿。
  4. 实现订单页面、详情组件和介入操作；页面调用已经通过测试的状态操作纯函数，权限指令通过 ESLint、构建和页面检查验证。
  5. 追加幂等菜单 SQL，再统一执行定向测试、ESLint、生产构建和两个仓库差异检查。

验证命令

Set-Location E:\QtwCode\foodie\foodie-admin-vue
npm run test:flash-delivery
npx eslint src/api/flashDelivery/index.js src/views/flashDelivery tests/flash-delivery.test.cjs
npm run build:prod
git diff --check

Set-Location E:\QtwCode\foodie\foodie_server
git diff --check

外卖同规则时段运价增量（2026-09-01）

本节替代上方“平台管理前端增量”中的单行价格配置接口、七字段表单和两位小数计价描述；订单管理与平台介入设计继续有效。

目标与架构

目标：将闪送计价改为与现有外卖订单一致的“当前时段 + 起送距离/价格 + 计价距离/金额”规则，移除最低价、时长费、尖峰倍率和启停状态，并让平台在独立闪送入口维护三种服务的多个运价时段。

架构：flash_delivery_pricing 继续作为闪送独立配置表，但从每服务单行改为每服务多时段；flash_delivery_pricing_lock 为三种服务各保存一行事务锁。FlashDeliveryPricingMapper 在数据库当前时间下返回全部匹配时段、提供重叠计数并用 SELECT ... FOR UPDATE 串行化同服务写入；应用服务要求当前时段唯一，异常多行时显式失败。FlashDeliveryPricingCalculator 只负责距离边界和整数 TWD 计算；应用服务负责 CRUD、版本、订单快照和业务错误。平台前端复用现有价格页与权限，改为时段新增、修改和删除。

技术栈：JDK 21、Spring Boot、MyBatis-Plus/MyBatis、MySQL、JUnit 5/Mockito；Vue 2.6、Element UI 2.15、Vue i18n 8、Node node:test。

全局约束

  • 不新建分支或 worktree，后端与平台前端都在当前 test 分支工作。
  • 不直接执行数据库迁移；删除测试阶段旧计价数据和字段的 SQL 只追加到 updatesql/sql.md。
  • 路线预计时长继续保存和展示，但不得参与计价。
  • 起送价格、计价金额、里程费用和最终金额均为整数 TWD；计算结果使用 RoundingMode.HALF_UP 取整到 1 元，不做千位特殊取整。
  • 同一服务类型的时段使用开始包含、结束不包含语义且不得重叠；写操作先取得服务类型数据库行锁再查重，保存即生效，删除即失效，不提供 enabled。
  • Controller 使用明确 DTO 和显式注解，平台配置接口继续使用 flash:pricing:list/edit。
  • 前端新增可见文本同步简中、繁中、英文和越南文，文件保留 CRLF，不增加 npm 依赖。
  • 只修改闪送功能所需文件，不触碰工作区原有脏文件。

文件职责

foodie_server/
├── ruoyi-system/src/main/java/com/ruoyi/system/domain/flash/
│   ├── FlashDeliveryPricing.java          # 时段运价实体
│   └── FlashDeliveryOrder.java            # 整数金额与运价快照
├── ruoyi-system/src/main/java/com/ruoyi/system/mapper/flash/
│   └── FlashDeliveryPricingMapper.java    # 当前时段与重叠查询
├── ruoyi-system/src/main/resources/mapper/flash/
│   └── FlashDeliveryOrderMapper.xml       # 新订单快照字段映射
├── ruoyi-admin/src/main/java/com/ruoyi/app/flashdelivery/
│   ├── controller/FlashDeliveryAdminController.java
│   ├── dto/FlashDeliveryPricingRequest.java
│   ├── dto/FlashDeliveryPriceBreakdown.java
│   ├── dto/FlashDeliveryQuoteView.java
│   ├── dto/FlashDeliveryServiceView.java
│   └── service/{FlashDeliveryApplicationService,FlashDeliveryPricingCalculator}.java
├── ruoyi-admin/src/test/java/com/ruoyi/app/flashdelivery/
│   ├── controller/FlashDeliveryControllerContractTest.java
│   └── service/{FlashDeliveryApplicationServiceTest,FlashDeliveryPricingCalculatorTest}.java
├── ruoyi-admin/src/main/resources/i18n/messages_{zh_CN,zh_TW,en_US,vi}.properties
└── updatesql/sql.md

foodie-admin-vue/
├── src/api/flashDelivery/{contracts,index}.js
├── src/views/flashDelivery/shared.js
├── src/views/flashDelivery/pricing/index.vue
├── src/views/flashDelivery/orders/OrderDetail.vue
├── src/api/language/language.{zh_CN,zh_TW,en_US,vi}.js
└── tests/flash-delivery.test.cjs

后端接口与数据流

  1. FlashDeliveryPricing 使用 startTime,endTime,startingDistance,startingFare,distance,freight；距离为正十进制公里，金额为正 Long。
  2. selectCurrent(serviceType) 使用数据库 CURTIME() 和 start_time <= CURTIME() AND end_time > CURTIME() 返回全部匹配时段；找不到时返回无可用运价错误，超过一条时返回配置重叠错误，不用 LIMIT 1 掩盖异常。
  3. countOverlaps(serviceType,startTime,endTime,excludedId) 使用 start_time < endTime AND end_time > startTime 检测重叠。新增、修改和删除在事务中先锁定 flash_delivery_pricing_lock 对应服务行；跨服务修改按字典序锁定旧、新服务，再校验并写入。
  4. 计价器签名改为 calculateBreakdown(FlashDeliveryPricing pricing, int distanceMeters)。超出公里小于 0.5 时计费公里为 0，小于 1 时为 1，否则使用实际超出公里；distanceFee 四舍五入为 Long，amount=startingFare+distanceFee。
  5. GET /admin/pricing 返回全部时段；POST /admin/pricing 新增；PUT /admin/pricing/{id} 按版本更新；DELETE /admin/pricing/{id} 删除。新增、修改和删除都使用 flash:pricing:edit。
  6. home 对三种服务分别读取当前时段，只返回有配置的服务；quote/create 每次重新读取当前时段并计算。订单固化 pricingId,pricingVersion,pricingStartTime,pricingEndTime,startingDistance,startingFare,distance,freight,distanceFee。
  7. 报价与公开服务 DTO 移除旧计价字段，保留 estimatedDurationSeconds；金额 DTO 和订单实体改为整数 Long。

平台前端交互

  • 价格页表格按服务类型、开始时间排序，列出起止时间、起送距离/价格、计价距离/金额、版本和更新时间。
  • “新增时段”打开空表单；“编辑”回填完整配置；“删除”二次确认后请求服务端并刷新列表。
  • 表单校验开始时间早于结束时间、距离为正数、金额为正整数，并用当前列表预检同服务时段重叠；服务端仍执行最终重叠校验。
  • 页面不显示启停、最低价、每分钟价格或尖峰倍率。配置保存后立即生效，无匹配时段时由后端阻止报价。
  • 订单详情展示匹配时段、起送距离/价格、计价距离/金额、里程费用和整数总额；预计时长仍显示在路线信息中。

TDD 批次

  1. 先改 FlashDeliveryPricingCalculatorTest，覆盖起送内、超出 0.49/0.50/0.99/1.20 公里、非 1 公里计价距离、.5 金额四舍五入及非法配置；确认旧实现编译或断言失败。
  2. 再改应用服务和 Controller 契约测试，覆盖当前时段读取、无时段、重叠新增/修改、版本冲突、删除、整数快照和新路由；确认旧接口失败。
  3. 实现实体、并发锁表、Mapper、DTO、计算器、应用服务、Controller 和四语言后端错误，使定向后端测试转绿。
  4. 先改 Node 测试，要求新增/修改/删除请求、六字段载荷、时段/整数校验、页面权限和四语言新 key，并确认旧前端失败。
  5. 实现前端请求、纯函数、价格页、订单详情与四语言，使 Node 测试转绿。
  6. 追加开发阶段重建 SQL，删除旧闪送测试表并创建运价锁、时段配置及新订单快照最终结构；不执行 SQL。

验证命令

Set-Location E:\QtwCode\foodie\foodie_server
$env:JAVA_HOME='C:\Users\qmj\.jdks\graalvm-jdk-21.0.7'
$env:PATH="$env:JAVA_HOME\bin;$env:PATH"
mvn -pl ruoyi-admin -am -Dtest='FlashDeliveryPricingCalculatorTest,FlashDeliveryApplicationServiceTest,FlashDeliveryControllerContractTest,FlashDeliveryOrderViewTest,FlashDeliveryAvailableOrderViewTest,FlashDeliveryI18nContractTest' -Dsurefire.failIfNoSpecifiedTests=false test
mvn -pl ruoyi-admin -am -DskipTests package
git diff --check

Set-Location E:\QtwCode\foodie\foodie-admin-vue
npm run test:flash-delivery
npx eslint --no-ignore src/api/flashDelivery/index.js src/api/flashDelivery/contracts.js src/views/flashDelivery/shared.js src/views/flashDelivery/pricing/index.vue src/views/flashDelivery/orders/index.vue src/views/flashDelivery/orders/OrderDetail.vue tests/flash-delivery.test.cjs
npm run build:prod
git diff --check