补充闪送接口和请求字段说明

完善闪送 Controller 接口注释及报价、创建、地址、运价等请求字段说明，明确取值、单位和业务含义。

ruoyi-admin/src/main/java/com/ruoyi/app/flashdelivery/controller/FlashDeliveryAdminController.java

@@ -59,6 +59,17 @@ public class FlashDeliveryAdminController extends BaseController {
         return success();
     }
 
+    /**
+     * 分页查询平台闪送订单。
+     *
+     * @param pageNum 页码，从 1 开始，默认 1
+     * @param pageSize 每页数量，默认 10，服务端限制为 1 至 100
+     * @param status 订单状态，选填，精确匹配
+     * @param serviceType 业务场景，选填，仅支持 HELP_SEND 或 HELP_PICKUP
+     * @param orderNo 订单号关键字，选填，模糊匹配
+     * @param userId 发件用户 ID，选填，精确匹配
+     * @param riderId 骑手用户 ID，选填，精确匹配
+     */
     @PreAuthorize("@ss.hasPermi('flash:order:list')")
     @GetMapping("/orders")
     public AjaxResult orders(@RequestParam(defaultValue = "1") int pageNum,

ruoyi-admin/src/main/java/com/ruoyi/app/flashdelivery/controller/FlashDeliveryRiderController.java

@@ -20,7 +20,16 @@ public class FlashDeliveryRiderController extends BaseController {
     private final FlashDeliveryApplicationService service;
     public FlashDeliveryRiderController(FlashDeliveryApplicationService service) { this.service = service; }
 
-    /** 按外卖订单同名页签查询可抢任务或当前骑手自己的任务。 */
+    /**
+     * 按页签查询可抢任务或当前骑手自己的任务。
+     *
+     * @param token 登录令牌，用于解析当前骑手 ID
+     * @param page 页码，从 1 开始，默认 1
+     * @param size 每页数量，默认 10，服务端限制为 1 至 100
+     * @param tab 骑手任务页签：newTask、toPickup、delivering、completed 或 cancelled
+     * @param longitude 骑手当前经度；newTask 页签选填，传入时必须与纬度同时提供
+     * @param latitude 骑手当前纬度；newTask 页签选填，传入时必须与经度同时提供
+     */
     @GetMapping("/orders")
     @Auth
     public AjaxResult orders(@RequestHeader String token,

ruoyi-admin/src/main/java/com/ruoyi/app/flashdelivery/controller/FlashDeliveryUserController.java

@@ -44,7 +44,14 @@ public class FlashDeliveryUserController extends BaseController {
         }
     }
 
-    /** 分页查询当前用户自己的闪送订单。 */
+    /**
+     * 分页查询当前用户参与的闪送订单。
+     *
+     * @param token 登录令牌，用于解析当前用户 ID
+     * @param page 页码，从 1 开始，默认 1
+     * @param size 每页数量，默认 10，服务端限制为 1 至 100
+     * @param role 订单角色；sender 表示我发的，receiver 表示我收的，不传按 sender 处理
+     */
     @GetMapping("/orders")
     @Auth
     public AjaxResult orders(@RequestHeader String token,

ruoyi-admin/src/main/java/com/ruoyi/app/flashdelivery/dto/FlashDeliveryAddressRequest.java

@@ -7,14 +7,30 @@ import java.math.BigDecimal;
 /** 下单或报价使用的联系人和地理坐标快照。 */
 @Data
 public class FlashDeliveryAddressRequest {
+    /** 联系人姓名，必填，去除首尾空格后最长 64 个字符。 */
     private String name;
+
+    /** 联系电话，必填，去除首尾空格后最长 32 个字符。 */
     private String phone;
+
+    /** 完整主地址，必填，去除首尾空格后最长 255 个字符。 */
     private String address;
+
+    /** 门牌、楼层等详细地址，选填，去除首尾空格后最长 255 个字符。 */
     private String addressDetail;
-    /** 市/区仅用于安全区域展示，不得替代完整地址校验。 */
+
+    /** 城市，选填，最长 64 个字符；用于骑手接单前的安全区域展示。 */
     private String city;
+
+    /** 行政区，选填，最长 64 个字符；用于骑手接单前的安全区域展示。 */
     private String area;
+
+    /** 交接方式或联系说明，选填，最长 40 个字符。 */
     private String handoffMethod;
+
+    /** 地址经度，必填，取值范围为 -180 至 180。 */
     private BigDecimal longitude;
+
+    /** 地址纬度，必填，取值范围为 -90 至 90。 */
     private BigDecimal latitude;
 }

ruoyi-admin/src/main/java/com/ruoyi/app/flashdelivery/dto/FlashDeliveryCreateRequest.java

@@ -9,17 +9,36 @@ import java.util.List;
 @Data
 @EqualsAndHashCode(callSuper = true)
 public class FlashDeliveryCreateRequest extends FlashDeliveryQuoteRequest {
-    /** 客户端生成的幂等请求号，同一用户重复提交时返回原订单。 */
+    /**
+     * 客户端生成的幂等请求号，必填，去除首尾空格后最长 64 个字符。
+     * 同一用户使用相同请求号重复提交时，服务端直接返回第一次创建的订单。
+     */
     private String clientRequestId;
-    /** 立即送或预约送；为空时兼容为 NOW。 */
+
+    /** 报价响应中的运价配置 ID，必填，创建时必须原样回传。 */
     private Long pricingId;
+
+    /** 报价响应中的运价版本，必填，创建时必须原样回传。 */
     private Integer pricingVersion;
+
+    /** 报价响应中的基础配送费，必填，整数 TWD，已包含距离费。 */
     private Long quotedBaseDeliveryFee;
+
+    /** 报价响应中的距离附加费，必填，整数 TWD，已包含在基础配送费中。 */
     private Long quotedDistanceFee;
+
+    /** 报价响应中的加急费，必填，整数 TWD；普通配送时为 0。 */
     private Long quotedUrgentFee;
+
+    /** 报价响应中的订单总金额，必填，整数 TWD。 */
     private Long quotedAmount;
-    /** 为空时按补充原型默认启用 PIN。 */
+
+    /** 是否启用四位交付 PIN，选填；不传时默认为 true。 */
     private Boolean pinRequired;
+
+    /** 寄件图片 URL，选填，最多 9 张；每项必须是最长 1000 字符的完整 HTTP(S) URL。 */
     private List<String> senderImageUrls;
+
+    /** 用户对本次闪送的备注，选填，最长 500 个字符。 */
     private String userNote;
 }

ruoyi-admin/src/main/java/com/ruoyi/app/flashdelivery/dto/FlashDeliveryDeliverRequest.java

@@ -7,5 +7,6 @@ import lombok.EqualsAndHashCode;
 @Data
 @EqualsAndHashCode(callSuper = true)
 public class FlashDeliveryDeliverRequest extends FlashDeliveryProofRequest {
+    /** 四位交付 PIN；订单启用 PIN 时必填，未启用时可不传。 */
     private String pinCode;
 }

ruoyi-admin/src/main/java/com/ruoyi/app/flashdelivery/dto/FlashDeliveryPricingRequest.java

@@ -4,16 +4,33 @@ import lombok.Data;
 
 import java.math.BigDecimal;
 
-/** 平台新增或修改闪送时段运价的请求。 */
+/** 平台新增或修改闪送时段运价的请求；开始时间必须早于结束时间，且各运价时段不能重叠。 */
 @Data
 public class FlashDeliveryPricingRequest {
+    /** 运价时段开始时间，必填，格式为 HH:mm，取值范围 00:00 至 23:59，包含该时刻。 */
     private String startTime;
+
+    /** 运价时段结束时间，必填，格式为 HH:mm，取值范围 00:01 至 24:00，不包含该时刻。 */
     private String endTime;
+
+    /** 起步距离，必填，单位为公里，必须大于 0 且不超过 999999.99；服务端按两位小数保存。 */
     private BigDecimal startingDistance;
+
+    /** 起步价，必填，单位为整数 TWD，必须大于 0。 */
     private Long startingFare;
+
+    /** 距离计价步长，必填，单位为公里，必须大于 0 且不超过 999999.99；服务端按两位小数保存。 */
     private BigDecimal distance;
+
+    /** 每个距离计价步长收取的运费，必填，单位为整数 TWD，必须大于 0。 */
     private Long freight;
+
+    /** 加急费比例，必填，单位为百分比，取值范围为 0 至 999999.99；服务端按两位小数保存。 */
     private BigDecimal urgentRate;
+
+    /** 最低加急费，必填，单位为整数 TWD，必须大于或等于 0。 */
     private Long minimumUrgentFee;
+
+    /** 当前运价配置版本；新增时不传，修改时必填，用于防止并发覆盖。 */
     private Integer configVersion;
 }

ruoyi-admin/src/main/java/com/ruoyi/app/flashdelivery/dto/FlashDeliveryProofRequest.java

@@ -7,5 +7,9 @@ import java.util.List;
 /** 骑手取件或送达时提交的图片凭证，业务层要求 1 至 9 张有效 URL。 */
 @Data
 public class FlashDeliveryProofRequest {
+    /**
+     * 履约凭证图片 URL，必填，数量为 1 至 9 张。
+     * 每项必须是最长 1000 个字符且包含主机名的完整 HTTP(S) URL。
+     */
     private List<String> imageUrls;
 }

ruoyi-admin/src/main/java/com/ruoyi/app/flashdelivery/dto/FlashDeliveryQuoteRequest.java

@@ -5,19 +5,64 @@ import lombok.Data;
 import java.math.BigDecimal;
 import java.util.Date;
 
-/** 闪送报价请求，支持帮送、帮取和加急送。 */
+/** 闪送报价请求；帮送/帮取与普通/加急为两个独立维度。 */
 @Data
 public class FlashDeliveryQuoteRequest {
+    /**
+     * 业务场景，必填。
+     * HELP_SEND 表示帮送，HELP_PICKUP 表示帮取；该字段不表示是否加急。
+     */
     private String serviceType;
+
+    /**
+     * 配送等级，必填。
+     * NORMAL 表示普通配送，URGENT 表示一对一加急配送。
+     */
     private String deliveryType;
+
+    /**
+     * 物品类别，必填。
+     * 可选值：DOCUMENT、GIFT、CLOTHING、BEAUTY、DAILY_NECESSITIES、
+     * FOOD_INGREDIENTS、ELECTRONICS、SMALL_APPLIANCE、OTHER。
+     */
     private String packageType;
+
+    /** 物品总数量，必填，必须为大于 0 的整数。 */
     private Integer quantity;
+
+    /**
+     * 物品总重量，必填，单位为千克。
+     * 必须大于 0、不超过 20，且最多保留两位小数；服务端据此生成重量档。
+     */
     private BigDecimal totalWeightKg;
+
+    /** 物品体积、尺寸或其他规格说明，选填，去除首尾空格后最长 255 个字符。 */
     private String specification;
+
+    /** 骑手小费，必填，单位为整数新台币；没有小费时传 0，不参与加急费计算。 */
     private Long tipAmount;
+
+    /**
+     * 取件方式，选填，默认 NOW。
+     * NOW 表示立即取件，SCHEDULED 表示预约取件。
+     */
     private String deliveryMode;
+
+    /**
+     * 预约取件开始时间。
+     * deliveryMode=SCHEDULED 时必填，必须为当前时间之后且不超过未来三天；NOW 时不得传。
+     */
     private Date scheduledPickupStartAt;
+
+    /**
+     * 预约取件结束时间。
+     * deliveryMode=SCHEDULED 时必填，必须比开始时间晚 30 分钟；NOW 时不得传。
+     */
     private Date scheduledPickupEndAt;
+
+    /** 取件联系人、电话、地址、交接方式和经纬度，必填。 */
     private FlashDeliveryAddressRequest pickup;
+
+    /** 收件联系人、电话、地址、交接方式和经纬度，必填。 */
     private FlashDeliveryAddressRequest delivery;
 }

ruoyi-admin/src/main/java/com/ruoyi/app/flashdelivery/dto/FlashDeliveryReasonRequest.java

@@ -5,5 +5,6 @@ import lombok.Data;
 /** 用户或平台取消闪送订单时提交的原因。 */
 @Data
 public class FlashDeliveryReasonRequest {
+    /** 取消原因，必填，去除首尾空格后不能为空且最长 500 个字符。 */
     private String reason;
 }

ruoyi-admin/src/main/java/com/ruoyi/app/flashdelivery/dto/InfoAddressRequest.java

@@ -6,16 +6,39 @@ import java.math.BigDecimal;
 /** 用户地址簿新增/修改请求；userId 永远由 token 决定，不对客户端开放。 */
 @Data
 public class InfoAddressRequest {
+    /** 地址记录 ID；新增时不传，修改时必填且必须属于当前 token 用户。 */
     private Long id;
+
+    /** 联系人姓名，必填，去除首尾空格后最长 64 个字符。 */
     private String name;
+
+    /** 联系电话，必填，去除首尾空格后最长 32 个字符。 */
     private String phone;
+
+    /** 完整主地址，必填，去除首尾空格后最长 255 个字符。 */
     private String address;
+
+    /** 门牌、楼层等详细地址，选填，去除首尾空格后最长 255 个字符。 */
     private String addressDetail;
+
+    /** 地址经度，必填，取值范围为 -180 至 180。 */
     private BigDecimal longitude;
+
+    /** 地址纬度，必填，取值范围为 -90 至 90。 */
     private BigDecimal latitude;
+
+    /** 国家或地区，选填，去除首尾空格后最长 64 个字符。 */
     private String country;
+
+    /** 省、州或一级行政区，选填，去除首尾空格后最长 64 个字符。 */
     private String province;
+
+    /** 城市，选填，去除首尾空格后最长 64 个字符。 */
     private String city;
+
+    /** 区、县或二级行政区，选填，去除首尾空格后最长 64 个字符。 */
     private String area;
+
+    /** 地址附加信息，选填，去除首尾空格后最长 1000 个字符。 */
     private String annexes;
 }

ruoyi-admin/src/main/java/com/ruoyi/app/order/InfoAddressController.java

@@ -45,14 +45,25 @@ public class InfoAddressController extends BaseController {
                 : error(MessageUtils.message("no.map.exception"));
     }
 
-    /** 查询当前用户拥有的地址详情。 */
+    /**
+     * 查询当前用户拥有的地址详情。
+     *
+     * @param token 登录令牌，用于限定地址所有人
+     * @param id 地址记录 ID
+     */
     @Anonymous @Auth
     @GetMapping("/getaddressxq")
     public AjaxResult getaddressxq(@RequestHeader String token, @RequestParam Long id) {
         return success(MessageUtils.message("no.obtained.success"), addressBookService.detail(userId(token), id));
     }
 
-    /** 查询当前用户地址簿中距离给定坐标最近的地址。 */
+    /**
+     * 查询当前用户地址簿中距离给定坐标最近的地址。
+     *
+     * @param token 登录令牌，用于限定地址所有人
+     * @param longitude 当前经度，取值范围 -180 至 180
+     * @param latitude 当前纬度，取值范围 -90 至 90
+     */
     @Anonymous @Auth
     @GetMapping("/getzuijinaddress")
     public AjaxResult getzuijinaddress(@RequestHeader String token, @RequestParam BigDecimal longitude,
@@ -61,7 +72,12 @@ public class InfoAddressController extends BaseController {
                 infoAddressMapper.getmyaddress(longitude, latitude, userId(token).intValue()));
     }
 
-    /** 搜索当前用户地址簿，置顶地址优先。 */
+    /**
+     * 搜索当前用户地址簿，置顶地址优先。
+     *
+     * @param token 登录令牌，用于限定地址所有人
+     * @param keyword 地址或联系人搜索关键字，选填；不传时返回全部地址
+     */
     @Anonymous @Auth
     @GetMapping("/getaddress")
     public AjaxResult getaddress(@RequestHeader String token,