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

> **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: 合法四档、非法旧值、空值、保存快照以及响应字段集合的可执行契约。

- [x] 将测试 Fixture 中的 `request.setTotalWeightKg(new BigDecimal("3.00"))` 改为 `request.setWeightRange("UP_TO_5_KG")`。
- [x] 将创建订单断言改为 `assertEquals("UP_TO_5_KG", saved.getValue().getWeightRange())`，并删除 `totalWeightKg/packageSize` 断言。
- [x] 用参数化或循环断言覆盖四个合法枚举；为空、`SMALL`、未知值时断言 `flash.delivery.item.invalid` 对应的业务异常。
- [x] 更新用户、骑手和详情 DTO 的精确字段集合，只保留 `weightRange`。
- [x] 更新 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`
- Modify: `ruoyi-admin/src/main/resources/i18n/messages.properties`
- Modify: `ruoyi-admin/src/main/resources/i18n/messages_en_US.properties`
- Modify: `ruoyi-admin/src/main/resources/i18n/messages_zh_CN.properties`
- Modify: `ruoyi-admin/src/main/resources/i18n/messages_zh_TW.properties`
- Modify: `ruoyi-admin/src/main/resources/i18n/messages_vi.properties`
- Modify: `ruoyi-admin/src/main/resources/i18n/messages_th_TH.properties`

**Interfaces:**
- Consumes: `FlashDeliveryQuoteRequest#getWeightRange(): String`。
- Produces: `FlashDeliveryOrder#getWeightRange(): String` 以及各响应 DTO 的 `weightRange` 属性。

- [x] 在请求 DTO 中以 `String weightRange` 替换 `BigDecimal totalWeightKg`，Javadoc 写明四个枚举和必填规则。
- [x] 在订单 Entity、详情、用户列表和骑手列表 DTO 中以 `String weightRange` 替换 `totalWeightKg/packageSize`。
- [x] 在应用服务定义四值不可变集合 `WEIGHT_RANGES`，`validateItem(...)` 校验 `weightRange` 必填且属于该集合，同时保留数量和规格长度校验。
- [x] 创建订单时直接保存 `request.getWeightRange()`，删除 `scaleWeight(...)` 和 `packageSize(...)`。
- [x] 更新详情、用户列表和骑手列表映射，原样返回订单的 `weightRange`。
- [x] 更新 MyBatis `resultMap` 为 `<result property="weightRange" column="weight_range"/>`，删除旧重量映射。
- [x] 更新默认、英文、简体、繁体、越南语和泰语的物品信息错误提示，将精确重量改为重量范围。

### 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: 可由前端直接实现的请求说明以及开发者手工执行的数据库迁移。

- [x] 在 `updatesql/sql.md` 追加 2026-09-07 迁移：先按 `total_weight_kg` 更新 `package_size` 为四档值，再把 `package_size` 重命名为 `weight_range VARCHAR(24) NOT NULL`，最后删除 `total_weight_kg`；另附超过 20 公斤异常数据的迁移前查询。
- [x] 将现有规格内所有当前契约描述改为四档 `weightRange`，并在任务记录中追加本次变更及验证状态。
- [x] 在 `docs/flash-delivery-app-api.md` 的全局规则、枚举、报价请求、创建订单请求、列表/详情响应、示例和错误处理处删除 `totalWeightKg/packageSize`，写明 `weightRange` 必填、四个枚举值、区间和 UI 文案。
- [x] 明确报价与创建订单均使用相同的 `weightRange` 字段格式和校验规则；重量范围当前不参与费用计算。

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

**Files:**
- Verify: Task 1–3 的全部文件。

**Interfaces:**
- Consumes: 完整实现和文档。
- Produces: 编译、测试、差异与旧字段扫描结果。

- [x] 运行旧字段扫描：`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`，仅允许迁移说明或历史背景命中。
- [x] 运行定向测试：`mvn -pl ruoyi-admin -am -Dtest=FlashDeliveryApplicationServiceTest,FlashDeliveryOrderViewTest,FlashDeliveryRiderOrderListViewTest,FlashDeliveryMapperXmlTest -Dsurefire.failIfNoSpecifiedTests=false test`。
- [x] 使用 JDK 21 运行模块编译：`mvn -pl ruoyi-admin -am -DskipTests compile`。
- [x] 运行完整回归：`mvn test`。
- [x] 运行 `git diff --check` 并检查最终文件清单，确保 `.claude/homunculus/observations.jsonl` 未进入交付范围。

验证结果：定向测试 50 项通过，JDK 21 模块编译成功，完整回归 401 项通过；SQL 仅写入迁移记录，未执行数据库操作。