主题
24 产品接口文档
全量接口清单，按应用归类。通用约定见 12 API与路由，错误码见 27 错误码大全。
通用约定
- 路径：
/{app}/{控制器}/{动作}（控制器名转蛇形，如ThemeTpl→theme_tpl） - 响应：
{ "status": 200, "msg": "...", "data": ... } - 鉴权：需登录的接口带
Authorization: Bearer <JWT>（开放 API 兼容JWT <token>） - 列表分页：
data: { list: [], total: N }
一、前台公开接口（/home，无需登录）
Content 内容
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /home/content/siteConfig | 站点 + 主题 bundle（站名、导航、SEO、主题配置） |
| GET | /home/content/maintenance | 维护公告 |
| GET | /home/content/affClick | 推广链接点击记录 |
| GET | /home/content/banners | 轮播图 |
| GET | /home/content/announcements | 公告列表 |
| GET | /home/content/announcement?id= | 公告详情 |
| GET | /home/content/kb | 知识库分类+文章树 |
| GET | /home/content/kbArticle?id= | 知识库文章详情 |
Store 商店
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /home/store/catalog | 商品组树 + 商品 + 最低价 |
| GET | /home/store/group?id= | 单商品组及其商品 |
| GET | /home/store/product?id= | 商品详情（定价 + 可配置选项；上游商品可能返回跳转） |
| GET | /home/store/redirect?id= | 上游代理商品 301 跳转 |
主题 SSR（魔方 .tpl）
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /tpl/home、/tpl/cart | 美化路由，转发到 theme_tpl/page |
| GET | /home/theme_tpl/render?type=&page= | 渲染指定模板（HTML 或 format=json） |
| GET | /home/theme_tpl/page?path= | SSR 首页/购物车入口 |
二、会员中心接口（/home，需登录）
鉴权：
UserAuth中间件校验Authorization: Bearer <JWT>（type=user）。
Auth 账户
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /home/auth/register | 注册 |
| POST | /home/auth/login | 登录换 JWT |
| GET | /home/auth/me | 当前用户信息 |
| POST | /home/auth/logout | 登出 |
| POST | /home/auth/realname | 提交实名认证 |
| GET | /home/auth/realnameQuery | 查询实名结果 |
Console 控制台
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /home/console/summary | 概览统计 |
| GET | /home/console/services | 我的服务实例列表 |
| GET | /home/console/service?id= | 服务实例详情 |
| GET | /home/console/invoices | 我的账单 |
| POST | /home/console/updateProfile | 修改资料 |
| POST | /home/console/changePassword | 修改密码 |
Order 下单
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /home/order/create | 创建订单（生成账单） |
| POST | /home/order/checkPromo | 校验优惠码 |
| GET | /home/order/index | 我的订单 |
Invoice 账单 / 支付
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /home/invoice/read?id= | 账单详情 |
| GET | /home/invoice/methods | 可用支付方式 |
| POST | /home/invoice/pay | 发起在线支付 |
| POST | /home/invoice/payCredit | 余额支付 |
| GET | /home/invoice/status?id= | 支付状态轮询 |
Ticket 工单
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /home/ticket/departments | 工单部门 |
| GET | /home/ticket/index | 工单列表 |
| POST | /home/ticket/create | 新建工单 |
| GET | /home/ticket/read?id= | 工单详情 |
| POST | /home/ticket/reply | 回复工单 |
| POST | /home/ticket/close | 关闭工单 |
Affiliate 推广
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /home/affiliate/index | 推广概况 |
| GET | /home/affiliate/commissions | 佣金明细 |
| POST | /home/affiliate/withdraw | 申请提现 |
| GET | /home/affiliate/withdrawals | 提现记录 |
三、开放 API v1（/api/v1，上下游对接）
供下游系统代理本系统商品。下游用「本系统账号 + API 密钥」换 JWT（2 小时），后续请求带 Authorization: JWT <token>（兼容 Bearer）。下单计入该账号名下并用账号余额实时结算。
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/v1/login | username + password(API密钥) → JWT（含 IP 白名单校验） |
| GET | /api/v1/products | 商品目录 |
| GET | /api/v1/productsconfig?id= | 商品详情（可配置选项 + 定价） |
| POST | /api/v1/order | 下单并用余额结算，返回开通凭据 |
| GET | /api/v1/host?id= | 服务实例详情（状态轮询/凭据） |
| POST | /api/v1/renew?id= | 续费并用余额结算 |
| GET | /api/v1/credit | 余额查询 |
示例：登录 + 下单
bash
# 1. 换取 JWT
curl -X POST https://你的域名/api/v1/login \
-d "username=downstream@x.com&password=<API密钥>"
# → { "status":200, "data": { "jwt":"...", "expire":7200 } }
# 2. 下单（余额结算）
curl -X POST https://你的域名/api/v1/order \
-H "Authorization: JWT <jwt>" \
-d "product_id=18&billing_cycle=monthly&qty=1"
# → { "status":200, "data": { "order_num":"...","hosts":[{...凭据}] } }API 密钥在后台 上下游 → API 密钥（/admin/api_key/*）管理，可设 IP 白名单。
四、支付回调（/api）
| 方法 | 路径 | 说明 |
|---|---|---|
| POST/GET | /api/notify/callback?gateway=<网关name> | 支付异步回调，PaymentService::handleNotify() 验签 |
| GET | /api/notify/sync?gateway=&invoice= | 支付同步跳回 |
| GET | /api/index/health | 探活（系统信息 + healthy） |
五、后台接口
后台接口数量较多，按权限模块组织，操作语义见 25 管理员操作文档。统一前缀 /admin/{控制器}/{动作}，需 AdminAuth + 模块权限。常见模式：index（列表）、read（详情）、create/update/delete（增改删）。
下一篇：25 管理员操作文档