制定闪送重量范围接口实施计划

明确请求、存储、响应、迁移、文档和统一验证步骤。

specs/024-flash-delivery/weight-range-implementation-plan.md

@@ -0,0 +1,96 @@
+# 闪送重量范围接口调整实施计划
+
+> **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` 未进入交付范围。