192
0
0
小氢云发卡系统模板开发教程
2026-02-02
文章摘要
|
接口文档
前台公共接口文档
本文档列出了系统中所有前台公共接口，包括接口地址、请求参数、响应示例和接口说明。
目录
系统配置接口
1. 获取系统配置
接口说明：获取系统基础配置信息，包括管理路径、应用名称、版本号等。
接口地址：GET /api/config
请求参数：无
响应示例：
{
"code": 200,
"msg": "操作成功",
"data": {
"admin_path": "/admin",
"app_name": "小氢云发卡系统",
"version": "1.0.0"
}
}{
"code": 200,
"msg": "操作成功",
"data": {
"admin_path": "/admin",
"app_name": "小氢云发卡系统",
"version": "1.0.0"
}
}字段说明：
admin_path: 管理端路径app_name: 应用名称version: 应用版本号
网站信息接口
2. 获取站点配置
接口说明：获取前台站点配置信息，包括 Logo、公告、联系方式等配置项。
接口地址：GET /api/home/config
请求参数：无
响应示例：
{
"code": 200,
"msg": "操作成功",
"data": {
"app_name": "小氢云发卡系统",
"version": "1.0.0",
"admin_path": "/admin",
"base_url": "https://example.com"
}
}{
"code": 200,
"msg": "操作成功",
"data": {
"app_name": "小氢云发卡系统",
"version": "1.0.0",
"admin_path": "/admin",
"base_url": "https://example.com"
}
}字段说明：
app_name: 应用名称version: 应用版本号admin_path: 管理端路径base_url: 基础URL
3. 获取网站信息
接口说明：获取网站所有配置信息，以 key-value 格式返回，包括网站名称、Logo、公告、联系方式等。
接口地址：GET /api/home/site-info
请求参数：无
响应示例：
{
"code": 200,
"msg": "操作成功",
"data": {
"site_title": "小氢云发卡系统",
"site_name": "小氢云发卡",
"site_keywords": "发卡系统,虚拟商品,自动发货",
"site_description": "专业的虚拟商品发卡系统，支持自动发货，安全可靠",
"site_notice": "<p>欢迎使用小氢云发卡系统！</p>",
"site_logo": "",
"last_login_ip": "",
"pc_template": "default",
"pe_template": "default"
}
}{
"code": 200,
"msg": "操作成功",
"data": {
"site_title": "小氢云发卡系统",
"site_name": "小氢云发卡",
"site_keywords": "发卡系统,虚拟商品,自动发货",
"site_description": "专业的虚拟商品发卡系统，支持自动发货，安全可靠",
"site_notice": "<p>欢迎使用小氢云发卡系统！</p>",
"site_logo": "",
"last_login_ip": "",
"pc_template": "default",
"pe_template": "default"
}
}重要说明（别再被示例误导）：
- 该接口返回的是
site_config表里 所有 配置项的key/value（map[string]string），字段数量 不是固定的。 - 你在后台「网站设置/模板/授权/支付渠道」等新增或更新了配置项，这里就会多返回对应的 key。
4. 获取支付渠道
接口说明：获取启用的支付渠道列表，返回各支付渠道的启用状态。
接口地址：GET /api/home/payment-channels
请求参数：无
响应示例：
{
"code": 200,
"msg": "操作成功",
"data": {
"alipay": true,
"wxpay": true,
"qqpay": false
}
}{
"code": 200,
"msg": "操作成功",
"data": {
"alipay": true,
"wxpay": true,
"qqpay": false
}
}说明：
alipay: 支付宝支付是否启用wxpay: 微信支付是否启用qqpay: QQ支付是否启用
重要说明：
- 这里的
qqpay只是“渠道开关”展示；当前后端下单与支付接口匹配逻辑里，payment_method仅支持alipay/wxpay（见PaymentInterfaceRepository.GetEnabledByPaymentMethod）。
分类接口
5. 获取分类列表
接口说明：获取所有启用的商品分类列表，用于前台展示分类导航。
接口地址：GET /api/home/category/list
请求参数：无（前台接口固定只返回启用的分类）
响应示例：
{
"code": 200,
"msg": "操作成功",
"data": [
{
"id": 1,
"name": "游戏点卡",
"image": "https://example.com/category1.jpg",
"sort": 1,
"status": 1,
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T12:00:00Z"
},
{
"id": 2,
"name": "会员充值",
"image": "",
"sort": 2,
"status": 1,
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T12:00:00Z"
}
]
}{
"code": 200,
"msg": "操作成功",
"data": [
{
"id": 1,
"name": "游戏点卡",
"image": "https://example.com/category1.jpg",
"sort": 1,
"status": 1,
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T12:00:00Z"
},
{
"id": 2,
"name": "会员充值",
"image": "",
"sort": 2,
"status": 1,
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T12:00:00Z"
}
]
}字段说明：
id: 分类ID（整数）name: 分类名称（字符串）image: 分类图片URL（字符串，可能为空字符串）sort: 排序值（整数），数字越小越靠前status: 状态（整数，1=启用，0=禁用）created_at: 创建时间（ISO 8601格式）updated_at: 更新时间（ISO 8601格式）
商品接口
6. 获取商品列表
接口说明：获取商品列表，支持分页、分类筛选、关键词搜索。前台接口固定只返回启用的商品。
接口地址：GET /api/home/goods/list
请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| page | int | 否 | 页码，默认1 |
| size | int | 否 | 每页数量，默认20 |
| category_id | int | 否 | 分类ID，筛选指定分类的商品 |
| name | string | 否 | 商品名称关键词，模糊搜索 |
请求示例：
GET /api/home/goods/list?page=1&size=20&category_id=1&name=点卡
响应示例：
{
"code": 200,
"msg": "操作成功",
"data": {
"list": [
{
"id": 1,
"category_id": 1,
"name": "王者荣耀点卡100元",
"image": "https://example.com/goods1.jpg",
"description": "王者荣耀点卡100元面值，可用于游戏内充值",
"price": "100.00",
"stock": 100,
"status": 1,
"sales": 50,
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T12:00:00Z"
},
{
"id": 2,
"category_id": 1,
"name": "和平精英点卡50元",
"image": "",
"description": "",
"price": "50.00",
"stock": 200,
"status": 1,
"sales": 30,
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T12:00:00Z"
}
],
"total": 100
}
}{
"code": 200,
"msg": "操作成功",
"data": {
"list": [
{
"id": 1,
"category_id": 1,
"name": "王者荣耀点卡100元",
"image": "https://example.com/goods1.jpg",
"description": "王者荣耀点卡100元面值，可用于游戏内充值",
"price": "100.00",
"stock": 100,
"status": 1,
"sales": 50,
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T12:00:00Z"
},
{
"id": 2,
"category_id": 1,
"name": "和平精英点卡50元",
"image": "",
"description": "",
"price": "50.00",
"stock": 200,
"status": 1,
"sales": 30,
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T12:00:00Z"
}
],
"total": 100
}
}字段说明：
id: 商品ID（整数）category_id: 分类ID（整数）name: 商品名称（字符串）image: 商品图片URL（字符串，可能为空字符串）description: 商品描述（字符串，可能为空字符串）price: 商品价格（字符串格式，保留两位小数）stock: 库存数量（整数，实际卡密库存）status: 状态（整数，1=启用，0=禁用）sales: 已售数量（整数）created_at: 创建时间（ISO 8601格式）updated_at: 更新时间（ISO 8601格式）total: 总记录数（整数）
7. 获取商品详情
接口说明：根据商品 ID 获取商品详细信息，包括商品描述、价格、库存等。
接口地址：GET /api/home/goods/:id
请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | int | 是 | 商品ID（路径参数） |
请求示例：
GET /api/home/goods/1
响应示例：
{
"code": 200,
"msg": "操作成功",
"data": {
"id": 1,
"category_id": 1,
"name": "王者荣耀点卡100元",
"image": "https://example.com/goods1.jpg",
"description": "<p>王者荣耀点卡100元面值，可用于游戏内充值</p><p>支持多种支付方式，安全可靠</p>",
"price": "100.00",
"stock": 100,
"status": 1,
"sales": 50,
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T12:00:00Z"
}
}{
"code": 200,
"msg": "操作成功",
"data": {
"id": 1,
"category_id": 1,
"name": "王者荣耀点卡100元",
"image": "https://example.com/goods1.jpg",
"description": "<p>王者荣耀点卡100元面值，可用于游戏内充值</p><p>支持多种支付方式，安全可靠</p>",
"price": "100.00",
"stock": 100,
"status": 1,
"sales": 50,
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T12:00:00Z"
}
}字段说明：
id: 商品IDcategory_id: 分类IDname: 商品名称image: 商品图片URL（可能为空字符串）description: 商品描述（HTML格式，可能为空字符串）price: 商品价格（字符串格式，保留两位小数）stock: 库存数量（实际卡密库存，整数）status: 状态（1=启用，0=禁用）sales: 已售数量（整数）created_at: 创建时间（ISO 8601格式）updated_at: 更新时间（ISO 8601格式）
错误响应：
- 商品不存在：
{"code": 404, "msg": "商品不存在"} - 商品已下架：
{"code": 404, "msg": "商品已下架"}
订单接口
8. 创建订单
接口说明：创建订单，如果商品支持自动发卡且库存充足，会直接返回成功；否则返回支付 URL，需要跳转到支付页面完成支付。
接口地址：POST /api/home/order/create
请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| goods_id | int | 是 | 商品ID |
| quantity | int | 是 | 购买数量 |
| contact_info | string | 否 | 联系方式（邮箱/QQ等），用于接收卡密 |
| payment_method | string | 否 | 支付方式：alipay（支付宝） / wxpay（微信支付）。注意：当前不支持 qqpay 作为下单支付方式 |
请求示例：
{
"goods_id": 1,
"quantity": 2,
"contact_info": "user@example.com",
"payment_method": "alipay"
}{
"goods_id": 1,
"quantity": 2,
"contact_info": "user@example.com",
"payment_method": "alipay"
}响应示例（需要支付）：
{
"code": 201,
"msg": "订单创建成功，请前往支付",
"url": "https://example.com/api/home/payment/ORD1234567890123456789",
"data": {
"id": 1,
"order_no": "ORD1234567890123456789",
"goods_id": 1,
"quantity": 2,
"total_price": "200.00",
"status": "pending",
"contact_info": {
"String": "user@example.com",
"Valid": true
},
"payment_method": {
"String": "alipay",
"Valid": true
},
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T12:00:00Z"
}
}{
"code": 201,
"msg": "订单创建成功，请前往支付",
"url": "https://example.com/api/home/payment/ORD1234567890123456789",
"data": {
"id": 1,
"order_no": "ORD1234567890123456789",
"goods_id": 1,
"quantity": 2,
"total_price": "200.00",
"status": "pending",
"contact_info": {
"String": "user@example.com",
"Valid": true
},
"payment_method": {
"String": "alipay",
"Valid": true
},
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T12:00:00Z"
}
}响应示例（免费商品自动发卡成功）：
{
"code": 200,
"msg": "订单创建成功，卡密已发送至您的邮箱",
"data": {
"id": 1,
"order_no": "ORD1234567890123456789",
"goods_id": 1,
"quantity": 2,
"total_price": "0.00",
"status": "sent",
"contact_info": {
"String": "user@example.com",
"Valid": true
},
"payment_method": {
"String": "",
"Valid": false
},
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T12:00:00Z"
}
}{
"code": 200,
"msg": "订单创建成功，卡密已发送至您的邮箱",
"data": {
"id": 1,
"order_no": "ORD1234567890123456789",
"goods_id": 1,
"quantity": 2,
"total_price": "0.00",
"status": "sent",
"contact_info": {
"String": "user@example.com",
"Valid": true
},
"payment_method": {
"String": "",
"Valid": false
},
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T12:00:00Z"
}
}字段说明：
id: 订单IDorder_no: 订单号goods_id: 商品IDquantity: 购买数量total_price: 订单总价（字符串格式，保留两位小数）status: 订单状态（pending=待支付，paid=已支付待发卡，sent=已发卡，cancelled=已取消）contact_info: 联系方式（对象，结构为{"String": "...", "Valid": true/false}，来自database/sql.NullString的默认JSON序列化）payment_method: 支付方式（对象，结构为{"String": "alipay|wxpay", "Valid": true/false}）created_at: 创建时间（ISO 8601格式）updated_at: 更新时间（ISO 8601格式）
说明：
code=200: 订单创建成功，卡密已自动发放（如果支持自动发卡）code=201: 订单创建成功，需要跳转到支付页面完成支付url: 支付页面URL（仅在code=201时返回；后端会把相对路径补全为绝对地址）status: 订单状态（pending=待支付，paid=已支付待发卡，sent=已发卡，cancelled=已取消）- HTTP状态码：当
code=201时，HTTP 状态码也会返回 201；其它情况为 200
9. 查询订单
接口说明：根据订单号或联系方式查询订单信息，如果订单已发货，会返回卡密信息。不返回待支付（pending）状态的订单。
接口地址：GET /api/home/order/query
请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| order_no | string | 否 | 订单号（与contact_info至少填一个） |
| contact_info | string | 否 | 联系方式（与order_no至少填一个） |
| page | int | 否 | 页码，默认1 |
| size | int | 否 | 每页数量，默认20 |
请求示例：
GET /api/home/order/query?order_no=ORDER20240101001
或
GET /api/home/order/query?contact_info=user@example.com&page=1&size=20
响应示例：
{
"code": 200,
"msg": "操作成功",
"data": [
{
"id": 1,
"order_no": "ORD1234567890123456789",
"goods_id": 1,
"quantity": 2,
"total_price": "200.00",
"status": "sent",
"contact_info": "user@example.com",
"created_at": "2024-01-01T12:00:00Z",
"cards": [
"CARD001 PASSWORD001",
"CARD002 PASSWORD002"
]
},
{
"id": 2,
"order_no": "ORD1234567890123456790",
"goods_id": 2,
"quantity": 1,
"total_price": "100.00",
"status": "paid",
"contact_info": "user2@example.com",
"created_at": "2024-01-01T13:00:00Z"
}
]
}{
"code": 200,
"msg": "操作成功",
"data": [
{
"id": 1,
"order_no": "ORD1234567890123456789",
"goods_id": 1,
"quantity": 2,
"total_price": "200.00",
"status": "sent",
"contact_info": "user@example.com",
"created_at": "2024-01-01T12:00:00Z",
"cards": [
"CARD001 PASSWORD001",
"CARD002 PASSWORD002"
]
},
{
"id": 2,
"order_no": "ORD1234567890123456790",
"goods_id": 2,
"quantity": 1,
"total_price": "100.00",
"status": "paid",
"contact_info": "user2@example.com",
"created_at": "2024-01-01T13:00:00Z"
}
]
}字段说明：
id: 订单IDorder_no: 订单号goods_id: 商品IDquantity: 购买数量total_price: 订单总价（字符串格式，保留两位小数）status: 订单状态（paid=已支付待发卡，sent=已发卡，cancelled=已取消）contact_info: 联系方式（字符串，可能为空字符串）created_at: 创建时间（ISO 8601格式）cards: 卡密列表（仅在status=sent时返回，格式：卡号 密码，多个卡密用数组返回。如果卡密没有密码，则只返回卡号）
错误响应：
- 参数错误：
{"code": 400, "msg": "请输入订单号或联系方式"}
支付接口
10. 支付页面
接口说明：获取支付页面 HTML，自动提交支付表单到支付平台。此接口返回 HTML 页面，不是 JSON 格式。
接口地址：GET /api/home/payment/:order_no
请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| order_no | string | 是 | 订单号（路径参数） |
请求示例：
GET /api/home/payment/ORDER20240101001
响应：返回 HTML 页面，自动跳转到支付平台
错误响应：
- 订单不存在：返回文本 "订单不存在"
- 订单状态不正确：返回文本 "订单状态不正确"
- 订单未指定支付方式：返回文本 "订单未指定支付方式"
- 支付接口未配置：返回文本 "支付接口未配置或未启用"
11. 支付回调（兼容旧路径）
接口说明：支付平台回调接口，兼容旧路径。支持 GET 和 POST 请求。
接口地址：ANY /api/payment/callback
请求参数：由支付平台传递，不同支付平台参数不同
响应：
- 成功：返回文本 "success"
- 失败：返回文本 "fail"
说明：此接口由支付平台调用，不需要前端调用。
12. 支付异步通知
接口说明：支付平台异步回调接口（服务器回调），用于接收支付结果通知。
接口地址：ANY /api/payment/notify
请求参数：由支付平台传递，不同支付平台参数不同
响应：
- 成功：返回文本 "success"
- 失败：返回文本 "fail"
说明：此接口由支付平台服务器调用，不需要前端调用。
13. 支付同步返回
接口说明：支付平台同步回调接口（用户浏览器回跳），支付完成后跳转回本站，展示支付结果和卡密信息。
接口地址：ANY /api/payment/return
请求参数：由支付平台传递，不同支付平台参数不同
响应：返回 HTML 页面，展示支付结果和卡密信息（如果已发卡）
说明：此接口由支付平台在用户支付完成后跳转调用，不需要前端主动调用。
14. 支付同步验证
接口说明：同步验证订单支付状态，用于前端轮询查询订单是否已支付。
接口地址：GET /api/user/getPay2
请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| order_no | string | 是 | 订单号 |
请求示例：
GET /api/user/getPay2?order_no=ORDER20240101001
响应示例（已支付）：
{
"code": 200,
"msg": "操作成功",
"data": {
"order_no": "ORD1234567890123456789",
"status": "paid",
"paid": true
}
}{
"code": 200,
"msg": "操作成功",
"data": {
"order_no": "ORD1234567890123456789",
"status": "paid",
"paid": true
}
}响应示例（待支付）：
{
"code": 200,
"msg": "操作成功",
"data": {
"order_no": "ORD1234567890123456789",
"status": "pending",
"paid": false,
"message": "订单状态查询完成"
}
}{
"code": 200,
"msg": "操作成功",
"data": {
"order_no": "ORD1234567890123456789",
"status": "pending",
"paid": false,
"message": "订单状态查询完成"
}
}响应示例（已发卡）：
{
"code": 200,
"msg": "操作成功",
"data": {
"order_no": "ORD1234567890123456789",
"status": "sent",
"paid": true
}
}{
"code": 200,
"msg": "操作成功",
"data": {
"order_no": "ORD1234567890123456789",
"status": "sent",
"paid": true
}
}字段说明：
order_no: 订单号status: 订单状态（pending=待支付，paid=已支付待发卡，sent=已发卡）paid: 是否已支付（布尔值）message: 提示信息（仅在待支付时返回）
产品版本接口
15. 获取产品版本列表
接口说明：获取产品版本列表（更新日志），代理到授权站获取。
接口地址：GET /api/frontend/product-versions
请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| product_id | int | 否 | 产品ID（后端强制设置为3，忽略前端传递的值） |
| page | int | 否 | 页码 |
| size | int | 否 | 每页数量 |
请求示例：
GET /api/frontend/product-versions?page=1&size=20
响应示例（有分页信息）：
{
"code": 200,
"msg": "操作成功",
"data": [],
"total": 10,
"page": 1,
"size": 20
}{
"code": 200,
"msg": "操作成功",
"data": [],
"total": 10,
"page": 1,
"size": 20
}响应示例（无分页信息）：
{
"code": 200,
"msg": "操作成功",
"data": []
}{
"code": 200,
"msg": "操作成功",
"data": []
}说明：
- 此接口会代理到授权站获取数据，如果授权站返回
code=1，本站会转换为code=200。 data内部字段 完全以授权站返回为准（本站不定义版本项的字段模型；这里只保证外层包装结构与分页字段）。
节点管理接口
16. 获取公共节点列表
接口说明：获取所有可用节点列表（登录前使用），包含节点连接状态和延迟信息。
接口地址：GET /api/admin/getPublicNodeList
请求参数：无
响应示例：
{
"code": 200,
"msg": "操作成功",
"data": [
{
"id": 1,
"name": "节点1",
"location": "北京",
"url": "https://node1.example.com",
"status": 1,
"ping": 50
},
{
"id": 2,
"name": "节点2",
"location": "上海",
"url": "https://node2.example.com",
"status": 1,
"ping": 80
}
]
}{
"code": 200,
"msg": "操作成功",
"data": [
{
"id": 1,
"name": "节点1",
"location": "北京",
"url": "https://node1.example.com",
"status": 1,
"ping": 50
},
{
"id": 2,
"name": "节点2",
"location": "上海",
"url": "https://node2.example.com",
"status": 1,
"ping": 80
}
]
}字段说明：
id: 节点IDname: 节点名称location: 节点位置url: 节点URLstatus: 节点状态（1=可用，0=不可用）ping: 延迟（毫秒）
17. 获取当前公共节点
接口说明：获取当前使用的节点信息（登录前使用）。
接口地址：GET /api/admin/getPublicCurrentNode
请求参数：无
响应示例：
{
"code": 200,
"msg": "操作成功",
"data": {
"id": 1,
"name": "节点1",
"location": "北京",
"url": "https://node1.example.com",
"status": 1,
"ping": 50
}
}{
"code": 200,
"msg": "操作成功",
"data": {
"id": 1,
"name": "节点1",
"location": "北京",
"url": "https://node1.example.com",
"status": 1,
"ping": 50
}
}错误响应：
- 没有可用节点：
{"code": 500, "msg": "没有可用的节点"}
18. 切换公共节点
接口说明：切换当前使用的节点（登录前使用）。
接口地址：POST /api/admin/switchPublicNode
请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| node_id | int | 是 | 节点ID |
请求示例：
{
"node_id": 2
}{
"node_id": 2
}响应示例：
{
"code": 200,
"msg": "切换节点成功",
"data": null
}{
"code": 200,
"msg": "切换节点成功",
"data": null
}错误响应：
- 节点不存在：
{"code": 400, "msg": "节点不存在"} - 切换失败：
{"code": 500, "msg": "切换节点失败: xxx"}
通用响应格式
所有接口统一使用以下响应格式：
成功响应
{
"code": 200,
"msg": "操作成功",
"data": {}
}{
"code": 200,
"msg": "操作成功",
"data": {}
}分页响应
{
"code": 200,
"msg": "操作成功",
"data": [],
"total": 100,
"page": 1,
"size": 20
}{
"code": 200,
"msg": "操作成功",
"data": [],
"total": 100,
"page": 1,
"size": 20
}错误响应
{
"code": 400,
"msg": "错误信息"
}{
"code": 400,
"msg": "错误信息"
}状态码说明：
200: 操作成功201: 创建成功（需要支付）400: 请求参数错误404: 资源不存在500: 服务器内部错误407: 授权密钥未配置 / 授权校验失败（LicenseAuth中间件拦截）409: 体验授权过期（LicenseAuth中间件拦截）401: 未登录（管理端接口常见）403: 无权限访问（如图片预览越权）
HTTP 状态码说明（很关键）：
- 本项目大多数 JSON 接口 无论成功/失败，HTTP 都返回 200，真正的业务状态看 JSON 里的
code（见pkg/response/response.go）。 - 例外：
POST /api/home/order/create：当返回体code=201时，HTTP 也会返回 201GET /health：不是统一响应结构（直接{status,time}）GET /api/home/payment/:order_no：返回 HTML（不是 JSON）ANY /api/payment/*：返回纯文本success/fail（不是 JSON）
其他公共接口（补充：非“前台业务API”但同样公开）
A1. 健康检查
接口说明：服务存活检测（无统一包装）。
接口地址：GET /health
请求参数：无
响应示例：
{
"status": "ok",
"time": "2026-02-01T12:00:00+08:00"
}{
"status": "ok",
"time": "2026-02-01T12:00:00+08:00"
}A2. 获取管理员登录验证码图片
接口说明：返回验证码 PNG 图片流（不是 JSON）。
接口地址：GET /api/admin/getLoginCode
请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| type | string | 否 | 验证码类型（默认 adminLogin），用于区分存储key |
响应：image/png 二进制图片
A3. 图片预览（管理端上传图片回显）
接口说明：通过安全校验后返回图片文件流（不是 JSON）。
接口地址：GET /api/admin/upload/preview
请求参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| path | string | 是 | 上传后返回的相对路径（文件名） |
响应：image/jpeg / image/png / image/webp 等二进制图片
A4. 前台静态资源（模板资源）
接口说明：按当前模板配置动态读取并返回前台静态资源文件（不是 JSON）。
接口地址：
GET /assets/pc/*filepathGET /assets/pe/*filepath
请求参数：路径参数 filepath（如：/assets/pc/assets/index-xxxx.js）
响应：对应文件内容（Content-Type 按扩展名推断）
A5. 前台首页
接口说明：根据 User-Agent 判断 PC/ 移动端，返回对应模板的 index.html（不是 JSON）。
接口地址：GET /
请求参数：无
响应：text/html; charset=utf-8
注意事项
认证要求：所有前台公共接口都不需要登录认证，但部分接口需要 License 授权（通过 LicenseAuth 中间件）。
访问统计：
/api/home/*和/api/config接口会自动统计访问量（PV）。支付回调：支付相关回调接口由支付平台调用，前端不需要主动调用。
订单查询：查询订单接口不会返回待支付（pending）状态的订单，只返回已支付或已发货的订单。
卡密显示：卡密信息仅在订单已发货（status=sent）时返回，且卡密已通过邮箱发送，页面不再显示卡密内容。
商品库存：商品详情接口返回的库存是实际卡密库存，不是商品配置的库存。
支付方式：创建订单时如果不指定支付方式，系统会根据配置自动选择或要求用户选择。
节点管理：节点管理接口分为公共接口（登录前）和管理接口（登录后），公共接口返回完整的节点信息包括 URL。
更新日志
- 2024-01-01: 初始版本，包含所有前台公共接口文档
开发教程
你可以直接把文档喂给 AI 或使用 f12 抓包接口
该系统比较简单，模板功能比较少。
模板开发手机端可以使用 vue3，打包成单页项目：index.html、assets。
把打包好的模板放进 public/template/pc 或 pe 目录中，然后再创建一个 config.json 文件，里面存放的是模板的信息
模板配置文件说明
config.json 字段说明
每个模板目录下必须包含一个 config.json 文件，用于描述模板的基本信息。
配置字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
version |
string | ✅ | 模板版本号，建议使用语义化版本号（如：1.0.0） |
name |
string | ✅ | 模板名称，必须与模板目录名一致（如：default、jingfaka） |
display_name |
string | ✅ | 在管理后台显示的模板名称 |
description |
string | ✅ | 模板描述信息，用于说明模板的特点和功能 |
author |
string | ⭕ | 模板作者或开发团队（可选） |
homepage |
string | ⭕ | 模板主页或文档链接（可选，留空表示无） |
thumbnail |
string | ⭕ | 模板缩略图路径，相对于模板目录（可选，留空表示无） |
配置示例
{
"version": "1.0.0",
"name": "default",
"display_name": "默认PC模板",
"description": "小氢云发卡系统默认PC端模板，采用现代化设计风格，支持响应式布局，适配各种屏幕尺寸",
"author": "小氢云团队",
"homepage": "",
"thumbnail": ""
}{
"version": "1.0.0",
"name": "default",
"display_name": "默认PC模板",
"description": "小氢云发卡系统默认PC端模板，采用现代化设计风格，支持响应式布局，适配各种屏幕尺寸",
"author": "小氢云团队",
"homepage": "",
"thumbnail": ""
}注意事项
- JSON 格式：配置文件必须使用标准 JSON 格式，不支持注释
- name 字段：必须与模板目录名完全一致
- 路径说明：
thumbnail路径相对于模板根目录，例如：thumbnail.png表示模板目录下的thumbnail.png文件 - 版本号：建议使用语义化版本号（Semantic Versioning），格式：
主版本号.次版本号.修订号