chore: sync local updates

mengyastore-backend-go/internal/handlers/order.go

@@ -195,17 +195,18 @@ func qrFromOrder(orderID, productID string) string {
 }
 
 // CreateOrder 创建订单（结账）。需登录与否取决于商品 requireLogin；Bearer 可选传入以关联账户与限购。
-// @Summary 结账创建订单
+// @Summary 结账并创建订单
+// @Description 根据商品配置决定是否需要登录（`requireLogin`）。可附带 `Authorization: Bearer` 以关联账号、限购与通知邮箱。付费订单走萌芽支付时需商品已配置收款码；同一商品在他人待支付锁定期内可能返回 409；同一账号存在待支付单时也可能冲突。成功返回订单概要及二维码链接等。
 // @Tags 订单
 // @Accept json
 // @Produce json
-// @Param Authorization header string false "Bearer 用户 token（部分商品必填）"
-// @Param body body CheckoutPayload true "结账参数"
+// @Param Authorization header string false "可选；格式 Bearer + 空格 + token，部分商品必填"
+// @Param body body CheckoutPayload true "结账请求体：商品、数量、联系方式等"
 // @Success 200 {object} SwaggerCheckoutWrap
 // @Failure 400 {object} SwaggerErrorBody
 // @Failure 401 {object} SwaggerErrorBody
 // @Failure 404 {object} SwaggerErrorBody
-// @Failure 409 {object} SwaggerErrorBody "库存锁定冲突或同用户待支付"
+// @Failure 409 {object} SwaggerErrorBody "库存锁定冲突（他人正在支付）或同账号待支付单未满间隔"
 // @Failure 500 {object} SwaggerErrorBody
 // @Router /api/checkout [post]
 func (h *OrderHandler) CreateOrder(c *gin.Context) {
@@ -339,6 +340,9 @@ func (h *OrderHandler) CreateOrder(c *gin.Context) {
 			"viewCount":       updatedProduct.ViewCount,
 			"status":          created.Status,
 			"paymentMethod":   payment.MethodMengya,
+			"deliveredCodes":  created.DeliveredCodes,
+			"deliveryMode":    created.DeliveryMode,
+			"isManual":        created.DeliveryMode == "manual",
 		}
 		c.JSON(http.StatusOK, gin.H{"data": resp})
 		return
@@ -469,14 +473,15 @@ func confirmResponse(order models.Order) gin.H {
 }
 
 // ConfirmOrder 用户确认订单状态（手动核销、待支付轮询后取货等）。
-// @Summary 确认订单
+// @Summary 确认订单（核销/完成流程）
+// @Description 用于用户侧「确认」动作：已完成订单直接返回数据；待支付时若仍未到账则 409；已取消或超时 410。手动发货等场景下会触发邮件通知（若配置）。
 // @Tags 订单
 // @Produce json
-// @Param id path string true "订单 ID"
+// @Param id path string true "订单ID"
 // @Success 200 {object} SwaggerConfirmWrap
 // @Failure 404 {object} SwaggerErrorBody
-// @Failure 409 {object} SwaggerErrorBody "待支付未到账等"
-// @Failure 410 {object} SwaggerErrorBody "已取消或超时"
+// @Failure 409 {object} SwaggerErrorBody "待支付但金额未核对到账等"
+// @Failure 410 {object} SwaggerErrorBody "订单已取消或已超过待支付时限"
 // @Router /api/orders/{id}/confirm [post]
 func (h *OrderHandler) ConfirmOrder(c *gin.Context) {
 	orderID := c.Param("id")
@@ -543,10 +548,11 @@ func (h *OrderHandler) ConfirmOrder(c *gin.Context) {
 }
 
 // GetOrderPaymentStatus 前端轮询订单支付状态（不返回卡密）。
-// @Summary 订单支付状态
+// @Summary 查询订单支付状态（轮询）
+// @Description 供前端轮询待支付订单：返回状态、应付快照、过期时间等；不包含卡密等敏感发货内容。路径参数为订单 ID。
 // @Tags 订单
 // @Produce json
-// @Param id path string true "订单 ID"
+// @Param id path string true "订单ID"
 // @Success 200 {object} SwaggerPaymentStatusWrap
 // @Failure 404 {object} SwaggerErrorBody
 // @Router /api/orders/{id}/payment-status [get]
@@ -665,11 +671,12 @@ func clampOneLine(s string, maxRunes int) string {
 }
 
 // MengyaPaymentWebhook 萌芽支付到账通知（Body 为渠道 JSON）。若配置 WEBHOOK_MENGYA_SECRET 则必须带 X-Webhook-Secret。
-// @Summary 萌芽支付 Webhook
+// @Summary 萌芽支付到账 Webhook
+// @Description 由支付渠道/转发服务 POST 原始 JSON；服务端解析到账金额并尝试匹配待支付订单。若配置 `WEBHOOK_MENGYA_SECRET`，请求头 `X-Webhook-Secret` 必须与其一致。本地联调与生产 `https://store.shumengya.top` 均使用同一路径，由部署时的域名与 TLS 决定回调 URL。
 // @Tags Webhook
 // @Accept json
 // @Produce json
-// @Param X-Webhook-Secret header string false "与 WEBHOOK_MENGYA_SECRET 一致"
+// @Param X-Webhook-Secret header string false "与进程环境变量 WEBHOOK_MENGYA_SECRET 一致；未配置密钥时可不填"
 // @Success 200 {object} SwaggerWebhookMengyaResp
 // @Failure 400 {object} SwaggerErrorBody
 // @Failure 403 {object} SwaggerErrorBody
@@ -744,10 +751,11 @@ func (h *OrderHandler) MengyaPaymentWebhook(c *gin.Context) {
 }
 
 // CancelOrder 用户取消待支付订单并释放预留库存（当前实现不校验 Bearer，凭订单 ID 操作）。
-// @Summary 取消订单
+// @Summary 取消待支付订单
+// @Description 仅对允许取消的状态生效（如待支付）；已完成订单会冲突。成功时释放预留库存/卡密占用。请勿在公网暴露此能力时省略鉴权策略（实现以代码为准）。
 // @Tags 订单
 // @Produce json
-// @Param id path string true "订单 ID"
+// @Param id path string true "订单ID"
 // @Success 200 {object} SwaggerCancelWrap
 // @Failure 404 {object} SwaggerErrorBody
 // @Failure 409 {object} SwaggerErrorBody
@@ -782,7 +790,8 @@ func (h *OrderHandler) CancelOrder(c *gin.Context) {
 }
 
 // ListMyOrders 当前登录用户的订单列表（待支付条目不返回卡密）。
-// @Summary 我的订单
+// @Summary 查询当前登录用户的订单列表
+// @Description 必须携带有效 Bearer。列表中处于待支付状态的订单不会包含已分配卡密等敏感字段，防止泄露。
 // @Tags 订单
 // @Produce json
 // @Security BearerAuth