维护时间格式

alien-dining/src/main/java/shop/alien/dining/controller/DiningController.java

@@ -35,7 +35,7 @@ public class DiningController {
     private final DiningWalkInReservationService diningWalkInReservationService;
     private final AlienStoreFeign alienStoreFeign;
 
-    @ApiOperation(value = "提交到店就餐信息", notes = "选完人数并填写姓名/电话/时段后调用：写入 user_reservation，状态为已到店(2)，并关联当前桌；同时将 store_table 置为就餐中(1)、写入 diner_count（与 page-info 首客传人数一致），便于 /table-dining-status。返回预约ID。下单时可不传 userReservationId，后端将按 tableId 解析本桌当日有效预约。")
+    @ApiOperation(value = "提交到店就餐信息", notes = "选完人数并填写姓名/电话/时段后调用：写入 user_reservation，状态为已到店(2)，并关联当前桌；同时将 store_table 置为就餐中(1)、写入 diner_count（与 page-info 首客传人数一致），便于 /table-dining-status。返回预约ID。下单时可不传 userReservationId，后端将按 tableId 解析本桌当日有效预约。startTime、endTime（若传）必须为 yyyy-MM-dd HH:mm（两位时分、无秒）；不传 endTime 由后端推算。可选 reservationDate 须与 startTime 日期一致。")
     @PostMapping("/walk-in/reservation")
     public R<Integer> createWalkInReservation(@Valid @RequestBody DiningWalkInReservationDTO dto) {
         log.info("DiningController.createWalkInReservation?tableId={}", dto != null ? dto.getTableId() : null);
@@ -52,11 +52,12 @@ public class DiningController {
         }
     }
 
-    @ApiOperation(value = "【小程序】按门店与餐桌查询预约详情列表", notes = "内部 Feign 调用门店 GET /user/reservation/detailByStoreAndTableRecord。userReservationTableId 为 store_table.id。reservationDate 为 yyyy-MM-dd 可选。免登录，与门店接口一致。")
+    @ApiOperation(value = "按门店与桌号查询预约详情列表", notes = "Feign 门店 GET /user/reservation/detailByStoreAndTableRecord。userReservationTableId 实为 store_table.id（user_reservation_table.table_id），勿传关联表主键。"
+            + "reservationDate 即 yyyy-MM-dd，可选。免登录，与门店接口一致。")
     @GetMapping("/reservation/detail-by-store-table-record")
     public R<List<UserReservationVo>> reservationDetailByStoreAndTableRecord(
             @ApiParam(value = "门店ID", required = true) @RequestParam Integer storeId,
-            @ApiParam(value = "餐桌ID（store_table.id）", required = true) @RequestParam Integer userReservationTableId,
+            @ApiParam(value = "桌号ID（store_table.id）", required = true) @RequestParam Integer userReservationTableId,
             @ApiParam(value = "预订日期 yyyy-MM-dd，不传则不过滤") @RequestParam(required = false) String reservationDate) {
         log.info("DiningController.reservationDetailByStoreAndTableRecord?storeId={}, userReservationTableId={}, reservationDate={}",
                 storeId, userReservationTableId, reservationDate);

alien-dining/src/main/java/shop/alien/dining/service/impl/DiningWalkInReservationServiceImpl.java

@@ -32,7 +32,8 @@ import java.util.concurrent.ThreadLocalRandom;
 import java.util.stream.Collectors;
 
 /**
- * 点餐流程：填写就餐信息 → 写 user_reservation + user_reservation_table（已到店），并更新 store_table 为就餐中；不产生 user_reservation_order
+ * 点餐流程：填写就餐信息 → 写 user_reservation + user_reservation_table（已到店），并更新 store_table 为就餐中；不产生 user_reservation_order。
+ * <p>到店就餐入参：{@code startTime}、若填写 {@code endTime} 仅允许 {@code yyyy-MM-dd HH:mm}（24h，时分各两位）；库内同格式。</p>
  */
 @Slf4j
 @Service
@@ -44,13 +45,23 @@ public class DiningWalkInReservationServiceImpl extends ServiceImpl<UserReservat
     private final UserReservationTableMapper userReservationTableMapper;
 
     private static final int STATUS_ARRIVED = 2;
+    /** 与 {@link UserReservation#getType()} 一致：小程序/扫码点餐填写到店信息 → app扫码 */
+    private static final int RESERVATION_SOURCE_APP_SCAN = 1;
     /** 占桌状态：与其它预订冲突检测范围内 */
     private static final ZoneId SHANGHAI = ZoneId.of("Asia/Shanghai");
     /** 未填结束时间时，按 N 小时作为占用窗口做冲突判断（与订金预订「结束时间」空值场景对齐） */
     private static final int DEFAULT_BLOCK_HOURS_WHEN_NO_END = 4;
+    /** 库内标准；到店入参同此格式 */
+    private static final DateTimeFormatter YMD_HM = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm");
+    /** 冲突检测：历史行可能含秒、或仅存时分 */
+    private static final DateTimeFormatter[] STORED_DATE_TIME_FORMATTERS = new DateTimeFormatter[]{
+            DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"),
+            YMD_HM,
+            DateTimeFormatter.ofPattern("yyyy-MM-dd H:mm:ss"),
+            DateTimeFormatter.ofPattern("yyyy-MM-dd H:mm")
+    };
+    /** 冲突检测：仅存时分的历史行 */
     private static final DateTimeFormatter HM = DateTimeFormatter.ofPattern("HH:mm");
-    /** 与订桌/库内既有数据一致：varchar 存 yyyy-MM-dd HH:mm */
-    private static final DateTimeFormatter STORE_DATE_TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm");
 
     @Override
     @Transactional(rollbackFor = Exception.class)
@@ -63,21 +74,34 @@ public class DiningWalkInReservationServiceImpl extends ServiceImpl<UserReservat
             throw new RuntimeException("桌号不存在");
         }
 
-        Date reservationDate = dto.getReservationDate();
-        if (reservationDate == null) {
-            reservationDate = Date.from(LocalDate.now(SHANGHAI).atStartOfDay(SHANGHAI).toInstant());
+        String startRaw = dto.getStartTime() != null ? dto.getStartTime().trim() : null;
+        if (!StringUtils.hasText(startRaw)) {
+            throw new RuntimeException("开始时间不能为空");
         }
+        LocalDateTime startLdt = parseYmdHmOrNull(startRaw);
+        if (startLdt == null) {
+            throw new RuntimeException("开始时间须为 yyyy-MM-dd HH:mm，例如 2026-03-28 18:30");
+        }
+        if (dto.getReservationDate() != null) {
+            LocalDate dtoDay = dto.getReservationDate().toInstant().atZone(SHANGHAI).toLocalDate();
+            if (!dtoDay.equals(startLdt.toLocalDate())) {
+                throw new RuntimeException("预约日期须与开始时间的日期一致");
+            }
+        }
+        Date reservationDate = Date.from(startLdt.toLocalDate().atStartOfDay(SHANGHAI).toInstant());
 
-        LocalDate day = reservationDate.toInstant().atZone(SHANGHAI).toLocalDate();
-        LocalTime newStartLt = parseTimeOfDayOnly(dto.getStartTime());
-        if (newStartLt == null) {
-            throw new RuntimeException("开始时间格式不正确，请使用 HH:mm");
+        String endRaw = trimOrNull(dto.getEndTime());
+        LocalDateTime endLdt;
+        if (endRaw == null) {
+            endLdt = windowEnd(startLdt.toLocalDate(), startLdt.toLocalTime(), null);
+        } else {
+            endLdt = parseYmdHmOrNull(endRaw);
+            if (endLdt == null) {
+                throw new RuntimeException("结束时间须为 yyyy-MM-dd HH:mm，例如 2026-03-28 20:00");
+            }
         }
-        LocalTime newEndLt = parseTimeOfDayOnly(dto.getEndTime());
-        assertNoTableBookingConflict(table.getId(), table.getStoreId(), day, newStartLt, newEndLt);
 
-        LocalDateTime startLdt = LocalDateTime.of(day, newStartLt);
-        LocalDateTime endLdt = windowEnd(day, newStartLt, newEndLt);
+        assertNoTableBookingConflict(table.getId(), table.getStoreId(), startLdt, endLdt);
 
         Date now = new Date();
         UserReservation entity = new UserReservation();
@@ -85,11 +109,12 @@ public class DiningWalkInReservationServiceImpl extends ServiceImpl<UserReservat
         entity.setUserId(userId);
         entity.setStoreId(table.getStoreId());
         entity.setReservationDate(reservationDate);
-        entity.setStartTime(startLdt.format(STORE_DATE_TIME));
-        entity.setEndTime(endLdt.format(STORE_DATE_TIME));
+        entity.setStartTime(startLdt.format(YMD_HM));
+        entity.setEndTime(endLdt.format(YMD_HM));
         entity.setGuestCount(dto.getGuestCount());
         entity.setCategoryId(table.getCategoryId());
         entity.setStatus(STATUS_ARRIVED);
+        entity.setType(RESERVATION_SOURCE_APP_SCAN);
         entity.setActualArrivalTime(now);
         entity.setRemark(trimOrNull(dto.getRemark()));
         entity.setReservationUserName(trimOrNull(dto.getReservationUserName()));
@@ -108,8 +133,7 @@ public class DiningWalkInReservationServiceImpl extends ServiceImpl<UserReservat
         link.setUpdatedUserId(userId);
         userReservationTableMapper.insert(link);
 
-        // 与 getDiningPageInfo 首客传人数一致：提交就餐信息成功后，餐桌置为就餐中并写入人数，
-        // 便于 /table-dining-status 与其它用户跳过「选人数」前置。
+        // 与 page-info 首客传人数一致：便于 /table-dining-status
         Integer st = table.getStatus();
         if (st == null || st == 0 || st == 2) {
             table.setStatus(1);
@@ -136,11 +160,23 @@ public class DiningWalkInReservationServiceImpl extends ServiceImpl<UserReservat
         return "RV" + System.currentTimeMillis() + ThreadLocalRandom.current().nextInt(1000, 9999);
     }
 
+    /** 到店入参仅接受 yyyy-MM-dd HH:mm */
+    private static LocalDateTime parseYmdHmOrNull(String raw) {
+        if (!StringUtils.hasText(raw)) {
+            return null;
+        }
+        try {
+            return LocalDateTime.parse(raw.trim(), YMD_HM);
+        } catch (DateTimeParseException e) {
+            return null;
+        }
+    }
+
     /**
      * 与其它有效预订（同桌、同日、状态为待确认/已确认/已到店）时段是否重叠；重叠则不允许到店就餐。
      */
-    private void assertNoTableBookingConflict(Integer tableId, Integer storeId, LocalDate day,
-                                              LocalTime newStart, LocalTime newEnd) {
+    private void assertNoTableBookingConflict(Integer tableId, Integer storeId,
+                                              LocalDateTime newStartLdt, LocalDateTime newEndLdt) {
         List<UserReservationTable> links = userReservationTableMapper.selectList(
                 new LambdaQueryWrapper<UserReservationTable>()
                         .eq(UserReservationTable::getTableId, tableId)
@@ -155,8 +191,7 @@ public class DiningWalkInReservationServiceImpl extends ServiceImpl<UserReservat
         if (resIds.isEmpty()) {
             return;
         }
-        LocalDateTime newStartLdt = LocalDateTime.of(day, newStart);
-        LocalDateTime newEndLdt = windowEnd(day, newStart, newEnd);
+        LocalDate day = newStartLdt.toLocalDate();
 
         List<UserReservation> others = new ArrayList<>(this.listByIds(resIds));
         if (others.isEmpty()) {
@@ -173,11 +208,11 @@ public class DiningWalkInReservationServiceImpl extends ServiceImpl<UserReservat
             if (otherDay == null || !day.equals(otherDay)) {
                 continue;
             }
-            LocalDateTime oStartLdt = parseStoredStartLdt(otherDay, other.getStartTime());
+            LocalDateTime oStartLdt = parseOtherReservationStart(otherDay, other.getStartTime());
             if (oStartLdt == null) {
                 continue;
             }
-            LocalDateTime oEndLdt = parseStoredEndLdt(oStartLdt, other.getEndTime());
+            LocalDateTime oEndLdt = parseOtherReservationEnd(oStartLdt, other.getEndTime());
             if (newStartLdt.isBefore(oEndLdt) && oStartLdt.isBefore(newEndLdt)) {
                 log.warn("到店就餐信息与既有预订冲突 tableId={} day={} new=[{} - {}] otherResId={} other=[{} - {}]",
                         tableId, day, newStartLdt, newEndLdt, other.getId(), oStartLdt, oEndLdt);
@@ -198,38 +233,13 @@ public class DiningWalkInReservationServiceImpl extends ServiceImpl<UserReservat
         return d.toInstant().atZone(SHANGHAI).toLocalDate();
     }
 
-    /** 仅时分：HH:mm / H:mm */
-    private static LocalTime parseTimeOfDayOnly(String raw) {
-        if (!StringUtils.hasText(raw)) {
-            return null;
-        }
-        String s = raw.trim();
-        if (s.contains(" ")) {
-            s = s.substring(s.lastIndexOf(' ') + 1).trim();
-        }
-        try {
-            return LocalTime.parse(s, HM);
-        } catch (DateTimeParseException e) {
-            try {
-                return LocalTime.parse(s, DateTimeFormatter.ofPattern("H:mm"));
-            } catch (DateTimeParseException e2) {
-                return null;
-            }
-        }
-    }
-
-    private static LocalDateTime tryParseFullDateTime(String raw) {
+    /** 库内既有预订：整段日期时间（可含秒） */
+    private static LocalDateTime parseStoredDateTimeOrNull(String raw) {
         if (!StringUtils.hasText(raw) || !raw.trim().contains(" ")) {
             return null;
         }
         String s = raw.trim();
-        DateTimeFormatter[] fmps = new DateTimeFormatter[]{
-                DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"),
-                DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm"),
-                DateTimeFormatter.ofPattern("yyyy-MM-dd H:mm:ss"),
-                DateTimeFormatter.ofPattern("yyyy-MM-dd H:mm")
-        };
-        for (DateTimeFormatter f : fmps) {
+        for (DateTimeFormatter f : STORED_DATE_TIME_FORMATTERS) {
             try {
                 return LocalDateTime.parse(s, f);
             } catch (DateTimeParseException ignored) {
@@ -238,12 +248,12 @@ public class DiningWalkInReservationServiceImpl extends ServiceImpl<UserReservat
         return null;
     }
 
-    private static LocalDateTime parseStoredStartLdt(LocalDate reservationDay, String raw) {
+    private static LocalDateTime parseOtherReservationStart(LocalDate reservationDay, String raw) {
         if (!StringUtils.hasText(raw)) {
             return null;
         }
         String s = raw.trim();
-        LocalDateTime full = tryParseFullDateTime(s);
+        LocalDateTime full = parseStoredDateTimeOrNull(s);
         if (full != null) {
             return full;
         }
@@ -254,25 +264,45 @@ public class DiningWalkInReservationServiceImpl extends ServiceImpl<UserReservat
         return LocalDateTime.of(reservationDay, t);
     }
 
-    private static LocalDateTime parseStoredEndLdt(LocalDateTime startLdt, String endRaw) {
+    private static LocalDateTime parseOtherReservationEnd(LocalDateTime startLdt, String endRaw) {
         if (startLdt == null) {
             return null;
         }
         if (!StringUtils.hasText(endRaw)) {
             return windowEnd(startLdt.toLocalDate(), startLdt.toLocalTime(), null);
         }
-        String s = endRaw.trim();
-        LocalDateTime full = tryParseFullDateTime(s);
+        String w = endRaw.trim();
+        LocalDateTime full = parseStoredDateTimeOrNull(w);
         if (full != null) {
             return full;
         }
-        LocalTime endT = parseTimeOfDayOnly(s);
+        LocalTime endT = parseTimeOfDayOnly(w);
         if (endT == null) {
             return windowEnd(startLdt.toLocalDate(), startLdt.toLocalTime(), null);
         }
         return windowEnd(startLdt.toLocalDate(), startLdt.toLocalTime(), endT);
     }
 
+    /** 仅时分：HH:mm / H:mm（含「日期 + 空格 + 时分」时取末段） */
+    private static LocalTime parseTimeOfDayOnly(String raw) {
+        if (!StringUtils.hasText(raw)) {
+            return null;
+        }
+        String s = raw.trim();
+        if (s.contains(" ")) {
+            s = s.substring(s.lastIndexOf(' ') + 1).trim();
+        }
+        try {
+            return LocalTime.parse(s, HM);
+        } catch (DateTimeParseException e) {
+            try {
+                return LocalTime.parse(s, DateTimeFormatter.ofPattern("H:mm"));
+            } catch (DateTimeParseException e2) {
+                return null;
+            }
+        }
+    }
+
     /**
      * 预约结束时刻：结束早于或等于开始（同一张日历日上的钟点）则视为跨日至次日；结束时间为空则用默认时长。
      */

alien-entity/src/main/java/shop/alien/entity/store/dto/DiningWalkInReservationDTO.java

@@ -8,6 +8,7 @@ import lombok.Data;
 import javax.validation.constraints.Min;
 import javax.validation.constraints.NotBlank;
 import javax.validation.constraints.NotNull;
+import javax.validation.constraints.Pattern;
 import javax.validation.constraints.Size;
 import java.util.Date;
 
@@ -27,15 +28,17 @@ public class DiningWalkInReservationDTO {
     @Min(value = 1, message = "人数至少为1")
     private Integer guestCount;
 
-    @ApiModelProperty(value = "预约日期，不传则默认当天（上海时区）")
+    @ApiModelProperty(value = "预约日期 yyyy-MM-dd，可选；若传须与 startTime 的日期一致（由开始时间可推导时可不传）")
     @JsonFormat(pattern = "yyyy-MM-dd", timezone = "GMT+8")
     private Date reservationDate;
 
-    @ApiModelProperty(value = "开始时间 HH:mm（与 reservation_date 组合；入库为 yyyy-MM-dd HH:mm）", required = true)
+    @ApiModelProperty(value = "开始时间，仅 yyyy-MM-dd HH:mm（两位时分，不带秒）", required = true, example = "2026-03-28 18:30")
     @NotBlank(message = "开始时间不能为空")
+    @Pattern(regexp = "\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}", message = "开始时间须为 yyyy-MM-dd HH:mm")
     private String startTime;
 
-    @ApiModelProperty(value = "结束时间 HH:mm；若早于当日开始钟点则视为次日结束。选填；入库为 yyyy-MM-dd HH:mm，不填则按占位规则写出结束时刻")
+    @ApiModelProperty(value = "结束时间，可选；若填写须为 yyyy-MM-dd HH:mm（与 startTime 同格式、无秒）。不传则后端按占用窗口推算后入库", example = "2026-03-28 20:00")
+    @Pattern(regexp = "^(\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2})?$", message = "结束时间须为 yyyy-MM-dd HH:mm 或留空")
     private String endTime;
 
     @ApiModelProperty(value = "就餐人姓名")

alien-store/src/main/java/shop/alien/store/controller/UserReservationController.java

@@ -176,14 +176,15 @@ public class UserReservationController {
     }
 
     /**
-     * 根据门店ID和多个 user_reservation_table 主键ID，查询该店铺这些桌记录对应的用户预约信息列表。
+     * 根据门店与桌号（store_table.id）查询该桌关联的有效预约详情列表。
      */
-    @ApiOperation("根据门店与预约桌记录ID列表查询预约详情列表")
+    @ApiOperation(value = "根据门店与桌号查询预约详情列表", notes = "userReservationTableId 为 store_table.id（对应 user_reservation_table.table_id），勿传 user_reservation_table 表主键。"
+            + "过滤已取消、用餐结束及已过结束时间的记录；可按 reservationDate 限定日历日。")
     @ApiOperationSupport(order = 9)
     @ApiImplicitParams({
-            @ApiImplicitParam(name = "storeId", value = "门店ID", dataType = "Integer", paramType = "query", required = true),
-            @ApiImplicitParam(name = "userReservationTableId", value = "user_reservation_table 表主键ID（或餐桌ID）", dataType = "Integer", paramType = "query", required = true),
-            @ApiImplicitParam(name = "reservationDate", value = "预订日期 yyyy-MM-dd，不传则不按日期过滤", dataType = "String", paramType = "query", required = false)
+            @ApiImplicitParam(name = "storeId", value = "门店ID", dataType = "int", paramType = "query", required = true),
+            @ApiImplicitParam(name = "userReservationTableId", value = "桌号ID（store_table.id）", dataType = "int", paramType = "query", required = true),
+            @ApiImplicitParam(name = "reservationDate", value = "预订日期 yyyy-MM-dd，不传则不过滤日期", dataType = "string", paramType = "query", required = false, format = "date")
     })
     @GetMapping("/detailByStoreAndTableRecord")
     public R<List<UserReservationVo>> detailByStoreAndTableRecord(

alien-store/src/main/java/shop/alien/store/controller/dining/StoreDiningPathProxyController.java

@@ -2,6 +2,7 @@ package shop.alien.store.controller.dining;
 
 import io.swagger.annotations.Api;
 import io.swagger.annotations.ApiOperation;
+import io.swagger.annotations.ApiParam;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.web.bind.annotation.*;
@@ -35,9 +36,10 @@ public class StoreDiningPathProxyController {
         return h;
     }
 
-    @ApiOperation("查询餐桌是否处于就餐中")
+    @ApiOperation(value = "查询餐桌是否处于就餐中", notes = "免登录。就餐中(status=1)、加餐(status=3) 且 diner_count 有值时 inDining=true，供前端判断是否跳过选人数。")
     @GetMapping("/table-dining-status")
-    public R<TableDiningStatusVO> getTableDiningStatus(@RequestParam Integer tableId) {
+    public R<TableDiningStatusVO> getTableDiningStatus(
+            @ApiParam(value = "桌号ID（store_table.id）", required = true) @RequestParam Integer tableId) {
         try {
             return diningServiceFeign.getTableDiningStatus(tableId);
         } catch (Exception e) {
@@ -46,7 +48,9 @@ public class StoreDiningPathProxyController {
         }
     }
 
-    @ApiOperation("提交到店就餐信息（写入预约表，已到店；返回预约ID供下单绑定）")
+    @ApiOperation(value = "提交到店就餐信息", notes = "需 Authorization。写入 user_reservation（已到店），关联本桌；store_table 置就餐中并写 diner_count。返回预约ID。"
+            + "startTime、若传的 endTime 须为 yyyy-MM-dd HH:mm（无秒）；不传 endTime 由后端推算；可选 reservationDate 须与 startTime 同日。"
+            + "与同桌有效预订时段冲突时报错。请求体见 DiningWalkInReservationDTO。")
     @PostMapping("/walk-in/reservation")
     public R<Integer> createWalkInReservation(HttpServletRequest request, @Valid @RequestBody DiningWalkInReservationDTO dto) {
         try {
@@ -57,13 +61,14 @@ public class StoreDiningPathProxyController {
         }
     }
 
-    @ApiOperation("【小程序】按门店与餐桌查询预约详情（透传点餐 → Feign 门店，与 APP 直调 /user/reservation/detailByStoreAndTableRecord 等价）")
+    @ApiOperation(value = "按门店与桌号查询有效预约详情列表", notes = "透传 alien-dining → 门店 GET /user/reservation/detailByStoreAndTableRecord，与 APP 直调该路径等价；Authorization 可选。"
+            + "参数 userReservationTableId 实际为 store_table.id（即 user_reservation_table.table_id），勿传 user_reservation_table 主键。")
     @GetMapping("/reservation/detail-by-store-table-record")
     public R<List<UserReservationVo>> reservationDetailByStoreAndTableRecord(
             HttpServletRequest request,
-            @RequestParam Integer storeId,
-            @RequestParam Integer userReservationTableId,
-            @RequestParam(required = false) String reservationDate) {
+            @ApiParam(value = "门店ID", required = true) @RequestParam Integer storeId,
+            @ApiParam(value = "桌号ID（store_table.id）", required = true) @RequestParam Integer userReservationTableId,
+            @ApiParam(value = "预订日期 yyyy-MM-dd，不传则不过滤日期") @RequestParam(required = false) String reservationDate) {
         try {
             return diningServiceFeign.reservationDetailByStoreAndTableRecord(
                     auth(request), storeId, userReservationTableId, reservationDate);
@@ -73,12 +78,12 @@ public class StoreDiningPathProxyController {
         }
     }
 
-    @ApiOperation("获取点餐页面信息")
+    @ApiOperation(value = "获取点餐页面信息", notes = "需登录。首客传就餐人数；餐桌已就餐中时可省略人数，使用表中已保存人数。")
     @GetMapping("/page-info")
     public R<DiningPageInfoVO> getDiningPageInfo(
             HttpServletRequest request,
-            @RequestParam Integer tableId,
-            @RequestParam(required = false) Integer dinerCount) {
+            @ApiParam(value = "桌号ID（store_table.id）", required = true) @RequestParam Integer tableId,
+            @ApiParam(value = "就餐人数，首客必传；已就餐中可省略") @RequestParam(required = false) Integer dinerCount) {
         try {
             return diningServiceFeign.getDiningPageInfo(auth(request), tableId, dinerCount);
         } catch (Exception e) {