shumengya/mengyastore
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: sync local updates

Browse Source
This commit is contained in:
树萌芽
2026-05-16 19:03:36 +08:00
parent 37983f3b60
commit f1417891ac
101 changed files with 4626 additions and 307 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
mengyastore-backend-go/internal/handlers/admin_chat.go
View File

@@ -8,7 +8,8 @@ import (
)
// GetAllConversations 返回所有用户会话列表。
// @Summary 全部会话列表
// @Summary 管理端：列出全部聊天会话
// @Description 返回每个有过消息的用户账号等信息，供客服选择会话；需管理令牌 `X-Admin-Token`。
// @Tags 管理端-聊天
// @Produce json
// @Security AdminToken
@@ -29,11 +30,12 @@ func (h *AdminHandler) GetAllConversations(c *gin.Context) {
}
// GetConversation 返回指定账号的全部消息记录。
// @Summary 指定用户聊天记录
// @Summary 管理端：查看某用户的完整聊天记录
// @Description 路径参数 `account` 为用户账号标识；返回按时间排列的消息数组；需管理令牌。
// @Tags 管理端-聊天
// @Produce json
// @Security AdminToken
// @Param account path string true "用户账号"
// @Param account path string true "用户账号（路径）"
// @Success 200 {object} SwaggerMessagesWrap
// @Failure 400 {object} SwaggerErrorBody
// @Failure 401 {object} SwaggerErrorBody
@@ -61,13 +63,14 @@ type AdminChatPayload struct {
}
// AdminReply 向指定用户发送管理员回复。
// @Summary 管理员回复
// @Summary 管理端：向用户回复一条消息
// @Description 路径为对方账号，JSON body 含 `content`；写入后用户侧拉取可见。
// @Tags 管理端-聊天
// @Accept json
// @Produce json
// @Security AdminToken
// @Param account path string true "用户账号"
// @Param body body AdminChatPayload true "回复内容"
// @Param account path string true "用户账号（路径）"
// @Param body body AdminChatPayload true "回复正文 JSON"
// @Success 200 {object} SwaggerOneChatMsgWrap
// @Failure 400 {object} SwaggerErrorBody
// @Failure 401 {object} SwaggerErrorBody
@@ -101,11 +104,12 @@ func (h *AdminHandler) AdminReply(c *gin.Context) {
}
// ClearConversation 清除与指定用户的全部消息记录。
// @Summary 清空会话
// @Summary 管理端：清空与某用户的会话
// @Description 删除该账号在系统中的全部聊天消息记录；不可恢复请谨慎使用。
// @Tags 管理端-聊天
// @Produce json
// @Security AdminToken
// @Param account path string true "用户账号"
// @Param account path string true "用户账号（路径）"
// @Success 200 {object} SwaggerBoolOKWrap
// @Failure 400 {object} SwaggerErrorBody
// @Failure 401 {object} SwaggerErrorBody

8
mengyastore-backend-go/internal/handlers/admin_orders.go
View File

@@ -7,7 +7,8 @@ import (
)
// ListAllOrders 管理端全部订单。
// @Summary 全部订单（管理）
// @Summary 管理端获取全部订单
// @Description 返回数据库中订单全量列表（含敏感字段），供后台管理；需 `X-Admin-Token`。
// @Tags 管理端-订单
// @Produce json
// @Security AdminToken
@@ -28,11 +29,12 @@ func (h *AdminHandler) ListAllOrders(c *gin.Context) {
}
// DeleteOrder 管理端删除订单。
// @Summary 删除订单
// @Summary 管理端删除指定订单
// @Description 按路径中的订单 ID 删除记录；不可恢复请谨慎操作。
// @Tags 管理端-订单
// @Produce json
// @Security AdminToken
// @Param id path string true "订单 ID"
// @Param id path string true "订单ID"
// @Success 200 {object} SwaggerBoolOKWrap
// @Failure 400 {object} SwaggerErrorBody
// @Failure 401 {object} SwaggerErrorBody

33
mengyastore-backend-go/internal/handlers/admin_product.go
View File

@@ -47,12 +47,12 @@ type AdminVerifyTokenRequest struct {
}
// VerifyAdminToken 校验请求中的令牌是否正确。
// @Summary 校验管理员令牌
// @Description 响应为 {"valid": true/false}，不泄露真实口令。
// @Summary 校验管理端令牌是否有效
// @Description 请求体 JSON 含 `token` 字段；响应仅返回 `{"valid": true|false}`，不会返回真实口令或敏感信息。
// @Tags 管理端-认证
// @Accept json
// @Produce json
// @Param body body AdminVerifyTokenRequest true "待校验 token"
// @Param body body AdminVerifyTokenRequest true "待校验的管理员 token（JSON）"
// @Success 200 {object} SwaggerValidBody
// @Router /api/admin/verify [post]
func (h *AdminHandler) VerifyAdminToken(c *gin.Context) {
@@ -65,7 +65,8 @@ func (h *AdminHandler) VerifyAdminToken(c *gin.Context) {
}
// ListAllProducts 管理端商品全量列表（含下架与卡密等敏感字段）。
// @Summary 全部商品（管理）
// @Summary 管理端获取全部商品列表
// @Description 含下架商品、卡密字段等完整数据，仅限管理令牌访问。需在请求头携带 `X-Admin-Token`。
// @Tags 管理端-商品
// @Produce json
// @Security AdminToken
@@ -86,12 +87,13 @@ func (h *AdminHandler) ListAllProducts(c *gin.Context) {
}
// CreateProduct 创建商品。
// @Summary 创建商品
// @Summary 管理端创建商品
// @Description 提交完整商品载荷：价格、卡密/固定内容、收款码链接、是否上架等。校验失败返回 400。
// @Tags 管理端-商品
// @Accept json
// @Produce json
// @Security AdminToken
// @Param body body ProductPayload true "商品字段"
// @Param body body ProductPayload true "商品各字段（含可选卡密、截图、收款码等）"
// @Success 200 {object} SwaggerProductOneBody
// @Failure 400 {object} SwaggerErrorBody
// @Failure 401 {object} SwaggerErrorBody
@@ -157,13 +159,14 @@ func (h *AdminHandler) CreateProduct(c *gin.Context) {
}
// UpdateProduct 更新商品。
// @Summary 更新商品
// @Summary 管理端更新商品
// @Description 路径参数为商品 ID，请求体为整包覆盖式更新（以服务端绑定逻辑为准）。未找到则 404。
// @Tags 管理端-商品
// @Accept json
// @Produce json
// @Security AdminToken
// @Param id path string true "商品 ID"
// @Param body body ProductPayload true "商品字段"
// @Param id path string true "商品ID"
// @Param body body ProductPayload true "待写入的商品字段"
// @Success 200 {object} SwaggerProductOneBody
// @Failure 400 {object} SwaggerErrorBody
// @Failure 401 {object} SwaggerErrorBody
@@ -231,13 +234,14 @@ func (h *AdminHandler) UpdateProduct(c *gin.Context) {
}
// ToggleProduct 上架/下架切换。
// @Summary 切换上架状态
// @Summary 管理端切换商品上架状态
// @Description PATCH 请求体为 `{ "active": true|false }`，用于快速上下架而不改其它字段。
// @Tags 管理端-商品
// @Accept json
// @Produce json
// @Security AdminToken
// @Param id path string true "商品 ID"
// @Param body body TogglePayload true "{active}"
// @Param id path string true "商品ID"
// @Param body body TogglePayload true "上架开关 { \"active\": bool }"
// @Success 200 {object} SwaggerProductOneBody
// @Failure 400 {object} SwaggerErrorBody
// @Failure 401 {object} SwaggerErrorBody
@@ -262,11 +266,12 @@ func (h *AdminHandler) ToggleProduct(c *gin.Context) {
}
// DeleteProduct 删除商品。
// @Summary 删除商品
// @Summary 管理端删除商品
// @Description 按 ID 永久删除商品记录（影响以数据库外键/业务逻辑为准），需管理令牌。
// @Tags 管理端-商品
// @Produce json
// @Security AdminToken
// @Param id path string true "商品 ID"
// @Param id path string true "商品ID"
// @Success 200 {object} SwaggerBoolOKWrap
// @Failure 401 {object} SwaggerErrorBody
// @Failure 500 {object} SwaggerErrorBody

13
mengyastore-backend-go/internal/handlers/admin_site.go
View File

@@ -14,12 +14,13 @@ type MaintenancePayload struct {
}
// SetMaintenance 设置站点维护模式。
// @Summary 设置维护模式
// @Summary 设置全站维护模式
// @Description 打开维护后前台可展示原因文案；需管理令牌。请求体含 `maintenance` 布尔与可选 `reason`。
// @Tags 管理端-站点
// @Accept json
// @Produce json
// @Security AdminToken
// @Param body body MaintenancePayload true "维护开关与原因"
// @Param body body MaintenancePayload true "maintenance 与 reason"
// @Success 200 {object} SwaggerMaintenanceWrap
// @Failure 400 {object} SwaggerErrorBody
// @Failure 401 {object} SwaggerErrorBody
@@ -47,7 +48,8 @@ func (h *AdminHandler) SetMaintenance(c *gin.Context) {
}
// GetSMTPConfig 获取 SMTP 配置（密码脱敏）。
// @Summary 获取 SMTP 配置
// @Summary 获取发信 SMTP 配置（脱敏）
// @Description 返回当前站点发件配置；密码字段以占位符脱敏显示，不会返回明文。
// @Tags 管理端-站点
// @Produce json
// @Security AdminToken
@@ -73,12 +75,13 @@ func (h *AdminHandler) GetSMTPConfig(c *gin.Context) {
}
// SetSMTPConfig 保存 SMTP 配置。
// @Summary 保存 SMTP 配置
// @Summary 保存发信 SMTP 配置
// @Description 写入 SMTP 主机、端口、账号等；若密码仍为脱敏占位符则保留库中已有密码（实现细节见服务逻辑）。
// @Tags 管理端-站点
// @Accept json
// @Produce json
// @Security AdminToken
// @Param body body storage.SMTPConfig true "SMTP 字段"
// @Param body body storage.SMTPConfig true "SMTP 连接与发件人信息"
// @Success 200 {object} SwaggerStringOKBody
// @Failure 400 {object} SwaggerErrorBody
// @Failure 401 {object} SwaggerErrorBody

3
mengyastore-backend-go/internal/handlers/admin_status.go
View File

@@ -30,7 +30,8 @@ func NewSystemStatusHandler(cfg *config.Config, db *gormDB.DB, mqClient *mq.Clie
}
// GetSystemStatus 返回管理后台用 JSON，需通过管理员令牌。
// @Summary 系统运行状态
// @Summary 管理端系统运行状态与依赖探活
// @Description 聚合展示配置摘要、数据库/MySQL、RabbitMQ、Redis 等探测结果与进程启动时间，便于运维排查；需管理令牌。
// @Tags 管理端-系统
// @Produce json
// @Security AdminToken

8
mengyastore-backend-go/internal/handlers/chat.go
View File

@@ -35,7 +35,8 @@ func (h *ChatHandler) requireChatUser(c *gin.Context) (account, name string, ok
}
// GetMyMessages 返回当前登录用户的全部聊天消息。
// @Summary 我的聊天消息
// @Summary 拉取当前用户聊天记录
// @Description 需在请求头携带有效的 `Authorization: Bearer <token>`。返回该登录用户在客服系统中与管理员往来的全部消息列表。
// @Tags 聊天（用户）
// @Produce json
// @Security BearerAuth
@@ -62,12 +63,13 @@ type ChatMessagePayload struct {
}
// SendMyMessage 向管理员发送一条用户消息。
// @Summary 发送用户消息
// @Summary 用户发送聊天消息
// @Description 需在请求头携带 Bearer。正文为 JSON `content` 字段；可能因频率限制返回 429。
// @Tags 聊天（用户）
// @Accept json
// @Produce json
// @Security BearerAuth
// @Param body body ChatMessagePayload true "消息正文"
// @Param body body ChatMessagePayload true "消息正文（JSON）"
// @Success 200 {object} SwaggerOneChatMsgWrap
// @Failure 400 {object} SwaggerErrorBody
// @Failure 401 {object} SwaggerErrorBody

39
mengyastore-backend-go/internal/handlers/order.go
View File

@@ -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

8
mengyastore-backend-go/internal/handlers/public.go
View File

@@ -19,7 +19,8 @@ func NewPublicHandler(store *storage.ProductStore) *PublicHandler {
}
// ListProducts 上架商品列表（公开字段，不含卡密与管理信息）。
// @Summary 上架商品列表
// @Summary 获取上架商品列表
// @Description 返回当前处于「上架」状态的商品集合，仅包含前台展示所需字段（不含卡密、管理字段等）。无需登录。
// @Tags 公开
// @Produce json
// @Success 200 {object} SwaggerProductListBody
@@ -35,10 +36,11 @@ func (h *PublicHandler) ListProducts(c *gin.Context) {
}
// RecordProductView 记录商品浏览（去重策略由服务端指纹决定）。
// @Summary 记录商品浏览
// @Summary 记录商品浏览次数
// @Description 对指定商品增加浏览计数；是否计入由服务端对访客指纹去重策略决定，用于热门统计。路径参数为商品 ID。
// @Tags 公开
// @Produce json
// @Param id path string true "商品 ID"
// @Param id path string true "商品ID（路径）"
// @Success 200 {object} SwaggerProductViewWrap
// @Failure 404 {object} SwaggerErrorBody
// @Router /api/products/{id}/view [post]

9
mengyastore-backend-go/internal/handlers/stats.go
View File

@@ -18,7 +18,8 @@ func NewStatsHandler(orderStore *storage.OrderStore, siteStore *storage.SiteStor
}
// GetStats 订单总数与站点访问总数。
// @Summary 站点统计
// @Summary 获取站点聚合统计
// @Description 返回全站累计订单数与累计访问量（公开读，用于首页展示等）。
// @Tags 公开
// @Produce json
// @Success 200 {object} SwaggerStatsWrap
@@ -44,7 +45,8 @@ func (h *StatsHandler) GetStats(c *gin.Context) {
}
// RecordVisit 记录一次站点访问并返回累计访问量。
// @Summary 记录站点访问
// @Summary 上报一次站点访问
// @Description 记录访客一次访问并累加全站访问计数；是否计入由服务端指纹等策略决定，响应中含最新总访问量与本次是否计入。
// @Tags 公开
// @Produce json
// @Success 200 {object} SwaggerVisitWrap
@@ -66,7 +68,8 @@ func (h *StatsHandler) RecordVisit(c *gin.Context) {
}
// GetMaintenance 当前维护模式与原因。
// @Summary 维护模式状态
// @Summary 获取维护模式状态
// @Description 返回当前是否开启全站维护、以及展示给前端的维护原因文案（公开接口，无需管理令牌）。
// @Tags 公开
// @Produce json
// @Success 200 {object} SwaggerMaintenanceWrap

13
mengyastore-backend-go/internal/handlers/wishlist.go
View File

@@ -35,7 +35,8 @@ func (h *WishlistHandler) requireUser(c *gin.Context) (string, bool) {
}
// GetWishlist 当前用户收藏的商品 ID 列表。
// @Summary 收藏列表
// @Summary 获取当前用户收藏列表
// @Description 需 Bearer 登录。返回该账号已收藏的商品 ID 数组（顺序由存储实现决定）。
// @Tags 收藏
// @Produce json
// @Security BearerAuth
@@ -62,12 +63,13 @@ type WishlistItemPayload struct {
}
// AddToWishlist 添加收藏。
// @Summary 添加收藏
// @Summary 添加商品到收藏
// @Description 需 Bearer。请求体为 `{ "productId": "..." }`；幂等语义由存储层实现（重复添加可忽略或报错以实际为准）。
// @Tags 收藏
// @Accept json
// @Produce json
// @Security BearerAuth
// @Param body body WishlistItemPayload true "商品 ID"
// @Param body body WishlistItemPayload true "包含 productId 的 JSON"
// @Success 200 {object} SwaggerWishlistWrap
// @Failure 400 {object} SwaggerErrorBody
// @Failure 401 {object} SwaggerErrorBody
@@ -92,11 +94,12 @@ func (h *WishlistHandler) AddToWishlist(c *gin.Context) {
}
// RemoveFromWishlist 按商品 ID 移除收藏。
// @Summary 移除收藏
// @Summary 从收藏中移除商品
// @Description 需 Bearer。路径参数为要移除的商品 ID。
// @Tags 收藏
// @Produce json
// @Security BearerAuth
// @Param id path string true "商品 ID"
// @Param id path string true "商品ID（路径）"
// @Success 200 {object} SwaggerWishlistWrap
// @Failure 400 {object} SwaggerErrorBody
// @Failure 401 {object} SwaggerErrorBody