foodie-server/specs/024-flash-delivery/weight-range-design.md

闪送重量范围接口调整设计

背景

用户端设计稿不要求用户输入精确重量，而是从“5 公斤以内、6–10 公斤、11–15 公斤、16–20 公斤”四个范围中选择。现有接口要求提交 totalWeightKg，并由后端生成 SMALL、MEDIUM、LARGE 三档 packageSize，字段语义和分档均与设计稿不一致。

决策

• 报价与创建订单统一使用必填字段 weightRange，不再接收 totalWeightKg。
• weightRange 只允许以下四个稳定枚举值：
  • UP_TO_5_KG：大于 0 且不超过 5 公斤，前端显示“5 公斤以内”。
  • OVER_5_TO_10_KG：超过 5 且不超过 10 公斤，前端显示“6–10 公斤”。
  • OVER_10_TO_15_KG：超过 10 且不超过 15 公斤，前端显示“11–15 公斤”。
  • OVER_15_TO_20_KG：超过 15 且不超过 20 公斤，前端显示“16–20 公斤”。
• API 枚举按连续数值区间命名，避免 UI 整数文案在 5.1 公斤等边界上产生空档。
• 删除 packageSize 的三档派生逻辑。weightRange 本身就是订单的重量档快照，不同时保留第二套重量档字段。
• 本次重量范围只用于物品申报、展示和骑手载重判断，不参与基础配送费、距离费或加急费计算。

接口变化

POST /system/flashDelivery/quote 和 POST /system/flashDelivery/orders 的物品字段调整为：

{
  "packageType": "DOCUMENT",
  "quantity": 1,
  "weightRange": "UP_TO_5_KG",
  "specification": "长 40cm"
}

服务端在字段缺失或值不属于上述枚举时返回国际化的物品信息错误。创建订单仍重新执行与报价相同的校验，不能绕过报价直接写入非法重量档。

订单详情、用户订单列表、骑手订单列表和平台订单数据统一返回 weightRange，不再返回 totalWeightKg 或 packageSize。本次采用前后端同步升级，不增加双字段兼容期，避免旧字段继续产生含义不真实的数据。

数据模型与迁移

• FlashDeliveryOrder 使用 weightRange 保存用户选择快照。
• MyBatis 映射使用数据库字段 weight_range。
• 在 updatesql/sql.md 追加人工迁移 SQL，不直接执行数据库变更。
• 迁移时根据历史 total_weight_kg 将旧订单映射到四档，再将 package_size 调整为 weight_range，最后删除不再使用的 total_weight_kg。
• 历史数据映射边界依次为 <=5、<=10、<=15、<=20；超过 20 公斤的异常历史数据归入最高档并由迁移前查询结果留给开发者确认。

影响范围

• 请求 DTO、订单 Entity、用户/骑手/详情响应 DTO。
• 闪送应用服务的物品校验、订单保存和响应映射。
• MyBatis XML、SQL 更新记录。
• docs/flash-delivery-app-api.md 与 specs/024-flash-delivery 下的现有规格、设计、数据模型、契约、计划和任务。
• 相关服务测试、Controller 契约测试和 Mapper 契约测试。

验收标准

1. 四个合法重量范围均可完成报价和创建订单，并在订单响应中原样返回。
2. 缺失、空字符串、旧枚举值和未知枚举值均被拒绝。
3. 报价与创建订单使用完全相同的重量范围校验。
4. 费用计算结果不因重量范围变化而变化。
5. 代码和文档不再把 totalWeightKg 或 packageSize 作为当前接口字段。
6. SQL 只记录到 updatesql/sql.md，不由本次实现直接执行。