chore: sync local updates

mengyastore-backend-go/main.go

@@ -1,6 +1,12 @@
 // @title 萌芽小店 API
 // @version 1.0.0-go
-// @description 商品、下单、站点统计、收藏与客服聊天；用户登录由萌芽账户认证中心（SproutGate）校验。监听地址以 HTTP_LISTEN_ADDR 为准。
+// @description 萌芽小店电商后端 HTTP API：商品、下单结账、订单与支付、站点统计与访问、维护模式、收藏、用户/管理员聊天、萌芽支付 Webhook，以及管理端商品/订单/站点与运维状态等。用户身份由萌芽账户认证中心（SproutGate）签发令牌并完成校验。
+// @description
+// @description **运行环境与基地址**
+// @description - **本地开发**：监听地址由环境变量 `HTTP_LISTEN_ADDR` 决定，未设置时默认为 `:8080`，即常见入口 `http://localhost:8080`。可在浏览器打开 `http://localhost:8080/swagger/index.html` 查看本页同款文档并调试。
+// @description - **生产部署**：线上前台/API 域名为 `https://store.shumengya.top`（HTTPS）
+// @description
+// @description **说明**：本 OpenAPI 由代码注释生成；与进程真实监听、反向代理头无关，仅作契约参考。
 // @host localhost:8080
 // @BasePath /
 // @schemes http https
@@ -8,17 +14,17 @@
 // @securityDefinitions.apikey BearerAuth
 // @in header
 // @name Authorization
-// @description 用户访问令牌，格式: Bearer 空格 + token
+// @description 用户访问令牌：请求头 `Authorization`，值为 `Bearer ` 后接 SproutGate 返回的 JWT/access token（部分公开接口可不携带）。
 
 // @securityDefinitions.apikey AdminToken
 // @in header
 // @name X-Admin-Token
-// @description 管理端令牌（也可使用 Authorization 头或 query token，见各接口说明）
+// @description 管理端访问令牌：与进程环境变量 `ADMIN_TOKEN` 一致。部分管理路由也可使用 `Authorization` 头或 Query `token`（以具体路由实现为准）。
 
 // @securityDefinitions.apikey WebhookSecret
 // @in header
 // @name X-Webhook-Secret
-// @description 与服务端 WEBHOOK_MENGYA_SECRET 一致时校验萌芽支付 Webhook
+// @description 当服务端配置了 `WEBHOOK_MENGYA_SECRET` 时，萌芽支付到账回调 `POST /api/webhooks/mengya-pay` 需携带本头且值与密钥完全一致，否则返回 403。
 package main
 
 import (
@@ -84,8 +90,8 @@ func accessLog() gin.HandlerFunc {
 }
 
 // rootAPIInfo 浏览器或客户端访问服务根路径时返回 API 说明（JSON）。
-// @Summary API 根信息与端点索引
-// @Description 返回服务描述、主要路径指引与版本（非 OpenAPI 详尽列表，完整契约见 /swagger）。
+// @Summary 根路径 API 说明与路由索引
+// @Description 访问服务根路径 `/` 返回 JSON：服务简介、本地与生产环境说明、主要业务路由分组、运行版本与时间戳。完整请求/响应模型请使用 Swagger UI：`GET /swagger/index.html`。
 // @Tags 元信息
 // @Produce json
 // @Success 200 {object} map[string]interface{}
@@ -97,6 +103,10 @@ func rootAPIInfo(c *gin.Context) {
 	}
 	c.JSON(http.StatusOK, gin.H{
 		"description": "萌芽小店电商后端：商品、下单、站点统计、收藏与客服聊天；用户登录认证由萌芽账户认证中心（SproutGate）校验。",
+		"environments": gin.H{
+			"local":      "本地开发：默认 http://localhost:8080（以 HTTP_LISTEN_ADDR 为准）",
+			"production": "生产部署：https://store.shumengya.top（若经反代请用实际对外地址）",
+		},
 		"endpoints": gin.H{
 			"health":     "/api/health",
 			"public":     "/api/products, /api/checkout, /api/stats, /api/site/*, POST /api/products/:id/view",
@@ -116,9 +126,10 @@ func rootAPIInfo(c *gin.Context) {
 
 // HealthCheck 返回进程与可选 RabbitMQ 探活结果。
 // @Summary 健康检查
+// @Description 用于负载均衡或编排探活：`status` 恒为 ok 表示 HTTP 服务存活；`rabbitmq` 为 `disabled`（未启用消息队列客户端）、`ok`（连接可用）或以 `error:` 开头的错误片段。
 // @Tags 健康检查
 // @Produce json
-// @Success 200 {object} map[string]interface{} "status ok；rabbitmq 为 disabled|ok|error:..."
+// @Success 200 {object} map[string]interface{} "status 为 ok；rabbitmq 为 disabled、ok 或 error: 前缀错误信息"
 // @Router /api/health [get]
 func HealthCheck(mqClient *mq.Client) gin.HandlerFunc {
 	return func(c *gin.Context) {
@@ -229,6 +240,7 @@ func main() {
 	chatHandler := handlers.NewChatHandler(chatStore, authClient)
 	statusHandler := handlers.NewSystemStatusHandler(cfg, db, mqClient, startedAt)
 
+	// 公开路由
 	r.GET("/api/products", publicHandler.ListProducts)
 	r.POST("/api/checkout", orderHandler.CreateOrder)
 	r.GET("/api/orders/:id/payment-status", orderHandler.GetOrderPaymentStatus)
@@ -241,6 +253,7 @@ func main() {
 	r.POST("/api/orders/:id/confirm", orderHandler.ConfirmOrder)
 	r.POST("/api/orders/:id/cancel", orderHandler.CancelOrder)
 
+	// 管理员路由
 	r.POST("/api/admin/verify", adminHandler.VerifyAdminToken)
 	r.GET("/api/admin/products", adminHandler.ListAllProducts)
 	r.POST("/api/admin/products", adminHandler.CreateProduct)
@@ -254,6 +267,7 @@ func main() {
 	r.DELETE("/api/admin/orders/:id", adminHandler.DeleteOrder)
 	r.GET("/api/admin/system-status", statusHandler.GetSystemStatus)
 
+	// 收藏夹路由
 	r.GET("/api/wishlist", wishlistHandler.GetWishlist)
 	r.POST("/api/wishlist", wishlistHandler.AddToWishlist)
 	r.DELETE("/api/wishlist/:id", wishlistHandler.RemoveFromWishlist)