Почетна Преглед Помоћ
Пријавите се
fa88
/
foodie-server
1
0
Креирај огранак 0
Датотеке Дискусије 0 Захтеви за спајање 0 Вики
Дрво: ac22d30123
Гране Ознаке
foodie-server
/
specs
/
024-flash-delivery
/
weight-range-implementation-plan.md

weight-range-implementation-plan.md 6.7 KB
Историја Датотека

闪送重量范围接口调整实施计划

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 将闪送报价、创建订单、持久化和响应中的精确重量/三档包裹尺寸统一改为设计稿对应的四档 weightRange，并完整更新 App API 文档。

Architecture: FlashDeliveryQuoteRequest 作为报价和创建订单共用的物品输入边界，只接收四值枚举字符串；应用服务集中校验并将其作为订单快照保存。Entity、MyBatis 和各类响应 DTO 使用同名 weightRange，数据库通过人工 SQL 把历史精确重量映射到四档并删除旧字段。

Tech Stack: Java 21、Spring Boot、MyBatis XML、MySQL、JUnit 5、Mockito、AssertJ。

Global Constraints

  • 仅修改闪送重量字段相关代码、测试、规格、API 文档和 SQL，不重构无关代码。
  • Controller 不新增 Map 请求参数；DTO 不使用 Bean Validation 注解，校验继续放在 Service。
  • 数据库变更只追加到 updatesql/sql.md，不得直接执行。
  • 枚举固定为 UP_TO_5_KG、OVER_5_TO_10_KG、OVER_10_TO_15_KG、OVER_15_TO_20_KG。
  • 不保留 totalWeightKg、packageSize 双字段兼容逻辑。
  • 所有实现完成后再统一运行定向测试、模块编译和回归测试。

Task 1: 锁定重量范围契约测试

Files:

  • Modify: ruoyi-admin/src/test/java/com/ruoyi/app/flashdelivery/service/FlashDeliveryApplicationServiceTest.java
  • Modify: ruoyi-admin/src/test/java/com/ruoyi/app/flashdelivery/dto/FlashDeliveryOrderViewTest.java
  • Modify: ruoyi-admin/src/test/java/com/ruoyi/app/flashdelivery/dto/FlashDeliveryRiderOrderListViewTest.java
  • Modify: ruoyi-system/src/test/java/com/ruoyi/system/mapper/flash/FlashDeliveryMapperXmlTest.java

Interfaces:

  • Consumes: 请求字段 String weightRange 和订单字段 String weightRange。

  • Produces: 合法四档、非法旧值、空值、保存快照以及响应字段集合的可执行契约。

  • [ ] 将测试 Fixture 中的 request.setTotalWeightKg(new BigDecimal("3.00")) 改为 request.setWeightRange("UP_TO_5_KG")。

  • [ ] 将创建订单断言改为 assertEquals("UP_TO_5_KG", saved.getValue().getWeightRange())，并删除 totalWeightKg/packageSize 断言。

  • [ ] 用参数化或循环断言覆盖四个合法枚举；为空、SMALL、未知值时断言 flash.delivery.item.invalid 对应的业务异常。

  • [ ] 更新用户、骑手和详情 DTO 的精确字段集合，只保留 weightRange。

  • [ ] 更新 Mapper XML 契约断言，要求 weightRange -> weight_range，不再要求旧属性。

Task 2: 实现统一重量范围模型

Files:

  • Modify: ruoyi-admin/src/main/java/com/ruoyi/app/flashdelivery/dto/FlashDeliveryQuoteRequest.java
  • Modify: ruoyi-admin/src/main/java/com/ruoyi/app/flashdelivery/dto/FlashDeliveryOrderView.java
  • Modify: ruoyi-admin/src/main/java/com/ruoyi/app/flashdelivery/dto/FlashDeliveryUserOrderListView.java
  • Modify: ruoyi-admin/src/main/java/com/ruoyi/app/flashdelivery/dto/FlashDeliveryRiderOrderListView.java
  • Modify: ruoyi-admin/src/main/java/com/ruoyi/app/flashdelivery/service/FlashDeliveryApplicationService.java
  • Modify: ruoyi-system/src/main/java/com/ruoyi/system/domain/flash/FlashDeliveryOrder.java
  • Modify: ruoyi-system/src/main/resources/mapper/flash/FlashDeliveryOrderMapper.xml

Interfaces:

  • Consumes: FlashDeliveryQuoteRequest#getWeightRange(): String。

  • Produces: FlashDeliveryOrder#getWeightRange(): String 以及各响应 DTO 的 weightRange 属性。

  • [ ] 在请求 DTO 中以 String weightRange 替换 BigDecimal totalWeightKg，Javadoc 写明四个枚举和必填规则。

  • [ ] 在订单 Entity、详情、用户列表和骑手列表 DTO 中以 String weightRange 替换 totalWeightKg/packageSize。

  • [ ] 在应用服务定义四值不可变集合 WEIGHT_RANGES，validateItem(...) 校验 weightRange 必填且属于该集合，同时保留数量和规格长度校验。

  • [ ] 创建订单时直接保存 request.getWeightRange()，删除 scaleWeight(...) 和 packageSize(...)。

  • [ ] 更新详情、用户列表和骑手列表映射，原样返回订单的 weightRange。

  • [ ] 更新 MyBatis resultMap 为 <result property="weightRange" column="weight_range"/>，删除旧重量映射。

Task 3: 更新迁移 SQL、规格和 App API 文档

Files:

  • Modify: updatesql/sql.md
  • Modify: specs/024-flash-delivery/spec.md
  • Modify: specs/024-flash-delivery/design.md
  • Modify: specs/024-flash-delivery/data-model.md
  • Modify: specs/024-flash-delivery/contracts/api.md
  • Modify: specs/024-flash-delivery/plan.md
  • Modify: specs/024-flash-delivery/tasks.md
  • Modify: docs/flash-delivery-app-api.md

Interfaces:

  • Consumes: Task 2 的最终字段名和枚举。

  • Produces: 可由前端直接实现的请求说明以及开发者手工执行的数据库迁移。

  • [ ] 在 updatesql/sql.md 追加 2026-09-07 迁移：先按 total_weight_kg 更新 package_size 为四档值，再把 package_size 重命名为 weight_range VARCHAR(24) NOT NULL，最后删除 total_weight_kg；另附超过 20 公斤异常数据的迁移前查询。

  • [ ] 将现有规格内所有当前契约描述改为四档 weightRange，并在任务记录中追加本次变更及验证状态。

  • [ ] 在 docs/flash-delivery-app-api.md 的全局规则、枚举、报价请求、创建订单请求、列表/详情响应、示例和错误处理处删除 totalWeightKg/packageSize，写明 weightRange 必填、四个枚举值、区间和 UI 文案。

  • [ ] 明确报价与创建订单均使用相同的 weightRange 字段格式和校验规则；重量范围当前不参与费用计算。

Task 4: 统一验证与交付检查

Files:

  • Verify: Task 1–3 的全部文件。

Interfaces:

  • Consumes: 完整实现和文档。

  • Produces: 编译、测试、差异与旧字段扫描结果。

  • [ ] 运行旧字段扫描：rg -n "totalWeightKg|packageSize|total_weight_kg|package_size" ruoyi-admin/src ruoyi-system/src docs/flash-delivery-app-api.md specs/024-flash-delivery，仅允许迁移说明或历史背景命中。

  • [ ] 运行定向测试：mvn -pl ruoyi-admin -am -Dtest=FlashDeliveryApplicationServiceTest,FlashDeliveryOrderViewTest,FlashDeliveryRiderOrderListViewTest,FlashDeliveryMapperXmlTest -Dsurefire.failIfNoSpecifiedTests=false test。

  • [ ] 使用 JDK 21 运行模块编译：mvn -pl ruoyi-admin -am -DskipTests compile。

  • [ ] 运行完整回归：mvn test。

  • [ ] 运行 git diff --check 并检查最终文件清单，确保 .claude/homunculus/observations.jsonl 未进入交付范围。