小氢云商城系统 API 接口文档

本文档根据 cmd/server/main.go 中的路由配置自动整理，仅覆盖 Go 后端部分接口。

所有业务接口统一走 /api 前缀。

一、全局说明

1. 基础信息

• 基础路径：/api
• 数据格式：Content-Type: application/json; charset=utf-8（少量接口为表单或图片）
• 字符编码：UTF-8

2. 统一响应格式

除少数直接返回 Gin c.JSON 的示例接口外，绝大多数业务接口采用统一响应结构（pkg/response）：

{
  "code": 200,
  "msg": "操作成功",
  "data": { ... }
}

• code：
  • 成功：200
  • 失败：-1、401、403、404、500 等（根据业务场景）
• msg：人类可读的提示信息
• data：业务数据对象；部分接口无 data 字段

分页返回示例（部分接口使用 SuccessWithPage 或手动返回）：

{
  "code": 0,
  "msg": "success",
  "data": {
    "list": [ ... ],
    "total": 100,
    "page": 1,
    "size": 10
  }
}

注意：老接口与新接口在 code/msg/data 上略有差异，前端需按接口实际返回做兼容。

3. 鉴权与 Token

用户 & 管理员登录后会颁发 JWT，主要通过以下方式传递：

3.1 普通用户接口鉴权（middleware.Auth()）

• Header 方式（推荐）：
  • Authorization: Bearer <token>
  • 或 Authorization: <token>（中间件内部会去掉 Bearer 前缀）
• Cookie 方式（登录接口会自动设置）：
  • Authorization=<token> （HttpOnly）
  • 兼容旧字段：user_token、token 等

未登录访问需要认证的接口时，典型响应：

{
  "code": 401,
  "msg": "请先登录"
}

3.2 管理员接口鉴权（middleware.AdminAuth()）

支持多种 Header 名称（按优先级）：

• ADMIN_TOKEN: <token>
• Admin-Token: <token>
• admin_token: <token>
• Authorization: Bearer <token> 或 Authorization: <token>
• X-Admin-Token: <token>

未登录或登录过期示例：

{
  "code": 401,
  "msg": "未登录或登录已过期"
}

3.3 可选认证（middleware.OptionalAuth()）

• 若带上用户 Token，则在接口内部可以拿到 user_id 做个性化逻辑（价格、收藏等）
• 若不带 Token，接口依然可访问，按游客处理

4. 常用请求头

• Content-Type: application/json：JSON 请求体
• Content-Type: application/x-www-form-urlencoded：表单提交
• Authorization: Bearer <token>：用户 / 管理员登录后的鉴权（视路由中间件而定）
• ADMIN_TOKEN: <token>：管理员接口常用 Header
• User-Agent：用于识别设备类型、写入活跃会话、背景图等

二、公共接口（无需登录）

2.1 健康检查

• URL：GET /health
• 说明：检查服务与数据库状态
• 请求参数：无
• 响应示例：

{
  "status": "ok",
  "time": "2025-11-29 15:30:00",
  "database": {
    "mysql": { ... },
    "redis": true
  }
}

2.2 系统安装状态

• URL：ANY /api/checkInstallStatus
• Handler：installStatusHandler.CheckInstallStatus
• 说明：检查系统是否已安装，安装向导使用
• 鉴权：无需

详细字段见安装相关 Handler / 文档，这里不展开。

2.3 公共配置

• URL：GET /api/public/config
• Handler：getPublicConfig
• 说明：获取公开的应用配置（名称、版本等）
• 请求参数：无
• 响应示例：

{
  "code": 0,
  "data": {
    "app_name": "简化网课",
    "version": "1.0.2"
  }
}

字段说明：

• code：状态码（0 代表成功）
• data.app_name：应用名称
• data.version：版本号

2.4 分类相关

• URL：
  • ANY /api/class
  • ANY /api/getclass
• Handler：categoryHandler.GetAllCategories
• 鉴权：无需
• 说明：获取所有商品分类，返回分类列表

具体字段参见 internal/handler/category_handler.go 与前端使用方式。

2.5 商品相关（可选认证）

• URL：

  • ANY /api/getGoods
  • ANY /api/goodsList

• Handler：goodsHandler.GetGoodsList

• 鉴权：middleware.OptionalAuth()（游客可访问，带 Token 时返回与用户相关的价格等）

• URL：

  • ANY /api/getGoodsById

• Handler：goodsHandler.GetGoodsDetail

• 说明：获取商品详情

价格、库存、标签等字段较多，这部分已有专门文档：《商品类型与订单处理逻辑.md》，此处不重复展开。

2.6 订单相关（下单、查询）

• URL：

  • ANY /api/add
  • ANY /api/add2

• Handler：orderHandler.CreateOrder

• 鉴权：middleware.OptionalAuth()（支持匿名下单）

• 说明：创建订单

• URL：ANY /api/batchOrderAdd

  • 批量下单

• URL：ANY /api/getOrder

  • 查询订单详情

订单字段和价格计算，参考现有《价格计算逻辑问题分析.md》《商品类型与订单处理逻辑.md》。

2.7 二维码接口

该部分已有独立文档：《二维码API文档.md》，这里只给路由速查。

• 二维码：
  • POST /api/qrcode
  • POST /api/qrcode/base64
  • POST /api/qrcode/form

详见 go/docs/二维码API文档.md。

2.8 万能接口（Universal API）

已有独立配置说明文档：《万能接口配置说明.md》。此处重点补充你刚刚改动的调试接口。

2.8.1 测试配置（直接传 JSON）

• URL：ANY /api/public/universalApi/test

• Handler：universalAPIHandler.TestConfig

• 鉴权：无需

• 请求头：

  • Content-Type: application/json

• 请求参数（Body JSON）：

{
  "config_json": "{...}",   // 必填，万能接口配置 JSON 字符串
  "variables": {             // 可选，变量字典
    "user_id": 123,
    "xxx": "yyy"
  },
  "log_title": "测试标题"   // 可选，日志标题
}

• 响应示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "result": { ... 第三方接口响应 ... },
    "timestamp": 1732867200
  }
}

2.8.2 按配置 ID 调用（带请求调试信息）

• URL：ANY /api/public/universalApi/call

• Handler：universalAPIHandler.CallAPI

• 鉴权：无需（建议仅在受控环境使用，如后台调试工具）

• 请求头：

  • Content-Type: application/json（POST 时）

• GET 请求参数：

  • config_id：int，配置 ID

• POST Body JSON：

{
  "config_id": 1,                // 必填，万能API配置ID
  "variables": {                 // 可选，变量字典
    "user": "test",
    "amount": 100,
    "date": "2025-11-29"
  }
}

• 响应示例（关键字段）：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    // === 第三方接口原始解析结果 ===
    "code": 0,
    "msg": "ok",
    "data": { ... },

    // === 调试信息：本次请求的最终 URL / Header / Body（变量已替换） ===
    "_debug_request_url": "https://third.api.com/v1/order?xxx=yyy",
    "_debug_request_header": {
      "Content-Type": ["application/json"],
      "Authorization": ["Bearer abc..."],
      "User-Agent": ["Go-http-client/1.1"]
    },
    "_debug_request_body": "{\"user\":\"test\",\"amount\":100}"
  }
}

字段说明：

• data.code/data.msg/data.data：
  • 为目标第三方接口的返回字段（根据配置里的 response.format、response.dataField 解析）
• _debug_request_url：
  • 实际请求的 URL，包含所有变量替换及查询参数
• _debug_request_header：
  • 实际发送到第三方的请求头（Gin Header 序列化结果）
• _debug_request_body：
  • 实际发送到第三方的请求体，字符串形式

该接口主要用于调试万能接口配置，请勿对外开放给前端普通用户直接调用。

三、认证与用户接口

3.1 用户登录

• URL：ANY /api/login

• Handler：authHandler.Login

• 鉴权：无需

• 请求头：

  • Content-Type: application/x-www-form-urlencoded 或 application/json

• 请求参数：

{
  "username": "test",   // 必填
  "password": "123456", // 必填
  "code": "abcd"        // 必填，图形验证码
}

• 响应示例：

{
  "code": 200,
  "msg": "登录成功！",
  "data": {
    "id": 1,
    "username": "测试用户",
    "token": "<JWT_TOKEN>"
  }
}

登录成功后服务端会设置 Cookie：

• Authorization=<token>（HttpOnly，7 天）
• user_logged_in=1（非 HttpOnly，前端可读，用于判断登录态）

前端后续调用需要登录的接口时，可使用：

• Header：Authorization: Bearer <token>，或依赖 Cookie（同域名下）

3.2 用户注册

• URL：ANY /api/userInvite

• Handler：authHandler.Register

• 鉴权：无需

• 请求参数：

{
  "username": "test",   // 必填
  "password": "123456", // 必填
  "code": "abcd",       // 必填，图形验证码
  "token": "INVITE001"  // 选填，邀请码，可从 Cookie invite_code 获取
}

• 响应示例：

{
  "code": 200,
  "msg": "注册成功！",
  "data": {
    "id": 123
  }
}

3.3 获取验证码图片

• 登录验证码：GET /api/getLoginImage
• 注册验证码：GET /api/getVsCode

根据路径自动识别验证码类型，返回 PNG 图片，主要头部：

• Content-Type: image/png
• Cache-Control: no-cache, no-store, must-revalidate

验证码值存储在服务端 Session，校验时由 /api/login、/api/userInvite 使用。

3.4 获取当前登录用户信息

• URL：ANY /api/getUserInfo

• Handler：authHandler.GetUserInfo

• 鉴权：需要用户登录（middleware.Auth() 间接保护）

• 请求参数：无

• 响应示例：

{
  "code": 200,
  "data": {
    "id": 1,
    "username": "测试用户",
    "money": "100.00",
    "grade": 1,
    "wx": "weixin_id",
    "qq": "123456"
  }
}

四、路由付费相关接口

参考路由：

routeGroup := api.Group("/route")
{
    routeGroup.POST("/purchase", middleware.Auth(), routePurchaseHandler.Purchase)
    routeGroup.GET("/purchases", middleware.Auth(), routePurchaseHandler.GetMyPurchases)
    routeGroup.GET("/check", middleware.OptionalAuth(), routePurchaseHandler.CheckPurchased)
}

// 管理端：
adminAuth.POST("/route-purchase/list", routePurchaseHandler.GetList)

4.1 购买路由访问权限

• URL：POST /api/route/purchase

• 鉴权：用户登录（middleware.Auth()）

• 请求头：

  • Authorization: Bearer <token>
  • Content-Type: application/json

• 请求体：

{
  "route_id": 1,         // 路由ID（推荐使用）
  "route": "/xxx/path"  // 备用：路由路径，route_id 为空时可使用
}

• 响应示例：

{
  "code": 200,
  "msg": "下单成功，等待支付", // 或 "已购买，无需重复购买" 等
  "data": {
    "purchased": false,              // 是否已拥有访问权限
    "pay_url": "https://...",      // 需要支付时返回的支付链接
    "order_no": "202511291530001"  // 订单号
  }
}

4.2 获取我的路由购买记录

• URL：GET /api/route/purchases

• 鉴权：用户登录（middleware.Auth()）

• 请求参数：无（可后续扩展分页）

• 响应示例：

{
  "code": 200,
  "data": [
    {
      "id": 1,
      "user_id": 1001,
      "route_id": 1,
      "route": "/vip/course/list",
      "status": 1,
      "price": "9.90",
      "created_at": "2025-11-29 15:00:00"
    }
  ]
}

具体字段以 models.RoutePurchase 为准，这里给出典型示例。

4.3 检查是否已购买

• URL：GET /api/route/check

• 鉴权：middleware.OptionalAuth()（未登录也可以调用，此时统一返回 purchased: false）

• 请求参数（Query）：

  • route_id：int，必填

• 响应示例（未登录或未购买）：

{
  "code": 200,
  "data": {
    "purchased": false
  }
}

• 响应示例（已购买）：

{
  "code": 200,
  "data": {
    "purchased": true
  }
}

4.4 管理端：路由购买记录列表

• URL：POST /api/admin/route-purchase/list

• 鉴权：管理员登录 + 授权校验（CheckAdminInstall + AdminAuth + LicenseAuth）

• 请求体 JSON（分页 + 筛选）：

{
  "page": 1,
  "size": 20,
  "keyword": "test",   // 可选，支持根据路由/用户等关键字搜索
  "user_id": 1001,      // 可选
  "route_id": 1,        // 可选
  "status": 1           // 可选
}

• 响应示例：

{
  "code": 200,
  "data": [ { ...记录... } ],
  "total": 100,
  "page": 1,
  "size": 20
}

五、管理员接口总览（简要）

完整列出 /api/admin/* 路由，但不逐一展开字段；用于速查。详细字段可按需要再单独拆文档。

• 公开管理员接口（无需 token，仅部分场景可用）：

  • ANY /api/admin/setPublicKey – 设置授权公钥
  • ANY /api/admin/getPublicNodeList – 公共节点列表
  • ANY /api/admin/getPublicCurrentNode – 当前节点
  • ANY /api/admin/switchPublicNode – 切换节点
  • ANY /api/admin/getLoginCode – 登录验证码
  • ANY /api/admin/login – 管理员登录（需 LicenseAuth 授权校验）

• 需要管理员登录 + 授权的接口（部分举例）：

  • 用户管理：/api/admin/users, /api/admin/UserUpdate, /api/admin/UserDelete, ...
  • 财务 / 余额卡密：/api/admin/getMoneyTokens, /api/admin/createMoneyTokens, ...
  • 万能接口管理：/api/admin/universalApi/list, /detail, /create, /update, /updateStatus, /delete, /export, /import
  • 日志、缓存、队列、备份、任务、通知、模板、系统配置等，详见 cmd/server/main.go 中 adminAuth.Any 段落注释。

六、接口分类总览（/ 与 /api/user）

本节对「根路由 /」与「用户路由 /api/user」下的所有接口按功能做一个总览，便于快速定位需要的接口。详细的请求参数与响应示例，参考前文对应章节。

6.1 根路径 / 接口速查

• GET /health
  服务健康检查（数据库、Redis 状态）。

• GET /debug/admin-index
  调试端点，返回嵌入的后台首页 HTML 源码。

• GET /admin/*、GET /admin
  后台管理前端 SPA 入口及静态资源。

• GET /static/*
  静态资源目录映射到 ./static。

• 其它非 /api/* 路径
  由 NoRoute 统一交给前端 home 应用处理，用作前台 SPA 路由（如首页、商品列表、详情页等）。

6.2 /api/user 接口按功能分组

所有以下路径的前缀均为 /api/user。

6.2.1 在线充值 / 支付入口

• ANY /api/user/onlineRecharge
  用户在线充值入口（创建充值订单、获取支付页面），可选认证（登录/游客均可）。

6.2.2 用户通知（支持游客访问）

这部分走 OptionalAuth，带 Token 时按登录用户处理，否则按游客。

• ANY /api/user/getNoticeList – 获取通知列表
• ANY /api/user/markNoticeRead – 标记单条通知为已读
• ANY /api/user/getUnreadNoticeCount – 获取未读通知数量
• ANY /api/user/getNoticeUnreadCount – 获取未读通知数量（兼容旧名称）

6.2.3 用户订单相关（需登录）

• ANY /api/user/OrderAll – 获取当前用户的订单列表
• ANY /api/user/OrderAll_fz – 获取分站订单列表
• ANY /api/user/getWkData – 获取单个订单详情

6.2.4 用户资料与账号管理（需登录）

• ANY /api/user/SetUserData – 修改用户资料
• ANY /api/user/SetUserPassword – 修改登录密码
• ANY /api/user/getlog – 获取用户操作日志
• ANY /api/user/getJunior – 获取下级用户列表
• ANY /api/user/setAlert – 保存提醒设置
• ANY /api/user/saveCollectionDiagram – 保存收款二维码
• ANY /api/user/add_token – 生成用户 API Token
• ANY /api/user/logout – 用户退出登录（JWT 失效）
• ANY /api/user/getConsumerRanking – 获取消费排行榜
• ANY /api/user/image_up – 上传用户图片（头像等）
• ANY /api/user/getInviteOrderCode – 获取邀请下单码
• ANY /api/user/getInviteOrderList – 获取邀请提成日志列表
• ANY /api/user/inviteFun – 生成邀请码

6.2.5 收藏相关（需登录）

• ANY /api/user/getCollectList – 获取收藏列表
• ANY /api/user/removeCollect – 移除收藏（用户接口）

6.2.6 财务 / 余额相关（需登录）

• ANY /api/user/tixian – 提现申请
• ANY /api/user/getTx – 获取提现记录
• ANY /api/user/withdraw/records – 提现记录（标准路由）
• ANY /api/user/recharge – 卡密充值
• ANY /api/user/upGrade – 等级升级
• ANY /api/user/transfer – 余额转账
• ANY /api/user/checkUser – 检查指定用户名是否存在
• ANY /api/user/getTransferHistory – 获取转账记录
• ANY /api/user/getChargeActivityConfig – 获取充值活动配置

6.2.7 分站管理（需登录）

• ANY /api/user/saveRegisterDefaultGrade – 保存注册默认等级
• ANY /api/user/getCategoryList – 获取分站可用分类列表
• ANY /api/user/saveCategorySettings – 保存分类设置
• ANY /api/user/getPriceAdjustGoodsList – 获取可调价商品列表
• ANY /api/user/savePriceAdjustment – 保存价格调整方案
• ANY /api/user/savePriceAdjust – 保存价格调整（兼容旧名称）
• ANY /api/user/deletePriceAdjustment – 删除价格调整
• ANY /api/user/toggleGoodsListed – 切换商品上下架
• ANY /api/user/save_goods_price – 保存商品价格设置
• ANY /api/user/getTemplateList – 获取模板列表
• ANY /api/user/setTemplate – 设置分站模板
• ANY /api/user/getSubstationConfig – 获取分站配置
• ANY /api/user/get_sub – 获取域名绑定状态

6.2.8 登录用户通知（需登录）

• ANY /api/user/getNoticeDetail – 获取通知详情
• ANY /api/user/markAllNoticeRead – 标记所有通知为已读

6.2.9 用户支付接口管理（需登录）

• ANY /api/user/getUserPayments – 获取用户支付接口列表
• ANY /api/user/savePayment – 保存支付接口
• ANY /api/user/deletePayment – 删除支付接口
• ANY /api/user/batchDeletePayment – 批量删除支付接口
• ANY /api/user/togglePaymentStatus – 切换支付接口状态
• ANY /api/user/getPaymentTypes – 获取所有支付接口类型

说明：

• /api/user 下大部分接口都受 Auth 中间件保护，需要用户登录；只有「6.2.1 在线充值」和「6.2.2 用户通知（游客可访问）」等少量接口使用 OptionalAuth 支持游客访问。

七、前台接口详细说明

7.1 健康与安装接口

7.1.1 心跳检测

接口地址：GET /api/ping
功能描述：服务心跳检测，用于健康检查
请求参数：无
响应示例：

{
  "message": "pong"
}

7.1.2 检查系统安装状态

接口地址：ANY /api/checkInstallStatus
功能描述：检查系统是否已安装
请求参数：无
响应示例：

{
  "code": 200,
  "msg": "已安装",
  "data": {
    "installed": true,
    "version": "1.0.0"
  }
}

7.2 分类与商品接口

7.2.1 获取分类列表

接口地址：ANY /api/class 或 ANY /api/getclass
功能描述：获取商品分类列表
请求参数：无
响应示例：

{
  "code": 200,
  "msg": "获取成功",
  "data": [
    {
      "id": 1,
      "name": "课程分类",
      "icon": "course.png",
      "sort": 100,
      "status": 1
    }
  ]
}

7.2.2 获取商品列表

接口地址：ANY /api/getGoods 或 ANY /api/goodsList
功能描述：获取商品列表，支持分页和筛选
请求参数： | 参数名 | 类型 | 必填 | 默认值 | 说明 | |--------|------|------|--------|------| | page | int | 否 | 1 | 页码 | | size | int | 否 | 10 | 每页数量 | | category_id | int | 否 | - | 分类ID | | keyword | string | 否 | - | 搜索关键词 | | sort | string | 否 | "id" | 排序字段 | | order | string | 否 | "desc" | 排序方向 |

响应示例：

{
  "code": 200,
  "msg": "获取成功",
  "data": [
    {
      "id": 1,
      "name": "商品名称",
      "price": 99.00,
      "original_price": 199.00,
      "category_id": 1,
      "category_name": "课程分类",
      "description": "商品描述",
      "image": "https://example.com/image.jpg",
      "status": 1,
      "sales": 100,
      "created_at": "2025-01-01 10:00:00"
    }
  ],
  "total": 100,
  "page": 1,
  "size": 10
}

7.2.3 获取商品详情

接口地址：ANY /api/getGoodsById
功能描述：获取指定商品的详细信息
请求参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | id | int | 是 | 商品ID |

响应示例：

{
  "code": 200,
  "msg": "获取成功",
  "data": {
    "id": 1,
    "name": "商品名称",
    "price": 99.00,
    "original_price": 199.00,
    "category_id": 1,
    "category_name": "课程分类",
    "description": "详细描述...",
    "content": "富文本内容",
    "images": ["image1.jpg", "image2.jpg"],
    "status": 1,
    "sales": 100,
    "stock": 999,
    "created_at": "2025-01-01 10:00:00",
    "updated_at": "2025-01-15 16:30:00"
  }
}

7.2.4 搜索课程/订单

接口地址：ANY /api/searchCourse
功能描述：搜索课程或订单信息
请求参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | keyword | string | 是 | 搜索关键词 | | type | string | 否 | 搜索类型：course/order | | page | int | 否 | 1 | | size | int | 否 | 10 |

响应示例：

{
  "code": 200,
  "msg": "搜索成功",
  "data": {
    "courses": [
      {
        "id": 1,
        "name": "课程名称",
        "price": 99.00,
        "image": "course.jpg"
      }
    ],
    "orders": [
      {
        "id": "ORDER123",
        "course_name": "课程名称",
        "status": "已完成"
      }
    ],
    "total": 50
  }
}

7.3 订单创建与操作接口

7.3.1 创建订单

接口地址：ANY /api/add 或 ANY /api/add2
功能描述：创建新订单
请求参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | goods_id | int | 是 | 商品ID | | quantity | int | 否 | 购买数量，默认1 | | contact_info | string | 否 | 联系信息 | | remark | string | 否 | 订单备注 |

响应示例：

{
  "code": 200,
  "msg": "订单创建成功",
  "data": {
    "order_id": "ORDER20250115001",
    "total_amount": 99.00,
    "pay_url": "https://pay.example.com/ORDER20250115001",
    "expire_time": "2025-01-15 17:30:00"
  }
}

7.3.2 批量下单

接口地址：ANY /api/batchOrderAdd
功能描述：批量创建多个订单
请求参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | orders | array | 是 | 订单列表，每个包含goods_id和quantity |

响应示例：

{
  "code": 200,
  "msg": "批量下单成功",
  "data": {
    "success_count": 5,
    "failed_count": 0,
    "orders": [
      {
        "order_id": "ORDER001",
        "goods_id": 1,
        "quantity": 1,
        "amount": 99.00
      }
    ],
    "total_amount": 495.00
  }
}

7.3.3 查询订单详情

接口地址：ANY /api/getOrder
功能描述：查询订单详细信息
请求参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | order_id | string | 是 | 订单ID |

响应示例：

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "order_id": "ORDER20250115001",
    "goods_name": "商品名称",
    "quantity": 1,
    "unit_price": 99.00,
    "total_amount": 99.00,
    "status": "待支付",
    "pay_status": 0,
    "created_at": "2025-01-15 16:30:00",
    "pay_time": null,
    "contact_info": "联系方式",
    "remark": "备注信息"
  }
}

7.4 认证相关接口

7.4.1 用户登录

接口地址：ANY /api/login
功能描述：用户登录获取访问令牌
请求参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | username | string | 是 | 用户名 | | password | string | 是 | 密码 | | captcha | string | 否 | 验证码（需要时） |

响应示例：

{
  "code": 200,
  "msg": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 123,
      "username": "testuser",
      "nickname": "测试用户",
      "avatar": "avatar.jpg",
      "balance": 100.50,
      "level": "VIP",
      "expire_time": "2025-12-31 23:59:59"
    },
    "expires_in": 86400
  }
}

7.4.2 用户注册

接口地址：ANY /api/userInvite
功能描述：新用户注册
请求参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | username | string | 是 | 用户名 | | password | string | 是 | 密码 | | confirm_password | string | 是 | 确认密码 | | email | string | 否 | 邮箱 | | phone | string | 否 | 手机号 | | invite_code | string | 否 | 邀请码 | | captcha | string | 是 | 验证码 |

响应示例：

{
  "code": 200,
  "msg": "注册成功",
  "data": {
    "user_id": 124,
    "username": "newuser",
    "message": "注册成功，请登录"
  }
}

7.4.3 获取登录验证码

接口地址：GET /api/getLoginImage
功能描述：获取登录验证码图片
请求参数：无
响应：PNG图片

7.4.4 退出登录

接口地址：ANY /api/logout
功能描述：用户退出登录，使令牌失效
请求参数：无（需要Authorization头）
响应示例：

{
  "code": 200,
  "msg": "退出成功"
}

7.5 用户信息接口

7.5.1 获取用户数据

接口地址：ANY /api/UserData
功能描述：获取当前用户的详细信息和统计数据
请求参数：无（需要登录）
响应示例：

{
  "code": 200,
  "msg": "获取成功",
  "data": {
    "user": {
      "id": 123,
      "username": "testuser",
      "nickname": "测试用户",
      "avatar": "avatar.jpg",
      "email": "test@example.com",
      "phone": "13800138000",
      "balance": 100.50,
      "frozen_balance": 0.00,
      "points": 500,
      "level": "VIP",
      "expire_time": "2025-12-31 23:59:59",
      "register_time": "2024-01-01 10:00:00"
    },
    "stats": {
      "total_orders": 25,
      "total_spent": 2475.00,
      "today_orders": 2,
      "today_spent": 198.00,
      "invite_count": 5,
      "invite_rewards": 50.00
    }
  }
}

7.5.2 获取当前用户信息

接口地址：ANY /api/getUserInfo
功能描述：获取当前登录用户的基本信息
请求参数：无（需要登录）
响应示例：

{
  "code": 200,
  "msg": "获取成功",
  "data": {
    "id": 123,
    "username": "testuser",
    "nickname": "测试用户",
    "avatar": "avatar.jpg",
    "balance": 100.50,
    "level": "VIP",
    "is_login": true
  }
}

7.6 系统配置接口

7.6.1 获取系统配置

接口地址：ANY /api/getConfig
功能描述：获取系统公开配置信息
请求参数：无
响应示例：

{
  "code": 200,
  "msg": "获取成功",
  "data": {
    "site_name": "小氢云商城系统",
    "site_url": "https://example.com",
    "version": "1.0.0",
    "icp": "ICP备案号",
    "contact_email": "admin@example.com",
    "payment_ways": [
      {
        "id": 1,
        "name": "支付宝",
        "icon": "alipay.png",
        "status": 1
      }
    ],
    "register_enabled": true,
    "invite_enabled": true
  }
}

7.7 收藏相关接口

7.7.1 检查是否收藏

接口地址：ANY /api/checkCollect
功能描述：检查当前用户是否已收藏指定商品
请求参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | goods_id | int | 是 | 商品ID |

响应示例：

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "collected": true,
    "collect_time": "2025-01-15 10:30:00"
  }
}

7.7.2 添加收藏

接口地址：ANY /api/addCollect
功能描述：收藏指定商品
请求参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | goods_id | int | 是 | 商品ID |

响应示例：

{
  "code": 200,
  "msg": "收藏成功"
}

7.7.3 取消收藏

接口地址：ANY /api/removeCollect
功能描述：取消收藏指定商品
请求参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | goods_id | int | 是 | 商品ID |

响应示例：

{
  "code": 200,
  "msg": "取消收藏成功"
}

7.8 支付相关接口

7.8.1 获取支付方式列表

接口地址：ANY /api/PaymentWay
功能描述：获取可用的支付方式列表
请求参数：无
响应示例：

{
  "code": 200,
  "msg": "获取成功",
  "data": [
    {
      "id": 1,
      "name": "支付宝",
      "code": "alipay",
      "icon": "https://example.com/alipay.png",
      "min_amount": 0.01,
      "max_amount": 50000.00,
      "status": 1,
      "description": "支付宝在线支付"
    },
    {
      "id": 2,
      "name": "微信支付",
      "code": "wechat",
      "icon": "https://example.com/wechat.png",
      "min_amount": 0.01,
      "max_amount": 50000.00,
      "status": 1,
      "description": "微信在线支付"
    }
  ]
}

7.8.2 订单价格计算

接口地址：ANY /api/OrderPrice
功能描述：计算单个订单的价格
请求参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | goods_id | int | 是 | 商品ID | | quantity | int | 否 | 数量，默认1 | | use_balance | boolean | 否 | 是否使用余额 |

响应示例：

{
  "code": 200,
  "msg": "计算成功",
  "data": {
    "goods_id": 1,
    "goods_name": "商品名称",
    "quantity": 1,
    "unit_price": 99.00,
    "discount_amount": 10.00,
    "final_price": 89.00,
    "balance_available": 100.50,
    "can_use_balance": true,
    "need_pay": 0.00
  }
}

7.8.3 批量订单价格计算

接口地址：ANY /api/BatchOrderPrice
功能描述：计算多个订单的总价格
请求参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | orders | array | 是 | 商品列表，每个包含goods_id和quantity |

响应示例：

{
  "code": 200,
  "msg": "计算成功",
  "data": {
    "items": [
      {
        "goods_id": 1,
        "quantity": 2,
        "unit_price": 99.00,
        "subtotal": 198.00
      }
    ],
    "total_amount": 198.00,
    "discount_amount": 20.00,
    "final_price": 178.00,
    "balance_available": 100.50,
    "need_pay": 77.50
  }
}

7.9 二维码接口

7.9.1 生成二维码（图片）

接口地址：POST /api/qrcode
功能描述：生成二维码图片
请求参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | text | string | 是 | 二维码内容 | | size | int | 否 | 二维码大小，默认200 | | level | string | 否 | 纠错级别：L/M/Q/H，默认M |

响应：PNG图片

7.9.2 生成二维码（Base64）

接口地址：POST /api/qrcode/base64
功能描述：生成二维码并返回Base64编码
请求参数：同上
响应示例：

{
  "code": 200,
  "msg": "生成成功",
  "data": {
    "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "size": 200
  }
}

八、/api/user 用户接口详细说明

8.1 在线充值接口

8.1.1 用户在线充值

接口地址：ANY /api/user/onlineRecharge
功能描述：用户余额充值，创建充值订单
请求参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | amount | decimal | 是 | 充值金额 | | payment_way | string | 是 | 支付方式：alipay/wechat | | return_url | string | 否 | 支付成功返回URL |

响应示例：

{
  "code": 200,
  "msg": "充值订单创建成功",
  "data": {
    "recharge_id": "RC20250115001",
    "amount": 100.00,
    "pay_url": "https://pay.example.com/recharge/RC20250115001",
    "expire_time": "2025-01-15 17:30:00"
  }
}

8.2 用户订单接口

8.2.1 获取用户订单列表

接口地址：ANY /api/user/OrderAll
功能描述：获取当前用户的订单列表
请求参数： | 参数名 | 类型 | 必填 | 默认值 | 说明 | |--------|------|------|--------|------| | page | int | 否 | 1 | 页码 | | size | int | 否 | 10 | 每页数量 | | status | string | 否 | - | 订单状态筛选 |

响应示例：

{
  "code": 200,
  "msg": "获取成功",
  "data": [
    {
      "order_id": "ORDER20250115001",
      "goods_name": "商品名称",
      "quantity": 1,
      "total_amount": 99.00,
      "status": "已完成",
      "pay_status": 1,
      "created_at": "2025-01-15 16:30:00",
      "pay_time": "2025-01-15 16:35:00"
    }
  ],
  "total": 25,
  "page": 1,
  "size": 10
}

8.2.2 获取订单详情

接口地址：ANY /api/user/getWkData
功能描述：获取指定订单的详细信息
请求参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | order_id | string | 是 | 订单ID |

响应示例：

{
  "code": 200,
  "msg": "获取成功",
  "data": {
    "order_id": "ORDER20250115001",
    "goods_id": 1,
    "goods_name": "商品名称",
    "quantity": 1,
    "unit_price": 99.00,
    "total_amount": 99.00,
    "status": "已完成",
    "pay_status": 1,
    "contact_info": "联系方式",
    "remark": "备注",
    "created_at": "2025-01-15 16:30:00",
    "pay_time": "2025-01-15 16:35:00",
    "complete_time": "2025-01-15 16:40:00"
  }
}

8.3 用户资料管理

8.3.1 修改用户资料

接口地址：ANY /api/user/SetUserData
功能描述：修改用户个人信息
请求参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | nickname | string | 否 | 昵称 | | email | string | 否 | 邮箱 | | phone | string | 否 | 手机号 | | avatar | string | 否 | 头像URL |

响应示例：

{
  "code": 200,
  "msg": "修改成功"
}

8.3.2 修改登录密码

接口地址：ANY /api/user/SetUserPassword
功能描述：修改用户登录密码
请求参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | old_password | string | 是 | 原密码 | | new_password | string | 是 | 新密码 | | confirm_password | string | 是 | 确认新密码 |

响应示例：

{
  "code": 200,
  "msg": "密码修改成功"
}

8.4 财务相关接口

8.4.1 提现申请

接口地址：ANY /api/user/tixian
功能描述：申请余额提现
请求参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | amount | decimal | 是 | 提现金额 | | account_type | string | 是 | 账户类型：alipay/wechat/bank | | account_info | string | 是 | 账户信息 |

响应示例：

{
  "code": 200,
  "msg": "提现申请提交成功",
  "data": {
    "withdraw_id": "WD20250115001",
    "amount": 100.00,
    "fee": 2.00,
    "actual_amount": 98.00,
    "status": "审核中"
  }
}

8.4.2 获取提现记录

接口地址：ANY /api/user/getTx
功能描述：获取用户提现记录
请求参数： | 参数名 | 类型 | 必填 | 默认值 | 说明 | |--------|------|------|--------|------| | page | int | 否 | 1 | 页码 | | size | int | 否 | 10 | 每页数量 | | status | string | 否 | - | 状态筛选 |

响应示例：

{
  "code": 200,
  "msg": "获取成功",
  "data": [
    {
      "withdraw_id": "WD20250115001",
      "amount": 100.00,
      "fee": 2.00,
      "actual_amount": 98.00,
      "status": "已完成",
      "account_type": "支付宝",
      "account_info": "138****8000",
      "apply_time": "2025-01-15 10:00:00",
      "process_time": "2025-01-15 14:00:00"
    }
  ],
  "total": 5,
  "page": 1,
  "size": 10
}

8.4.3 余额转账

接口地址：ANY /api/user/transfer
功能描述：向其他用户转账余额
请求参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | to_username | string | 是 | 收款用户名 | | amount | decimal | 是 | 转账金额 | | remark | string | 否 | 转账备注 |

响应示例：

{
  "code": 200,
  "msg": "转账成功",
  "data": {
    "transfer_id": "TF20250115001",
    "from_username": "sender",
    "to_username": "receiver",
    "amount": 50.00,
    "balance": 50.50,
    "transfer_time": "2025-01-15 15:30:00"
  }
}

8.5 用户支付接口管理

8.5.1 获取用户支付接口列表

接口地址：ANY /api/user/getUserPayments
功能描述：获取用户配置的支付接口列表
请求参数：无
响应示例：

{
  "code": 200,
  "msg": "获取成功",
  "data": [
    {
      "id": 1,
      "name": "我的支付宝",
      "type": "alipay",
      "account": "138****8000",
      "status": 1,
      "default": true,
      "created_at": "2025-01-01 10:00:00"
    }
  ]
}

8.5.2 保存支付接口

接口地址：ANY /api/user/savePayment
功能描述：添加或编辑用户支付接口
请求参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | id | int | 否 | 编辑时传入，新增时不传 | | name | string | 是 | 支付接口名称 | | type | string | 是 | 支付类型：alipay/wechat | | account | string | 是 | 账户信息 | | config | string | 否 | 配置信息JSON |

响应示例：

{
  "code": 200,
  "msg": "保存成功",
  "data": {
    "id": 2,
    "name": "我的微信",
    "type": "wechat"
  }
}

8.5.3 删除支付接口

接口地址：ANY /api/user/deletePayment
功能描述：删除用户支付接口
请求参数： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | id | int | 是 | 支付接口ID |

响应示例：

{
  "code": 200,
  "msg": "删除成功"
}

九、其他说明

• 本文档主要基于路由入口与部分 Handler 源码整理，不保证涵盖所有历史兼容字段，如有特殊字段以实际返回 JSON 为准。
• 万能接口、二维码、价格计算等复杂模块已有专项文档，可在 go/docs 目录中查看：
  • 《万能接口配置说明.md》
  • 《二维码API文档.md》
  • 《价格计算逻辑问题分析.md》
  • 《商品类型与订单处理逻辑.md》

如需要，我可以进一步：

• 针对某一模块（例如"订单"、"支付"、"万能接口"）补齐详细字段表；
• 或者生成自动化提取路由 + 注释的工具，减少后续维护成本。