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

2
mengyastore-backend-go/.dockerignore
View File

@@ -1,9 +1,9 @@
.git
.gitignore
node_modules
dist
debug-logs
*.exe
*.exe~
# 勿忽略 dist/：Dockerfile 需 COPY dist/mengyastore-backend-linux-amd64（先在 Windows 运行 dist\build-linux-amd64.bat）
Dockerfile
docker-compose.yml

3
mengyastore-backend-go/.gitignore vendored
View File

@@ -4,3 +4,6 @@
.env.local
.env.production
*.exe
# Windows 本地交叉编译产物（部署前生成，勿提交）
dist/mengyastore-backend-linux-amd64

16
mengyastore-backend-go/Dockerfile
View File

@@ -1,20 +1,14 @@
FROM golang:1.24-alpine AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o /out/mengyastore-backend .
# 运行镜像仅包含 Alpine + 预编译二进制。
# 请在 Windows 上先执行 dist\build-linux-amd64.bat，生成 dist/mengyastore-backend-linux-amd64，
# 再将本目录同步到服务器并在服务器执行 docker build（无需在服务器安装 Go）。
FROM alpine:3.20
RUN apk add --no-cache ca-certificates tzdata
WORKDIR /app
COPY --from=builder /out/mengyastore-backend ./mengyastore-backend
COPY dist/mengyastore-backend-linux-amd64 ./mengyastore-backend
RUN chmod +x ./mengyastore-backend
EXPOSE 8080

2
mengyastore-backend-go/Makefile
View File

@@ -1,3 +1,3 @@
.PHONY: swagger
swagger:
swag init -g main.go -o docs --parseDependency --parseInternal
go run github.com/swaggo/swag/cmd/swag@v1.8.12 init -g main.go -o docs --parseDependency --parseInternal

22
mengyastore-backend-go/docker-compose.yml
View File

@@ -1,3 +1,15 @@
# 构建镜像前在 Windows 执行: dist\build-linux-amd64.bat
# 再放入 dist/mengyastore-backend-linux-amd64 后构建（服务器仅需 Docker，无需 Go）
#
# 与本地 dev.bat 使用同一套库：
# - Compose 会自动读取本目录下的 .env（若存在），用于 ${VAR} 替换并传入容器。
# - 将本地 mengyastore-backend-go/.env.development 复制到服务器本目录，命名为 .env；
# 或至少设置与开发机相同的 DATABASE_DSN。
# - 默认 APP_ENV=development：与 go run 且未设 APP_ENV 时一致（空 DSN → 代码内 TestDSN）。
# 正式上生产请在 .env 中写 APP_ENV=production。
#
# 前端「样式和本地 npm run dev 不一样」：部署一般是 npm run build 的产出，经 Nginx 缓存；
# 换文案/样式后需重新构建前端并强刷或清理 Service Worker（PWA）。
services:
backend:
build:
@@ -6,11 +18,9 @@ services:
ports:
- "28081:8080"
environment:
# 生产环境（本地开发请使用 APP_ENV=development + 根目录 .env.development，或 ENV_FILE）
APP_ENV: production
GIN_MODE: release
APP_ENV: ${APP_ENV:-development}
GIN_MODE: ${GIN_MODE:-release}
TZ: Asia/Shanghai
# 通过宿主机 .env 或 export 注入，勿在仓库中写真实 DSN/口令
DATABASE_DSN: ${DATABASE_DSN:-}
ADMIN_TOKEN: ${ADMIN_TOKEN:-changeme}
AUTH_API_URL: ${AUTH_API_URL:-}
@@ -19,6 +29,6 @@ services:
REDIS_PASSWORD: ${REDIS_PASSWORD:-}
REDIS_DB: ${REDIS_DB:-1}
RABBITMQ_ENABLED: "false"
RABBITMQ_ENV: prod
RABBITMQ_URL: ${RABBITMQ_URL}
RABBITMQ_ENV: ${RABBITMQ_ENV:-dev}
RABBITMQ_URL: ${RABBITMQ_URL:-}
restart: unless-stopped

166
mengyastore-backend-go/docs/docs.go
View File

@@ -18,14 +18,14 @@ const docTemplate = `{
"paths": {
"/": {
"get": {
"description": "返回服务描述、主要路径指引与版本（非 OpenAPI 详尽列表，完整契约见 /swagger）。",
"description": "访问服务根路径 ` + "`" + `/` + "`" + ` 返回 JSON：服务简介、本地与生产环境说明、主要业务路由分组、运行版本与时间戳。完整请求/响应模型请使用 Swagger UI：` + "`" + `GET /swagger/index.html` + "`" + `。本地一般为 ` + "`" + `http://localhost:8080/` + "`" + `，生产域名为 ` + "`" + `https://store.shumengya.top/` + "`" + `。",
"produces": [
"application/json"
],
"tags": [
"元信息"
],
"summary": "API 根信息与端点索引",
"summary": "根路径 API 说明与路由索引",
"responses": {
"200": {
"description": "OK",
@@ -44,13 +44,14 @@ const docTemplate = `{
"AdminToken": []
}
],
"description": "返回每个有过消息的用户账号等信息，供客服选择会话；需管理令牌 ` + "`" + `X-Admin-Token` + "`" + `。",
"produces": [
"application/json"
],
"tags": [
"管理端-聊天"
],
"summary": "全部会话列表",
"summary": "管理端：列出全部聊天会话",
"responses": {
"200": {
"description": "OK",
@@ -81,17 +82,18 @@ const docTemplate = `{
"AdminToken": []
}
],
"description": "路径参数 ` + "`" + `account` + "`" + ` 为用户账号标识；返回按时间排列的消息数组；需管理令牌。",
"produces": [
"application/json"
],
"tags": [
"管理端-聊天"
],
"summary": "指定用户聊天记录",
"summary": "管理端：查看某用户的完整聊天记录",
"parameters": [
{
"type": "string",
"description": "用户账号",
"description": "用户账号（路径）",
"name": "account",
"in": "path",
"required": true
@@ -130,6 +132,7 @@ const docTemplate = `{
"AdminToken": []
}
],
"description": "路径为对方账号，JSON body 含 ` + "`" + `content` + "`" + `；写入后用户侧拉取可见。",
"consumes": [
"application/json"
],
@@ -139,17 +142,17 @@ const docTemplate = `{
"tags": [
"管理端-聊天"
],
"summary": "管理员回复",
"summary": "管理端：向用户回复一条消息",
"parameters": [
{
"type": "string",
"description": "用户账号",
"description": "用户账号（路径）",
"name": "account",
"in": "path",
"required": true
},
{
"description": "回复内容",
"description": "回复正文 JSON",
"name": "body",
"in": "body",
"required": true,
@@ -191,17 +194,18 @@ const docTemplate = `{
"AdminToken": []
}
],
"description": "删除该账号在系统中的全部聊天消息记录；不可恢复请谨慎使用。",
"produces": [
"application/json"
],
"tags": [
"管理端-聊天"
],
"summary": "清空会话",
"summary": "管理端：清空与某用户的会话",
"parameters": [
{
"type": "string",
"description": "用户账号",
"description": "用户账号（路径）",
"name": "account",
"in": "path",
"required": true
@@ -242,13 +246,14 @@ const docTemplate = `{
"AdminToken": []
}
],
"description": "返回数据库中订单全量列表（含敏感字段），供后台管理；需 ` + "`" + `X-Admin-Token` + "`" + `。",
"produces": [
"application/json"
],
"tags": [
"管理端-订单"
],
"summary": "全部订单（管理）",
"summary": "管理端获取全部订单",
"responses": {
"200": {
"description": "OK",
@@ -278,17 +283,18 @@ const docTemplate = `{
"AdminToken": []
}
],
"description": "按路径中的订单 ID 删除记录；不可恢复请谨慎操作。",
"produces": [
"application/json"
],
"tags": [
"管理端-订单"
],
"summary": "删除订单",
"summary": "管理端删除指定订单",
"parameters": [
{
"type": "string",
"description": "订单 ID",
"description": "订单ID",
"name": "id",
"in": "path",
"required": true
@@ -329,13 +335,14 @@ const docTemplate = `{
"AdminToken": []
}
],
"description": "含下架商品、卡密字段等完整数据，仅限管理令牌访问。需在请求头携带 ` + "`" + `X-Admin-Token` + "`" + `。",
"produces": [
"application/json"
],
"tags": [
"管理端-商品"
],
"summary": "全部商品（管理）",
"summary": "管理端获取全部商品列表",
"responses": {
"200": {
"description": "OK",
@@ -363,6 +370,7 @@ const docTemplate = `{
"AdminToken": []
}
],
"description": "提交完整商品载荷：价格、卡密/固定内容、收款码链接、是否上架等。校验失败返回 400。",
"consumes": [
"application/json"
],
@@ -372,10 +380,10 @@ const docTemplate = `{
"tags": [
"管理端-商品"
],
"summary": "创建商品",
"summary": "管理端创建商品",
"parameters": [
{
"description": "商品字段",
"description": "商品各字段（含可选卡密、截图、收款码等）",
"name": "body",
"in": "body",
"required": true,
@@ -419,6 +427,7 @@ const docTemplate = `{
"AdminToken": []
}
],
"description": "路径参数为商品 ID，请求体为整包覆盖式更新（以服务端绑定逻辑为准）。未找到则 404。",
"consumes": [
"application/json"
],
@@ -428,17 +437,17 @@ const docTemplate = `{
"tags": [
"管理端-商品"
],
"summary": "更新商品",
"summary": "管理端更新商品",
"parameters": [
{
"type": "string",
"description": "商品 ID",
"description": "商品ID",
"name": "id",
"in": "path",
"required": true
},
{
"description": "商品字段",
"description": "待写入的商品字段",
"name": "body",
"in": "body",
"required": true,
@@ -486,17 +495,18 @@ const docTemplate = `{
"AdminToken": []
}
],
"description": "按 ID 永久删除商品记录（影响以数据库外键/业务逻辑为准），需管理令牌。",
"produces": [
"application/json"
],
"tags": [
"管理端-商品"
],
"summary": "删除商品",
"summary": "管理端删除商品",
"parameters": [
{
"type": "string",
"description": "商品 ID",
"description": "商品ID",
"name": "id",
"in": "path",
"required": true
@@ -531,6 +541,7 @@ const docTemplate = `{
"AdminToken": []
}
],
"description": "PATCH 请求体为 ` + "`" + `{ \"active\": true|false }` + "`" + `，用于快速上下架而不改其它字段。",
"consumes": [
"application/json"
],
@@ -540,17 +551,17 @@ const docTemplate = `{
"tags": [
"管理端-商品"
],
"summary": "切换上架状态",
"summary": "管理端切换商品上架状态",
"parameters": [
{
"type": "string",
"description": "商品 ID",
"description": "商品ID",
"name": "id",
"in": "path",
"required": true
},
{
"description": "{active}",
"description": "上架开关 { \\",
"name": "body",
"in": "body",
"required": true,
@@ -594,6 +605,7 @@ const docTemplate = `{
"AdminToken": []
}
],
"description": "打开维护后前台可展示原因文案；需管理令牌。请求体含 ` + "`" + `maintenance` + "`" + ` 布尔与可选 ` + "`" + `reason` + "`" + `。",
"consumes": [
"application/json"
],
@@ -603,10 +615,10 @@ const docTemplate = `{
"tags": [
"管理端-站点"
],
"summary": "设置维护模式",
"summary": "设置全站维护模式",
"parameters": [
{
"description": "维护开关与原因",
"description": "maintenance 与 reason",
"name": "body",
"in": "body",
"required": true,
@@ -650,13 +662,14 @@ const docTemplate = `{
"AdminToken": []
}
],
"description": "返回当前站点发件配置；密码字段以占位符脱敏显示，不会返回明文。",
"produces": [
"application/json"
],
"tags": [
"管理端-站点"
],
"summary": "获取 SMTP 配置",
"summary": "获取发信 SMTP 配置（脱敏）",
"responses": {
"200": {
"description": "OK",
@@ -684,6 +697,7 @@ const docTemplate = `{
"AdminToken": []
}
],
"description": "写入 SMTP 主机、端口、账号等；若密码仍为脱敏占位符则保留库中已有密码（实现细节见服务逻辑）。",
"consumes": [
"application/json"
],
@@ -693,10 +707,10 @@ const docTemplate = `{
"tags": [
"管理端-站点"
],
"summary": "保存 SMTP 配置",
"summary": "保存发信 SMTP 配置",
"parameters": [
{
"description": "SMTP 字段",
"description": "SMTP 连接与发件人信息",
"name": "body",
"in": "body",
"required": true,
@@ -740,13 +754,14 @@ const docTemplate = `{
"AdminToken": []
}
],
"description": "聚合展示配置摘要、数据库/MySQL、RabbitMQ、Redis 等探测结果与进程启动时间，便于运维排查；需管理令牌。",
"produces": [
"application/json"
],
"tags": [
"管理端-系统"
],
"summary": "系统运行状态",
"summary": "管理端系统运行状态与依赖探活",
"responses": {
"200": {
"description": "OK",
@@ -766,7 +781,7 @@ const docTemplate = `{
},
"/api/admin/verify": {
"post": {
"description": "响应为 {\"valid\": true/false}，不泄露真实口令。",
"description": "请求体 JSON 含 ` + "`" + `token` + "`" + ` 字段；响应仅返回 ` + "`" + `{\"valid\": true|false}` + "`" + `，不会返回真实口令或敏感信息。",
"consumes": [
"application/json"
],
@@ -776,10 +791,10 @@ const docTemplate = `{
"tags": [
"管理端-认证"
],
"summary": "校验管理员令牌",
"summary": "校验管理端令牌是否有效",
"parameters": [
{
"description": "待校验 token",
"description": "待校验的管理员 token（JSON）",
"name": "body",
"in": "body",
"required": true,
@@ -805,13 +820,14 @@ const docTemplate = `{
"BearerAuth": []
}
],
"description": "需在请求头携带有效的 ` + "`" + `Authorization: Bearer \u003ctoken\u003e` + "`" + `。返回该登录用户在客服系统中与管理员往来的全部消息列表。",
"produces": [
"application/json"
],
"tags": [
"聊天（用户）"
],
"summary": "我的聊天消息",
"summary": "拉取当前用户聊天记录",
"responses": {
"200": {
"description": "OK",
@@ -839,6 +855,7 @@ const docTemplate = `{
"BearerAuth": []
}
],
"description": "需在请求头携带 Bearer。正文为 JSON ` + "`" + `content` + "`" + ` 字段；可能因频率限制返回 429。",
"consumes": [
"application/json"
],
@@ -848,10 +865,10 @@ const docTemplate = `{
"tags": [
"聊天（用户）"
],
"summary": "发送用户消息",
"summary": "用户发送聊天消息",
"parameters": [
{
"description": "消息正文",
"description": "消息正文（JSON）",
"name": "body",
"in": "body",
"required": true,
@@ -896,6 +913,7 @@ const docTemplate = `{
},
"/api/checkout": {
"post": {
"description": "根据商品配置决定是否需要登录（` + "`" + `requireLogin` + "`" + `）。可附带 ` + "`" + `Authorization: Bearer` + "`" + ` 以关联账号、限购与通知邮箱。付费订单走萌芽支付时需商品已配置收款码；同一商品在他人待支付锁定期内可能返回 409；同一账号存在待支付单时也可能冲突。成功返回订单概要及二维码链接等。",
"consumes": [
"application/json"
],
@@ -905,16 +923,16 @@ const docTemplate = `{
"tags": [
"订单"
],
"summary": "结账创建订单",
"summary": "结账并创建订单",
"parameters": [
{
"type": "string",
"description": "Bearer 用户 token（部分商品必填）",
"description": "可选；格式 Bearer + 空格 + token，部分商品必填",
"name": "Authorization",
"in": "header"
},
{
"description": "结账参数",
"description": "结账请求体：商品、数量、联系方式等",
"name": "body",
"in": "body",
"required": true,
@@ -949,7 +967,7 @@ const docTemplate = `{
}
},
"409": {
"description": "库存锁定冲突或同用户待支付",
"description": "库存锁定冲突（他人正在支付）或同账号待支付单未满间隔",
"schema": {
"$ref": "#/definitions/handlers.SwaggerErrorBody"
}
@@ -965,6 +983,7 @@ const docTemplate = `{
},
"/api/health": {
"get": {
"description": "用于负载均衡或编排探活：` + "`" + `status` + "`" + ` 恒为 ok 表示 HTTP 服务存活；` + "`" + `rabbitmq` + "`" + ` 为 ` + "`" + `disabled` + "`" + `（未启用消息队列客户端）、` + "`" + `ok` + "`" + `（连接可用）或以 ` + "`" + `error:` + "`" + ` 开头的错误片段。",
"produces": [
"application/json"
],
@@ -974,7 +993,7 @@ const docTemplate = `{
"summary": "健康检查",
"responses": {
"200": {
"description": "status ok；rabbitmq 为 disabled|ok|error:...",
"description": "status 为 ok；rabbitmq 为 disabled、ok 或 error: 前缀错误信息",
"schema": {
"type": "object",
"additionalProperties": true
@@ -990,13 +1009,14 @@ const docTemplate = `{
"BearerAuth": []
}
],
"description": "必须携带有效 Bearer。列表中处于待支付状态的订单不会包含已分配卡密等敏感字段，防止泄露。",
"produces": [
"application/json"
],
"tags": [
"订单"
],
"summary": "我的订单",
"summary": "查询当前登录用户的订单列表",
"responses": {
"200": {
"description": "OK",
@@ -1021,17 +1041,18 @@ const docTemplate = `{
},
"/api/orders/{id}/cancel": {
"post": {
"description": "仅对允许取消的状态生效（如待支付）；已完成订单会冲突。成功时释放预留库存/卡密占用。请勿在公网暴露此能力时省略鉴权策略（实现以代码为准）。",
"produces": [
"application/json"
],
"tags": [
"订单"
],
"summary": "取消订单",
"summary": "取消待支付订单",
"parameters": [
{
"type": "string",
"description": "订单 ID",
"description": "订单ID",
"name": "id",
"in": "path",
"required": true
@@ -1067,17 +1088,18 @@ const docTemplate = `{
},
"/api/orders/{id}/confirm": {
"post": {
"description": "用于用户侧「确认」动作：已完成订单直接返回数据；待支付时若仍未到账则 409；已取消或超时 410。手动发货等场景下会触发邮件通知（若配置）。",
"produces": [
"application/json"
],
"tags": [
"订单"
],
"summary": "确认订单",
"summary": "确认订单（核销/完成流程）",
"parameters": [
{
"type": "string",
"description": "订单 ID",
"description": "订单ID",
"name": "id",
"in": "path",
"required": true
@@ -1097,13 +1119,13 @@ const docTemplate = `{
}
},
"409": {
"description": "待支付未到账等",
"description": "待支付但金额未核对到账等",
"schema": {
"$ref": "#/definitions/handlers.SwaggerErrorBody"
}
},
"410": {
"description": "已取消或超时",
"description": "订单已取消或已超过待支付时限",
"schema": {
"$ref": "#/definitions/handlers.SwaggerErrorBody"
}
@@ -1113,17 +1135,18 @@ const docTemplate = `{
},
"/api/orders/{id}/payment-status": {
"get": {
"description": "供前端轮询待支付订单：返回状态、应付快照、过期时间等；不包含卡密等敏感发货内容。路径参数为订单 ID。",
"produces": [
"application/json"
],
"tags": [
"订单"
],
"summary": "订单支付状态",
"summary": "查询订单支付状态（轮询）",
"parameters": [
{
"type": "string",
"description": "订单 ID",
"description": "订单ID",
"name": "id",
"in": "path",
"required": true
@@ -1147,13 +1170,14 @@ const docTemplate = `{
},
"/api/products": {
"get": {
"description": "返回当前处于「上架」状态的商品集合，仅包含前台展示所需字段（不含卡密、管理字段等）。无需登录。",
"produces": [
"application/json"
],
"tags": [
"公开"
],
"summary": "上架商品列表",
"summary": "获取上架商品列表",
"responses": {
"200": {
"description": "OK",
@@ -1172,17 +1196,18 @@ const docTemplate = `{
},
"/api/products/{id}/view": {
"post": {
"description": "对指定商品增加浏览计数；是否计入由服务端对访客指纹去重策略决定，用于热门统计。路径参数为商品 ID。",
"produces": [
"application/json"
],
"tags": [
"公开"
],
"summary": "记录商品浏览",
"summary": "记录商品浏览次数",
"parameters": [
{
"type": "string",
"description": "商品 ID",
"description": "商品ID（路径）",
"name": "id",
"in": "path",
"required": true
@@ -1206,13 +1231,14 @@ const docTemplate = `{
},
"/api/site/maintenance": {
"get": {
"description": "返回当前是否开启全站维护、以及展示给前端的维护原因文案（公开接口，无需管理令牌）。",
"produces": [
"application/json"
],
"tags": [
"公开"
],
"summary": "维护模式状态",
"summary": "获取维护模式状态",
"responses": {
"200": {
"description": "OK",
@@ -1231,13 +1257,14 @@ const docTemplate = `{
},
"/api/site/visit": {
"post": {
"description": "记录访客一次访问并累加全站访问计数；是否计入由服务端指纹等策略决定，响应中含最新总访问量与本次是否计入。",
"produces": [
"application/json"
],
"tags": [
"公开"
],
"summary": "记录站点访问",
"summary": "上报一次站点访问",
"responses": {
"200": {
"description": "OK",
@@ -1256,13 +1283,14 @@ const docTemplate = `{
},
"/api/stats": {
"get": {
"description": "返回全站累计订单数与累计访问量（公开读，用于首页展示等）。",
"produces": [
"application/json"
],
"tags": [
"公开"
],
"summary": "站点统计",
"summary": "获取站点聚合统计",
"responses": {
"200": {
"description": "OK",
@@ -1281,6 +1309,7 @@ const docTemplate = `{
},
"/api/webhooks/mengya-pay": {
"post": {
"description": "由支付渠道/转发服务 POST 原始 JSON；服务端解析到账金额并尝试匹配待支付订单。若配置 ` + "`" + `WEBHOOK_MENGYA_SECRET` + "`" + `，请求头 ` + "`" + `X-Webhook-Secret` + "`" + ` 必须与其一致。本地联调与生产 ` + "`" + `https://store.shumengya.top` + "`" + ` 均使用同一路径，由部署时的域名与 TLS 决定回调 URL。",
"consumes": [
"application/json"
],
@@ -1290,11 +1319,11 @@ const docTemplate = `{
"tags": [
"Webhook"
],
"summary": "萌芽支付 Webhook",
"summary": "萌芽支付到账 Webhook",
"parameters": [
{
"type": "string",
"description": "与 WEBHOOK_MENGYA_SECRET 一致",
"description": "与进程环境变量 WEBHOOK_MENGYA_SECRET 一致；未配置密钥时可不填",
"name": "X-Webhook-Secret",
"in": "header"
}
@@ -1334,13 +1363,14 @@ const docTemplate = `{
"BearerAuth": []
}
],
"description": "需 Bearer 登录。返回该账号已收藏的商品 ID 数组（顺序由存储实现决定）。",
"produces": [
"application/json"
],
"tags": [
"收藏"
],
"summary": "收藏列表",
"summary": "获取当前用户收藏列表",
"responses": {
"200": {
"description": "OK",
@@ -1368,6 +1398,7 @@ const docTemplate = `{
"BearerAuth": []
}
],
"description": "需 Bearer。请求体为 ` + "`" + `{ \"productId\": \"...\" }` + "`" + `；幂等语义由存储层实现（重复添加可忽略或报错以实际为准）。",
"consumes": [
"application/json"
],
@@ -1377,10 +1408,10 @@ const docTemplate = `{
"tags": [
"收藏"
],
"summary": "添加收藏",
"summary": "添加商品到收藏",
"parameters": [
{
"description": "商品 ID",
"description": "包含 productId 的 JSON",
"name": "body",
"in": "body",
"required": true,
@@ -1424,17 +1455,18 @@ const docTemplate = `{
"BearerAuth": []
}
],
"description": "需 Bearer。路径参数为要移除的商品 ID。",
"produces": [
"application/json"
],
"tags": [
"收藏"
],
"summary": "移除收藏",
"summary": "从收藏中移除商品",
"parameters": [
{
"type": "string",
"description": "商品 ID",
"description": "商品ID（路径）",
"name": "id",
"in": "path",
"required": true
@@ -2156,19 +2188,19 @@ const docTemplate = `{
},
"securityDefinitions": {
"AdminToken": {
"description": "管理端令牌（也可使用 Authorization 头或 query token，见各接口说明）",
"description": "管理端访问令牌：与进程环境变量 ` + "`" + `ADMIN_TOKEN` + "`" + ` 一致。部分管理路由也可使用 ` + "`" + `Authorization` + "`" + ` 头或 Query ` + "`" + `token` + "`" + `（以具体路由实现为准）。",
"type": "apiKey",
"name": "X-Admin-Token",
"in": "header"
},
"BearerAuth": {
"description": "用户访问令牌，格式: Bearer 空格 + token",
"description": "用户访问令牌：请求头 ` + "`" + `Authorization` + "`" + `，值为 ` + "`" + `Bearer ` + "`" + ` 后接 SproutGate 返回的 JWT/access token（部分公开接口可不携带）。",
"type": "apiKey",
"name": "Authorization",
"in": "header"
},
"WebhookSecret": {
"description": "与服务端 WEBHOOK_MENGYA_SECRET 一致时校验萌芽支付 Webhook",
"description": "当服务端配置了 ` + "`" + `WEBHOOK_MENGYA_SECRET` + "`" + ` 时，萌芽支付到账回调 ` + "`" + `POST /api/webhooks/mengya-pay` + "`" + ` 需携带本头且值与密钥完全一致，否则返回 403。",
"type": "apiKey",
"name": "X-Webhook-Secret",
"in": "header"
@@ -2183,7 +2215,7 @@ var SwaggerInfo = &swag.Spec{
BasePath: "/",
Schemes: []string{"http", "https"},
Title: "萌芽小店 API",
Description: "商品、下单、站点统计、收藏与客服聊天；用户登录由萌芽账户认证中心（SproutGate）校验。监听地址以 HTTP_LISTEN_ADDR 为准。",
Description: "萌芽小店电商后端 HTTP API：商品、下单结账、订单与支付、站点统计与访问、维护模式、收藏、用户/管理员聊天、萌芽支付 Webhook，以及管理端商品/订单/站点与运维状态等。用户身份由萌芽账户认证中心（SproutGate）签发令牌并完成校验。\n\n**运行环境与基地址**\n- **本地开发**：监听地址由环境变量 `HTTP_LISTEN_ADDR` 决定，未设置时默认为 `:8080`，即常见入口 `http://localhost:8080`。可在浏览器打开 `http://localhost:8080/swagger/index.html` 查看本页同款文档并调试。\n- **生产部署**：线上前台/API 域名为 `https://store.shumengya.top`（HTTPS）。若前面还有网关、路径前缀或端口映射，请在拼接请求 URL 时以实际对外发布地址为准；Swagger 中默认 Host 为本地，联调线上时请将浏览器地址或客户端 Base URL 换成生产基地址。\n\n**说明**：本 OpenAPI 由代码注释生成；与进程真实监听、反向代理头无关，仅作契约参考。",
InfoInstanceName: "swagger",
SwaggerTemplate: docTemplate,
}

166
mengyastore-backend-go/docs/swagger.json
View File

@@ -5,7 +5,7 @@
],
"swagger": "2.0",
"info": {
"description": "商品、下单、站点统计、收藏与客服聊天；用户登录由萌芽账户认证中心（SproutGate）校验。监听地址以 HTTP_LISTEN_ADDR 为准。",
"description": "萌芽小店电商后端 HTTP API：商品、下单结账、订单与支付、站点统计与访问、维护模式、收藏、用户/管理员聊天、萌芽支付 Webhook，以及管理端商品/订单/站点与运维状态等。用户身份由萌芽账户认证中心（SproutGate）签发令牌并完成校验。\n\n**运行环境与基地址**\n- **本地开发**：监听地址由环境变量 `HTTP_LISTEN_ADDR` 决定，未设置时默认为 `:8080`，即常见入口 `http://localhost:8080`。可在浏览器打开 `http://localhost:8080/swagger/index.html` 查看本页同款文档并调试。\n- **生产部署**：线上前台/API 域名为 `https://store.shumengya.top`（HTTPS）。若前面还有网关、路径前缀或端口映射，请在拼接请求 URL 时以实际对外发布地址为准；Swagger 中默认 Host 为本地，联调线上时请将浏览器地址或客户端 Base URL 换成生产基地址。\n\n**说明**：本 OpenAPI 由代码注释生成；与进程真实监听、反向代理头无关，仅作契约参考。",
"title": "萌芽小店 API",
"contact": {},
"version": "1.0.0-go"
@@ -15,14 +15,14 @@
"paths": {
"/": {
"get": {
"description": "返回服务描述、主要路径指引与版本（非 OpenAPI 详尽列表，完整契约见 /swagger）。",
"description": "访问服务根路径 `/` 返回 JSON：服务简介、本地与生产环境说明、主要业务路由分组、运行版本与时间戳。完整请求/响应模型请使用 Swagger UI：`GET /swagger/index.html`。本地一般为 `http://localhost:8080/`，生产域名为 `https://store.shumengya.top/`。",
"produces": [
"application/json"
],
"tags": [
"元信息"
],
"summary": "API 根信息与端点索引",
"summary": "根路径 API 说明与路由索引",
"responses": {
"200": {
"description": "OK",
@@ -41,13 +41,14 @@
"AdminToken": []
}
],
"description": "返回每个有过消息的用户账号等信息，供客服选择会话；需管理令牌 `X-Admin-Token`。",
"produces": [
"application/json"
],
"tags": [
"管理端-聊天"
],
"summary": "全部会话列表",
"summary": "管理端：列出全部聊天会话",
"responses": {
"200": {
"description": "OK",
@@ -78,17 +79,18 @@
"AdminToken": []
}
],
"description": "路径参数 `account` 为用户账号标识；返回按时间排列的消息数组；需管理令牌。",
"produces": [
"application/json"
],
"tags": [
"管理端-聊天"
],
"summary": "指定用户聊天记录",
"summary": "管理端：查看某用户的完整聊天记录",
"parameters": [
{
"type": "string",
"description": "用户账号",
"description": "用户账号（路径）",
"name": "account",
"in": "path",
"required": true
@@ -127,6 +129,7 @@
"AdminToken": []
}
],
"description": "路径为对方账号，JSON body 含 `content`；写入后用户侧拉取可见。",
"consumes": [
"application/json"
],
@@ -136,17 +139,17 @@
"tags": [
"管理端-聊天"
],
"summary": "管理员回复",
"summary": "管理端：向用户回复一条消息",
"parameters": [
{
"type": "string",
"description": "用户账号",
"description": "用户账号（路径）",
"name": "account",
"in": "path",
"required": true
},
{
"description": "回复内容",
"description": "回复正文 JSON",
"name": "body",
"in": "body",
"required": true,
@@ -188,17 +191,18 @@
"AdminToken": []
}
],
"description": "删除该账号在系统中的全部聊天消息记录；不可恢复请谨慎使用。",
"produces": [
"application/json"
],
"tags": [
"管理端-聊天"
],
"summary": "清空会话",
"summary": "管理端：清空与某用户的会话",
"parameters": [
{
"type": "string",
"description": "用户账号",
"description": "用户账号（路径）",
"name": "account",
"in": "path",
"required": true
@@ -239,13 +243,14 @@
"AdminToken": []
}
],
"description": "返回数据库中订单全量列表（含敏感字段），供后台管理；需 `X-Admin-Token`。",
"produces": [
"application/json"
],
"tags": [
"管理端-订单"
],
"summary": "全部订单（管理）",
"summary": "管理端获取全部订单",
"responses": {
"200": {
"description": "OK",
@@ -275,17 +280,18 @@
"AdminToken": []
}
],
"description": "按路径中的订单 ID 删除记录；不可恢复请谨慎操作。",
"produces": [
"application/json"
],
"tags": [
"管理端-订单"
],
"summary": "删除订单",
"summary": "管理端删除指定订单",
"parameters": [
{
"type": "string",
"description": "订单 ID",
"description": "订单ID",
"name": "id",
"in": "path",
"required": true
@@ -326,13 +332,14 @@
"AdminToken": []
}
],
"description": "含下架商品、卡密字段等完整数据，仅限管理令牌访问。需在请求头携带 `X-Admin-Token`。",
"produces": [
"application/json"
],
"tags": [
"管理端-商品"
],
"summary": "全部商品（管理）",
"summary": "管理端获取全部商品列表",
"responses": {
"200": {
"description": "OK",
@@ -360,6 +367,7 @@
"AdminToken": []
}
],
"description": "提交完整商品载荷：价格、卡密/固定内容、收款码链接、是否上架等。校验失败返回 400。",
"consumes": [
"application/json"
],
@@ -369,10 +377,10 @@
"tags": [
"管理端-商品"
],
"summary": "创建商品",
"summary": "管理端创建商品",
"parameters": [
{
"description": "商品字段",
"description": "商品各字段（含可选卡密、截图、收款码等）",
"name": "body",
"in": "body",
"required": true,
@@ -416,6 +424,7 @@
"AdminToken": []
}
],
"description": "路径参数为商品 ID，请求体为整包覆盖式更新（以服务端绑定逻辑为准）。未找到则 404。",
"consumes": [
"application/json"
],
@@ -425,17 +434,17 @@
"tags": [
"管理端-商品"
],
"summary": "更新商品",
"summary": "管理端更新商品",
"parameters": [
{
"type": "string",
"description": "商品 ID",
"description": "商品ID",
"name": "id",
"in": "path",
"required": true
},
{
"description": "商品字段",
"description": "待写入的商品字段",
"name": "body",
"in": "body",
"required": true,
@@ -483,17 +492,18 @@
"AdminToken": []
}
],
"description": "按 ID 永久删除商品记录（影响以数据库外键/业务逻辑为准），需管理令牌。",
"produces": [
"application/json"
],
"tags": [
"管理端-商品"
],
"summary": "删除商品",
"summary": "管理端删除商品",
"parameters": [
{
"type": "string",
"description": "商品 ID",
"description": "商品ID",
"name": "id",
"in": "path",
"required": true
@@ -528,6 +538,7 @@
"AdminToken": []
}
],
"description": "PATCH 请求体为 `{ \"active\": true|false }`，用于快速上下架而不改其它字段。",
"consumes": [
"application/json"
],
@@ -537,17 +548,17 @@
"tags": [
"管理端-商品"
],
"summary": "切换上架状态",
"summary": "管理端切换商品上架状态",
"parameters": [
{
"type": "string",
"description": "商品 ID",
"description": "商品ID",
"name": "id",
"in": "path",
"required": true
},
{
"description": "{active}",
"description": "上架开关 { \\",
"name": "body",
"in": "body",
"required": true,
@@ -591,6 +602,7 @@
"AdminToken": []
}
],
"description": "打开维护后前台可展示原因文案；需管理令牌。请求体含 `maintenance` 布尔与可选 `reason`。",
"consumes": [
"application/json"
],
@@ -600,10 +612,10 @@
"tags": [
"管理端-站点"
],
"summary": "设置维护模式",
"summary": "设置全站维护模式",
"parameters": [
{
"description": "维护开关与原因",
"description": "maintenance 与 reason",
"name": "body",
"in": "body",
"required": true,
@@ -647,13 +659,14 @@
"AdminToken": []
}
],
"description": "返回当前站点发件配置；密码字段以占位符脱敏显示，不会返回明文。",
"produces": [
"application/json"
],
"tags": [
"管理端-站点"
],
"summary": "获取 SMTP 配置",
"summary": "获取发信 SMTP 配置（脱敏）",
"responses": {
"200": {
"description": "OK",
@@ -681,6 +694,7 @@
"AdminToken": []
}
],
"description": "写入 SMTP 主机、端口、账号等；若密码仍为脱敏占位符则保留库中已有密码（实现细节见服务逻辑）。",
"consumes": [
"application/json"
],
@@ -690,10 +704,10 @@
"tags": [
"管理端-站点"
],
"summary": "保存 SMTP 配置",
"summary": "保存发信 SMTP 配置",
"parameters": [
{
"description": "SMTP 字段",
"description": "SMTP 连接与发件人信息",
"name": "body",
"in": "body",
"required": true,
@@ -737,13 +751,14 @@
"AdminToken": []
}
],
"description": "聚合展示配置摘要、数据库/MySQL、RabbitMQ、Redis 等探测结果与进程启动时间，便于运维排查；需管理令牌。",
"produces": [
"application/json"
],
"tags": [
"管理端-系统"
],
"summary": "系统运行状态",
"summary": "管理端系统运行状态与依赖探活",
"responses": {
"200": {
"description": "OK",
@@ -763,7 +778,7 @@
},
"/api/admin/verify": {
"post": {
"description": "响应为 {\"valid\": true/false}，不泄露真实口令。",
"description": "请求体 JSON 含 `token` 字段；响应仅返回 `{\"valid\": true|false}`，不会返回真实口令或敏感信息。",
"consumes": [
"application/json"
],
@@ -773,10 +788,10 @@
"tags": [
"管理端-认证"
],
"summary": "校验管理员令牌",
"summary": "校验管理端令牌是否有效",
"parameters": [
{
"description": "待校验 token",
"description": "待校验的管理员 token（JSON）",
"name": "body",
"in": "body",
"required": true,
@@ -802,13 +817,14 @@
"BearerAuth": []
}
],
"description": "需在请求头携带有效的 `Authorization: Bearer \u003ctoken\u003e`。返回该登录用户在客服系统中与管理员往来的全部消息列表。",
"produces": [
"application/json"
],
"tags": [
"聊天（用户）"
],
"summary": "我的聊天消息",
"summary": "拉取当前用户聊天记录",
"responses": {
"200": {
"description": "OK",
@@ -836,6 +852,7 @@
"BearerAuth": []
}
],
"description": "需在请求头携带 Bearer。正文为 JSON `content` 字段；可能因频率限制返回 429。",
"consumes": [
"application/json"
],
@@ -845,10 +862,10 @@
"tags": [
"聊天（用户）"
],
"summary": "发送用户消息",
"summary": "用户发送聊天消息",
"parameters": [
{
"description": "消息正文",
"description": "消息正文（JSON）",
"name": "body",
"in": "body",
"required": true,
@@ -893,6 +910,7 @@
},
"/api/checkout": {
"post": {
"description": "根据商品配置决定是否需要登录（`requireLogin`）。可附带 `Authorization: Bearer` 以关联账号、限购与通知邮箱。付费订单走萌芽支付时需商品已配置收款码；同一商品在他人待支付锁定期内可能返回 409；同一账号存在待支付单时也可能冲突。成功返回订单概要及二维码链接等。",
"consumes": [
"application/json"
],
@@ -902,16 +920,16 @@
"tags": [
"订单"
],
"summary": "结账创建订单",
"summary": "结账并创建订单",
"parameters": [
{
"type": "string",
"description": "Bearer 用户 token（部分商品必填）",
"description": "可选；格式 Bearer + 空格 + token，部分商品必填",
"name": "Authorization",
"in": "header"
},
{
"description": "结账参数",
"description": "结账请求体：商品、数量、联系方式等",
"name": "body",
"in": "body",
"required": true,
@@ -946,7 +964,7 @@
}
},
"409": {
"description": "库存锁定冲突或同用户待支付",
"description": "库存锁定冲突（他人正在支付）或同账号待支付单未满间隔",
"schema": {
"$ref": "#/definitions/handlers.SwaggerErrorBody"
}
@@ -962,6 +980,7 @@
},
"/api/health": {
"get": {
"description": "用于负载均衡或编排探活：`status` 恒为 ok 表示 HTTP 服务存活；`rabbitmq` 为 `disabled`（未启用消息队列客户端）、`ok`（连接可用）或以 `error:` 开头的错误片段。",
"produces": [
"application/json"
],
@@ -971,7 +990,7 @@
"summary": "健康检查",
"responses": {
"200": {
"description": "status ok；rabbitmq 为 disabled|ok|error:...",
"description": "status 为 ok；rabbitmq 为 disabled、ok 或 error: 前缀错误信息",
"schema": {
"type": "object",
"additionalProperties": true
@@ -987,13 +1006,14 @@
"BearerAuth": []
}
],
"description": "必须携带有效 Bearer。列表中处于待支付状态的订单不会包含已分配卡密等敏感字段，防止泄露。",
"produces": [
"application/json"
],
"tags": [
"订单"
],
"summary": "我的订单",
"summary": "查询当前登录用户的订单列表",
"responses": {
"200": {
"description": "OK",
@@ -1018,17 +1038,18 @@
},
"/api/orders/{id}/cancel": {
"post": {
"description": "仅对允许取消的状态生效（如待支付）；已完成订单会冲突。成功时释放预留库存/卡密占用。请勿在公网暴露此能力时省略鉴权策略（实现以代码为准）。",
"produces": [
"application/json"
],
"tags": [
"订单"
],
"summary": "取消订单",
"summary": "取消待支付订单",
"parameters": [
{
"type": "string",
"description": "订单 ID",
"description": "订单ID",
"name": "id",
"in": "path",
"required": true
@@ -1064,17 +1085,18 @@
},
"/api/orders/{id}/confirm": {
"post": {
"description": "用于用户侧「确认」动作：已完成订单直接返回数据；待支付时若仍未到账则 409；已取消或超时 410。手动发货等场景下会触发邮件通知（若配置）。",
"produces": [
"application/json"
],
"tags": [
"订单"
],
"summary": "确认订单",
"summary": "确认订单（核销/完成流程）",
"parameters": [
{
"type": "string",
"description": "订单 ID",
"description": "订单ID",
"name": "id",
"in": "path",
"required": true
@@ -1094,13 +1116,13 @@
}
},
"409": {
"description": "待支付未到账等",
"description": "待支付但金额未核对到账等",
"schema": {
"$ref": "#/definitions/handlers.SwaggerErrorBody"
}
},
"410": {
"description": "已取消或超时",
"description": "订单已取消或已超过待支付时限",
"schema": {
"$ref": "#/definitions/handlers.SwaggerErrorBody"
}
@@ -1110,17 +1132,18 @@
},
"/api/orders/{id}/payment-status": {
"get": {
"description": "供前端轮询待支付订单：返回状态、应付快照、过期时间等；不包含卡密等敏感发货内容。路径参数为订单 ID。",
"produces": [
"application/json"
],
"tags": [
"订单"
],
"summary": "订单支付状态",
"summary": "查询订单支付状态（轮询）",
"parameters": [
{
"type": "string",
"description": "订单 ID",
"description": "订单ID",
"name": "id",
"in": "path",
"required": true
@@ -1144,13 +1167,14 @@
},
"/api/products": {
"get": {
"description": "返回当前处于「上架」状态的商品集合，仅包含前台展示所需字段（不含卡密、管理字段等）。无需登录。",
"produces": [
"application/json"
],
"tags": [
"公开"
],
"summary": "上架商品列表",
"summary": "获取上架商品列表",
"responses": {
"200": {
"description": "OK",
@@ -1169,17 +1193,18 @@
},
"/api/products/{id}/view": {
"post": {
"description": "对指定商品增加浏览计数；是否计入由服务端对访客指纹去重策略决定，用于热门统计。路径参数为商品 ID。",
"produces": [
"application/json"
],
"tags": [
"公开"
],
"summary": "记录商品浏览",
"summary": "记录商品浏览次数",
"parameters": [
{
"type": "string",
"description": "商品 ID",
"description": "商品ID（路径）",
"name": "id",
"in": "path",
"required": true
@@ -1203,13 +1228,14 @@
},
"/api/site/maintenance": {
"get": {
"description": "返回当前是否开启全站维护、以及展示给前端的维护原因文案（公开接口，无需管理令牌）。",
"produces": [
"application/json"
],
"tags": [
"公开"
],
"summary": "维护模式状态",
"summary": "获取维护模式状态",
"responses": {
"200": {
"description": "OK",
@@ -1228,13 +1254,14 @@
},
"/api/site/visit": {
"post": {
"description": "记录访客一次访问并累加全站访问计数；是否计入由服务端指纹等策略决定，响应中含最新总访问量与本次是否计入。",
"produces": [
"application/json"
],
"tags": [
"公开"
],
"summary": "记录站点访问",
"summary": "上报一次站点访问",
"responses": {
"200": {
"description": "OK",
@@ -1253,13 +1280,14 @@
},
"/api/stats": {
"get": {
"description": "返回全站累计订单数与累计访问量（公开读，用于首页展示等）。",
"produces": [
"application/json"
],
"tags": [
"公开"
],
"summary": "站点统计",
"summary": "获取站点聚合统计",
"responses": {
"200": {
"description": "OK",
@@ -1278,6 +1306,7 @@
},
"/api/webhooks/mengya-pay": {
"post": {
"description": "由支付渠道/转发服务 POST 原始 JSON；服务端解析到账金额并尝试匹配待支付订单。若配置 `WEBHOOK_MENGYA_SECRET`，请求头 `X-Webhook-Secret` 必须与其一致。本地联调与生产 `https://store.shumengya.top` 均使用同一路径，由部署时的域名与 TLS 决定回调 URL。",
"consumes": [
"application/json"
],
@@ -1287,11 +1316,11 @@
"tags": [
"Webhook"
],
"summary": "萌芽支付 Webhook",
"summary": "萌芽支付到账 Webhook",
"parameters": [
{
"type": "string",
"description": "与 WEBHOOK_MENGYA_SECRET 一致",
"description": "与进程环境变量 WEBHOOK_MENGYA_SECRET 一致；未配置密钥时可不填",
"name": "X-Webhook-Secret",
"in": "header"
}
@@ -1331,13 +1360,14 @@
"BearerAuth": []
}
],
"description": "需 Bearer 登录。返回该账号已收藏的商品 ID 数组（顺序由存储实现决定）。",
"produces": [
"application/json"
],
"tags": [
"收藏"
],
"summary": "收藏列表",
"summary": "获取当前用户收藏列表",
"responses": {
"200": {
"description": "OK",
@@ -1365,6 +1395,7 @@
"BearerAuth": []
}
],
"description": "需 Bearer。请求体为 `{ \"productId\": \"...\" }`；幂等语义由存储层实现（重复添加可忽略或报错以实际为准）。",
"consumes": [
"application/json"
],
@@ -1374,10 +1405,10 @@
"tags": [
"收藏"
],
"summary": "添加收藏",
"summary": "添加商品到收藏",
"parameters": [
{
"description": "商品 ID",
"description": "包含 productId 的 JSON",
"name": "body",
"in": "body",
"required": true,
@@ -1421,17 +1452,18 @@
"BearerAuth": []
}
],
"description": "需 Bearer。路径参数为要移除的商品 ID。",
"produces": [
"application/json"
],
"tags": [
"收藏"
],
"summary": "移除收藏",
"summary": "从收藏中移除商品",
"parameters": [
{
"type": "string",
"description": "商品 ID",
"description": "商品ID（路径）",
"name": "id",
"in": "path",
"required": true
@@ -2153,19 +2185,19 @@
},
"securityDefinitions": {
"AdminToken": {
"description": "管理端令牌（也可使用 Authorization 头或 query token，见各接口说明）",
"description": "管理端访问令牌：与进程环境变量 `ADMIN_TOKEN` 一致。部分管理路由也可使用 `Authorization` 头或 Query `token`（以具体路由实现为准）。",
"type": "apiKey",
"name": "X-Admin-Token",
"in": "header"
},
"BearerAuth": {
"description": "用户访问令牌，格式: Bearer 空格 + token",
"description": "用户访问令牌：请求头 `Authorization`，值为 `Bearer ` 后接 SproutGate 返回的 JWT/access token（部分公开接口可不携带）。",
"type": "apiKey",
"name": "Authorization",
"in": "header"
},
"WebhookSecret": {
"description": "与服务端 WEBHOOK_MENGYA_SECRET 一致时校验萌芽支付 Webhook",
"description": "当服务端配置了 `WEBHOOK_MENGYA_SECRET` 时，萌芽支付到账回调 `POST /api/webhooks/mengya-pay` 需携带本头且值与密钥完全一致，否则返回 403。",
"type": "apiKey",
"name": "X-Webhook-Secret",
"in": "header"

183
mengyastore-backend-go/docs/swagger.yaml
View File

@@ -444,14 +444,22 @@ definitions:
host: localhost:8080
info:
contact: {}
description: 商品、下单、站点统计、收藏与客服聊天；用户登录由萌芽账户认证中心（SproutGate）校验。监听地址以 HTTP_LISTEN_ADDR
为准。
description: |-
萌芽小店电商后端 HTTP API：商品、下单结账、订单与支付、站点统计与访问、维护模式、收藏、用户/管理员聊天、萌芽支付 Webhook，以及管理端商品/订单/站点与运维状态等。用户身份由萌芽账户认证中心（SproutGate）签发令牌并完成校验。
**运行环境与基地址**
- **本地开发**：监听地址由环境变量 `HTTP_LISTEN_ADDR` 决定，未设置时默认为 `:8080`，即常见入口 `http://localhost:8080`。可在浏览器打开 `http://localhost:8080/swagger/index.html` 查看本页同款文档并调试。
- **生产部署**：线上前台/API 域名为 `https://store.shumengya.top`（HTTPS）。若前面还有网关、路径前缀或端口映射，请在拼接请求 URL 时以实际对外发布地址为准；Swagger 中默认 Host 为本地，联调线上时请将浏览器地址或客户端 Base URL 换成生产基地址。
**说明**：本 OpenAPI 由代码注释生成；与进程真实监听、反向代理头无关，仅作契约参考。
title: 萌芽小店 API
version: 1.0.0-go
paths:
/:
get:
description: 返回服务描述、主要路径指引与版本（非 OpenAPI 详尽列表，完整契约见 /swagger）。
description: 访问服务根路径 `/` 返回 JSON：服务简介、本地与生产环境说明、主要业务路由分组、运行版本与时间戳。完整请求/响应模型请使用
Swagger UI：`GET /swagger/index.html`。本地一般为 `http://localhost:8080/`，生产域名为
`https://store.shumengya.top/`。
produces:
- application/json
responses:
@@ -460,11 +468,12 @@ paths:
schema:
additionalProperties: true
type: object
summary: API 根信息与端点索引
summary: 根路径 API 说明与路由索引
tags:
- 元信息
/api/admin/chat:
get:
description: 返回每个有过消息的用户账号等信息，供客服选择会话；需管理令牌 `X-Admin-Token`。
produces:
- application/json
responses:
@@ -483,13 +492,14 @@ paths:
$ref: '#/definitions/handlers.SwaggerErrorBody'
security:
- AdminToken: []
summary: 全部会话列表
summary: 管理端：列出全部聊天会话
tags:
- 管理端-聊天
/api/admin/chat/{account}:
delete:
description: 删除该账号在系统中的全部聊天消息记录；不可恢复请谨慎使用。
parameters:
- description: 用户账号
- description: 用户账号（路径）
in: path
name: account
required: true
@@ -515,12 +525,13 @@ paths:
$ref: '#/definitions/handlers.SwaggerErrorBody'
security:
- AdminToken: []
summary: 清空会话
summary: 管理端：清空与某用户的会话
tags:
- 管理端-聊天
get:
description: 路径参数 `account` 为用户账号标识；返回按时间排列的消息数组；需管理令牌。
parameters:
- description: 用户账号
- description: 用户账号（路径）
in: path
name: account
required: true
@@ -546,19 +557,20 @@ paths:
$ref: '#/definitions/handlers.SwaggerErrorBody'
security:
- AdminToken: []
summary: 指定用户聊天记录
summary: 管理端：查看某用户的完整聊天记录
tags:
- 管理端-聊天
post:
consumes:
- application/json
description: 路径为对方账号，JSON body 含 `content`；写入后用户侧拉取可见。
parameters:
- description: 用户账号
- description: 用户账号（路径）
in: path
name: account
required: true
type: string
- description: 回复内容
- description: 回复正文 JSON
in: body
name: body
required: true
@@ -585,11 +597,12 @@ paths:
$ref: '#/definitions/handlers.SwaggerErrorBody'
security:
- AdminToken: []
summary: 管理员回复
summary: 管理端：向用户回复一条消息
tags:
- 管理端-聊天
/api/admin/orders:
get:
description: 返回数据库中订单全量列表（含敏感字段），供后台管理；需 `X-Admin-Token`。
produces:
- application/json
responses:
@@ -607,13 +620,14 @@ paths:
$ref: '#/definitions/handlers.SwaggerErrorBody'
security:
- AdminToken: []
summary: 全部订单（管理）
summary: 管理端获取全部订单
tags:
- 管理端-订单
/api/admin/orders/{id}:
delete:
description: 按路径中的订单 ID 删除记录；不可恢复请谨慎操作。
parameters:
- description: 订单 ID
- description: 订单ID
in: path
name: id
required: true
@@ -639,11 +653,12 @@ paths:
$ref: '#/definitions/handlers.SwaggerErrorBody'
security:
- AdminToken: []
summary: 删除订单
summary: 管理端删除指定订单
tags:
- 管理端-订单
/api/admin/products:
get:
description: 含下架商品、卡密字段等完整数据，仅限管理令牌访问。需在请求头携带 `X-Admin-Token`。
produces:
- application/json
responses:
@@ -661,14 +676,15 @@ paths:
$ref: '#/definitions/handlers.SwaggerErrorBody'
security:
- AdminToken: []
summary: 全部商品（管理）
summary: 管理端获取全部商品列表
tags:
- 管理端-商品
post:
consumes:
- application/json
description: 提交完整商品载荷：价格、卡密/固定内容、收款码链接、是否上架等。校验失败返回 400。
parameters:
- description: 商品字段
- description: 商品各字段（含可选卡密、截图、收款码等）
in: body
name: body
required: true
@@ -695,13 +711,14 @@ paths:
$ref: '#/definitions/handlers.SwaggerErrorBody'
security:
- AdminToken: []
summary: 创建商品
summary: 管理端创建商品
tags:
- 管理端-商品
/api/admin/products/{id}:
delete:
description: 按 ID 永久删除商品记录（影响以数据库外键/业务逻辑为准），需管理令牌。
parameters:
- description: 商品 ID
- description: 商品ID
in: path
name: id
required: true
@@ -723,19 +740,20 @@ paths:
$ref: '#/definitions/handlers.SwaggerErrorBody'
security:
- AdminToken: []
summary: 删除商品
summary: 管理端删除商品
tags:
- 管理端-商品
put:
consumes:
- application/json
description: 路径参数为商品 ID，请求体为整包覆盖式更新（以服务端绑定逻辑为准）。未找到则 404。
parameters:
- description: 商品 ID
- description: 商品ID
in: path
name: id
required: true
type: string
- description: 商品字段
- description: 待写入的商品字段
in: body
name: body
required: true
@@ -766,20 +784,21 @@ paths:
$ref: '#/definitions/handlers.SwaggerErrorBody'
security:
- AdminToken: []
summary: 更新商品
summary: 管理端更新商品
tags:
- 管理端-商品
/api/admin/products/{id}/status:
patch:
consumes:
- application/json
description: 'PATCH 请求体为 `{ "active": true|false }`，用于快速上下架而不改其它字段。'
parameters:
- description: 商品 ID
- description: 商品ID
in: path
name: id
required: true
type: string
- description: '{active}'
- description: 上架开关 { \
in: body
name: body
required: true
@@ -806,15 +825,16 @@ paths:
$ref: '#/definitions/handlers.SwaggerErrorBody'
security:
- AdminToken: []
summary: 切换上架状态
summary: 管理端切换商品上架状态
tags:
- 管理端-商品
/api/admin/site/maintenance:
post:
consumes:
- application/json
description: 打开维护后前台可展示原因文案；需管理令牌。请求体含 `maintenance` 布尔与可选 `reason`。
parameters:
- description: 维护开关与原因
- description: maintenance 与 reason
in: body
name: body
required: true
@@ -841,11 +861,12 @@ paths:
$ref: '#/definitions/handlers.SwaggerErrorBody'
security:
- AdminToken: []
summary: 设置维护模式
summary: 设置全站维护模式
tags:
- 管理端-站点
/api/admin/site/smtp:
get:
description: 返回当前站点发件配置；密码字段以占位符脱敏显示，不会返回明文。
produces:
- application/json
responses:
@@ -863,14 +884,15 @@ paths:
$ref: '#/definitions/handlers.SwaggerErrorBody'
security:
- AdminToken: []
summary: 获取 SMTP 配置
summary: 获取发信 SMTP 配置（脱敏）
tags:
- 管理端-站点
post:
consumes:
- application/json
description: 写入 SMTP 主机、端口、账号等；若密码仍为脱敏占位符则保留库中已有密码（实现细节见服务逻辑）。
parameters:
- description: SMTP 字段
- description: SMTP 连接与发件人信息
in: body
name: body
required: true
@@ -897,11 +919,12 @@ paths:
$ref: '#/definitions/handlers.SwaggerErrorBody'
security:
- AdminToken: []
summary: 保存 SMTP 配置
summary: 保存发信 SMTP 配置
tags:
- 管理端-站点
/api/admin/system-status:
get:
description: 聚合展示配置摘要、数据库/MySQL、RabbitMQ、Redis 等探测结果与进程启动时间，便于运维排查；需管理令牌。
produces:
- application/json
responses:
@@ -916,16 +939,16 @@ paths:
$ref: '#/definitions/handlers.SwaggerErrorBody'
security:
- AdminToken: []
summary: 系统运行状态
summary: 管理端系统运行状态与依赖探活
tags:
- 管理端-系统
/api/admin/verify:
post:
consumes:
- application/json
description: '响应为 {"valid": true/false}，不泄露真实口令。'
description: '请求体 JSON 含 `token` 字段；响应仅返回 `{"valid": true|false}`，不会返回真实口令或敏感信息。'
parameters:
- description: 待校验 token
- description: 待校验的管理员 token（JSON）
in: body
name: body
required: true
@@ -938,11 +961,12 @@ paths:
description: OK
schema:
$ref: '#/definitions/handlers.SwaggerValidBody'
summary: 校验管理员令牌
summary: 校验管理端令牌是否有效
tags:
- 管理端-认证
/api/chat/messages:
get:
description: '需在请求头携带有效的 `Authorization: Bearer <token>`。返回该登录用户在客服系统中与管理员往来的全部消息列表。'
produces:
- application/json
responses:
@@ -960,14 +984,15 @@ paths:
$ref: '#/definitions/handlers.SwaggerErrorBody'
security:
- BearerAuth: []
summary: 我的聊天消息
summary: 拉取当前用户聊天记录
tags:
- 聊天（用户）
post:
consumes:
- application/json
description: 需在请求头携带 Bearer。正文为 JSON `content` 字段；可能因频率限制返回 429。
parameters:
- description: 消息正文
- description: 消息正文（JSON）
in: body
name: body
required: true
@@ -998,19 +1023,21 @@ paths:
$ref: '#/definitions/handlers.SwaggerErrorBody'
security:
- BearerAuth: []
summary: 发送用户消息
summary: 用户发送聊天消息
tags:
- 聊天（用户）
/api/checkout:
post:
consumes:
- application/json
description: '根据商品配置决定是否需要登录（`requireLogin`）。可附带 `Authorization: Bearer` 以关联账号、限购与通知邮箱。付费订单走萌芽支付时需商品已配置收款码；同一商品在他人待支付锁定期内可能返回
409；同一账号存在待支付单时也可能冲突。成功返回订单概要及二维码链接等。'
parameters:
- description: Bearer 用户 token（部分商品必填）
- description: 可选；格式 Bearer + 空格 + token，部分商品必填
in: header
name: Authorization
type: string
- description: 结账参数
- description: 结账请求体：商品、数量、联系方式等
in: body
name: body
required: true
@@ -1036,23 +1063,25 @@ paths:
schema:
$ref: '#/definitions/handlers.SwaggerErrorBody'
"409":
description: 库存锁定冲突或同用户待支付
description: 库存锁定冲突（他人正在支付）或同账号待支付单未满间隔
schema:
$ref: '#/definitions/handlers.SwaggerErrorBody'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/handlers.SwaggerErrorBody'
summary: 结账创建订单
summary: 结账并创建订单
tags:
- 订单
/api/health:
get:
description: 用于负载均衡或编排探活：`status` 恒为 ok 表示 HTTP 服务存活；`rabbitmq` 为 `disabled`（未启用消息队列客户端）、`ok`（连接可用）或以
`error:` 开头的错误片段。
produces:
- application/json
responses:
"200":
description: status ok；rabbitmq 为 disabled|ok|error:...
description: 'status 为 ok；rabbitmq 为 disabled、ok 或 error: 前缀错误信息'
schema:
additionalProperties: true
type: object
@@ -1061,6 +1090,7 @@ paths:
- 健康检查
/api/orders:
get:
description: 必须携带有效 Bearer。列表中处于待支付状态的订单不会包含已分配卡密等敏感字段，防止泄露。
produces:
- application/json
responses:
@@ -1078,13 +1108,14 @@ paths:
$ref: '#/definitions/handlers.SwaggerErrorBody'
security:
- BearerAuth: []
summary: 我的订单
summary: 查询当前登录用户的订单列表
tags:
- 订单
/api/orders/{id}/cancel:
post:
description: 仅对允许取消的状态生效（如待支付）；已完成订单会冲突。成功时释放预留库存/卡密占用。请勿在公网暴露此能力时省略鉴权策略（实现以代码为准）。
parameters:
- description: 订单 ID
- description: 订单ID
in: path
name: id
required: true
@@ -1108,13 +1139,14 @@ paths:
description: Internal Server Error
schema:
$ref: '#/definitions/handlers.SwaggerErrorBody'
summary: 取消订单
summary: 取消待支付订单
tags:
- 订单
/api/orders/{id}/confirm:
post:
description: 用于用户侧「确认」动作：已完成订单直接返回数据；待支付时若仍未到账则 409；已取消或超时 410。手动发货等场景下会触发邮件通知（若配置）。
parameters:
- description: 订单 ID
- description: 订单ID
in: path
name: id
required: true
@@ -1131,20 +1163,21 @@ paths:
schema:
$ref: '#/definitions/handlers.SwaggerErrorBody'
"409":
description: 待支付未到账等
description: 待支付但金额未核对到账等
schema:
$ref: '#/definitions/handlers.SwaggerErrorBody'
"410":
description: 已取消或超时
description: 订单已取消或已超过待支付时限
schema:
$ref: '#/definitions/handlers.SwaggerErrorBody'
summary: 确认订单
summary: 确认订单（核销/完成流程）
tags:
- 订单
/api/orders/{id}/payment-status:
get:
description: 供前端轮询待支付订单：返回状态、应付快照、过期时间等；不包含卡密等敏感发货内容。路径参数为订单 ID。
parameters:
- description: 订单 ID
- description: 订单ID
in: path
name: id
required: true
@@ -1160,11 +1193,12 @@ paths:
description: Not Found
schema:
$ref: '#/definitions/handlers.SwaggerErrorBody'
summary: 订单支付状态
summary: 查询订单支付状态（轮询）
tags:
- 订单
/api/products:
get:
description: 返回当前处于「上架」状态的商品集合，仅包含前台展示所需字段（不含卡密、管理字段等）。无需登录。
produces:
- application/json
responses:
@@ -1176,13 +1210,14 @@ paths:
description: Internal Server Error
schema:
$ref: '#/definitions/handlers.SwaggerErrorBody'
summary: 上架商品列表
summary: 获取上架商品列表
tags:
- 公开
/api/products/{id}/view:
post:
description: 对指定商品增加浏览计数；是否计入由服务端对访客指纹去重策略决定，用于热门统计。路径参数为商品 ID。
parameters:
- description: 商品 ID
- description: 商品ID（路径）
in: path
name: id
required: true
@@ -1198,11 +1233,12 @@ paths:
description: Not Found
schema:
$ref: '#/definitions/handlers.SwaggerErrorBody'
summary: 记录商品浏览
summary: 记录商品浏览次数
tags:
- 公开
/api/site/maintenance:
get:
description: 返回当前是否开启全站维护、以及展示给前端的维护原因文案（公开接口，无需管理令牌）。
produces:
- application/json
responses:
@@ -1214,11 +1250,12 @@ paths:
description: Internal Server Error
schema:
$ref: '#/definitions/handlers.SwaggerErrorBody'
summary: 维护模式状态
summary: 获取维护模式状态
tags:
- 公开
/api/site/visit:
post:
description: 记录访客一次访问并累加全站访问计数；是否计入由服务端指纹等策略决定，响应中含最新总访问量与本次是否计入。
produces:
- application/json
responses:
@@ -1230,11 +1267,12 @@ paths:
description: Internal Server Error
schema:
$ref: '#/definitions/handlers.SwaggerErrorBody'
summary: 记录站点访问
summary: 上报一次站点访问
tags:
- 公开
/api/stats:
get:
description: 返回全站累计订单数与累计访问量（公开读，用于首页展示等）。
produces:
- application/json
responses:
@@ -1246,15 +1284,18 @@ paths:
description: Internal Server Error
schema:
$ref: '#/definitions/handlers.SwaggerErrorBody'
summary: 站点统计
summary: 获取站点聚合统计
tags:
- 公开
/api/webhooks/mengya-pay:
post:
consumes:
- application/json
description: 由支付渠道/转发服务 POST 原始 JSON；服务端解析到账金额并尝试匹配待支付订单。若配置 `WEBHOOK_MENGYA_SECRET`，请求头
`X-Webhook-Secret` 必须与其一致。本地联调与生产 `https://store.shumengya.top` 均使用同一路径，由部署时的域名与
TLS 决定回调 URL。
parameters:
- description: 与 WEBHOOK_MENGYA_SECRET 一致
- description: 与进程环境变量 WEBHOOK_MENGYA_SECRET 一致；未配置密钥时可不填
in: header
name: X-Webhook-Secret
type: string
@@ -1277,11 +1318,12 @@ paths:
description: Internal Server Error
schema:
$ref: '#/definitions/handlers.SwaggerErrorBody'
summary: 萌芽支付 Webhook
summary: 萌芽支付到账 Webhook
tags:
- Webhook
/api/wishlist:
get:
description: 需 Bearer 登录。返回该账号已收藏的商品 ID 数组（顺序由存储实现决定）。
produces:
- application/json
responses:
@@ -1299,14 +1341,15 @@ paths:
$ref: '#/definitions/handlers.SwaggerErrorBody'
security:
- BearerAuth: []
summary: 收藏列表
summary: 获取当前用户收藏列表
tags:
- 收藏
post:
consumes:
- application/json
description: '需 Bearer。请求体为 `{ "productId": "..." }`；幂等语义由存储层实现（重复添加可忽略或报错以实际为准）。'
parameters:
- description: 商品 ID
- description: 包含 productId 的 JSON
in: body
name: body
required: true
@@ -1333,13 +1376,14 @@ paths:
$ref: '#/definitions/handlers.SwaggerErrorBody'
security:
- BearerAuth: []
summary: 添加收藏
summary: 添加商品到收藏
tags:
- 收藏
/api/wishlist/{id}:
delete:
description: 需 Bearer。路径参数为要移除的商品 ID。
parameters:
- description: 商品 ID
- description: 商品ID（路径）
in: path
name: id
required: true
@@ -1365,7 +1409,7 @@ paths:
$ref: '#/definitions/handlers.SwaggerErrorBody'
security:
- BearerAuth: []
summary: 移除收藏
summary: 从收藏中移除商品
tags:
- 收藏
schemes:
@@ -1373,17 +1417,20 @@ schemes:
- https
securityDefinitions:
AdminToken:
description: 管理端令牌（也可使用 Authorization 头或 query token，见各接口说明）
description: 管理端访问令牌：与进程环境变量 `ADMIN_TOKEN` 一致。部分管理路由也可使用 `Authorization` 头或 Query
`token`（以具体路由实现为准）。
in: header
name: X-Admin-Token
type: apiKey
BearerAuth:
description: '用户访问令牌，格式: Bearer 空格 + token'
description: 用户访问令牌：请求头 `Authorization`，值为 `Bearer ` 后接 SproutGate 返回的 JWT/access
token（部分公开接口可不携带）。
in: header
name: Authorization
type: apiKey
WebhookSecret:
description: 与服务端 WEBHOOK_MENGYA_SECRET 一致时校验萌芽支付 Webhook
description: 当服务端配置了 `WEBHOOK_MENGYA_SECRET` 时，萌芽支付到账回调 `POST /api/webhooks/mengya-pay`
需携带本头且值与密钥完全一致，否则返回 403。
in: header
name: X-Webhook-Secret
type: apiKey

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

28
mengyastore-backend-go/main.go
View File

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