-- 扩展API文档初始化脚本 -- 运行方式: 在项目根目录执行 go run cmd/scripts/init_extension_docs.go -- 首先创建扩展API文档分类 INSERT INTO doc_categories (name, slug, description, icon, status, sort, created_at, updated_at) VALUES ('扩展API', 'extension-api', '开放API文档，供开发者在自己的服务器集成平台功能', 'code', 'active', 100, datetime('now'), datetime('now')); -- 概述文档 INSERT INTO docs (category_id, title, slug, content, status, sort, created_at, updated_at) VALUES ( (SELECT id FROM doc_categories WHERE slug = 'extension-api'), '扩展API概述', 'extension-api-overview', '# 扩展API概述 扩展API允许开发者在自己的服务器上集成平台功能，实现自定义的业务逻辑。 ## 功能特点 - **用户管理**: 查询用户信息、充值、扣费等操作 - **卡密管理**: 查询卡密、生成卡密 - **消息通知**: 向用户发送通知消息 - **应用管理**: 获取应用信息和统计数据 - **云端变量**: 读写用户和应用级别的云端变量 ## 认证方式 所有API请求需要进行签名认证，请求头需要包含以下字段： | 字段 | 说明 | |------|------| | X-Access-Key | API密钥的Access Key | | X-Signature | 请求签名 | | X-Timestamp | 请求时间戳（秒级） | ## 签名算法 签名生成步骤： 1. 拼接签名字符串: `METHOD + PATH + TIMESTAMP + BODY` 2. 使用Secret Key对签名字符串进行HMAC-SHA256签名 3. 将签名结果转换为十六进制字符串 ```javascript // JavaScript示例 const crypto = require(''crypto''); function generateSignature(method, path, timestamp, body, secretKey) { const stringToSign = method + path + timestamp + body; const hmac = crypto.createHmac(''sha256'', secretKey); hmac.update(stringToSign); return hmac.digest(''hex''); } ``` ## 请求限制 - 时间戳有效期：5分钟 - 请求频率：根据套餐限制 ## 创建API密钥 1. 进入「扩展配置」页面 2. 切换到「API密钥」标签 3. 点击「创建密钥」按钮 4. 选择应用并配置权限 5. 保存Access Key和Secret Key > ⚠️ **注意**: Secret Key只在创建时显示一次，请妥善保存！ ', 'published', 1, datetime('now'), datetime('now') ); -- 用户管理API文档 INSERT INTO docs (category_id, title, slug, content, status, sort, created_at, updated_at) VALUES ( (SELECT id FROM doc_categories WHERE slug = 'extension-api'), '用户管理', 'extension-api-user', '# 用户管理 ## 获取用户信息 获取指定用户的详细信息。 ### 请求 ``` GET /api/v1/ext/user/:userId ``` ### 请求头 | 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | X-Access-Key | string | 是 | Access Key | | X-Signature | string | 是 | 请求签名 | | X-Timestamp | string | 是 | 时间戳 | ### 响应示例 ```json { "code": 200, "message": "success", "data": { "id": 1, "username": "testuser", "email": "test@example.com", "status": "active", "balance": 100.00, "expiry_at": "2024-12-31T23:59:59Z", "last_login_at": "2024-01-15T10:30:00Z", "is_trial_user": false, "created_at": "2024-01-01T00:00:00Z" } } ``` --- ## 获取用户列表 获取应用下的用户列表。 ### 请求 ``` GET /api/v1/ext/users ``` ### 查询参数 | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | page | int | 否 | 页码，默认1 | | page_size | int | 否 | 每页数量，默认20 | | status | string | 否 | 状态筛选 | | search | string | 否 | 搜索关键词 | ### 响应示例 ```json { "code": 200, "message": "success", "data": { "users": [...], "total": 100, "page": 1, "page_size": 20, "total_page": 5 } } ``` --- ## 用户充值 为用户充值时长或余额。 ### 请求 ``` POST /api/v1/ext/user/:userId/recharge ``` ### 请求体 ```json { "amount": 100, "type": "days", "description": "在线充值" } ``` | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | amount | int | 是 | 充值数量 | | type | string | 是 | 类型：days（天数）或 balance（余额） | | description | string | 否 | 描述说明 | ### 响应示例 ```json { "code": 200, "message": "success", "data": { "message": "充值成功", "user": { "id": 1, "balance": 100.00, "expiry_at": "2024-12-31T23:59:59Z" } } } ``` --- ## 用户扣费 扣除用户余额或时长。 ### 请求 ``` POST /api/v1/ext/user/:userId/deduct ``` ### 请求体 ```json { "amount": 50, "type": "balance", "description": "消费扣费" } ``` | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | amount | int | 是 | 扣除数量 | | type | string | 是 | 类型：days（天数）或 balance（余额） | | description | string | 否 | 描述说明 | ### 响应示例 ```json { "code": 200, "message": "success", "data": { "message": "扣除成功", "user": { "id": 1, "balance": 50.00 } } } ``` --- ## 获取用户变量 获取用户的云端变量。 ### 请求 ``` GET /api/v1/ext/user/:userId/variables ``` ### 响应示例 ```json { "code": 200, "message": "success", "data": { "vip_level": { "value": "3", "scope": "user" }, "game_score": { "value": "1000", "scope": "user" } } } ``` --- ## 更新用户变量 更新用户的云端变量。 ### 请求 ``` POST /api/v1/ext/user/:userId/variables ``` ### 请求体 ```json { "variables": { "vip_level": "5", "game_score": "2000" } } ``` ### 响应示例 ```json { "code": 200, "message": "success", "data": { "message": "更新成功" } } ``` ', 'published', 2, datetime('now'), datetime('now') ); -- 卡密管理API文档 INSERT INTO docs (category_id, title, slug, content, status, sort, created_at, updated_at) VALUES ( (SELECT id FROM doc_categories WHERE slug = 'extension-api'), '卡密管理', 'extension-api-card', '# 卡密管理 ## 获取卡密列表 获取应用下的卡密列表。 ### 请求 ``` GET /api/v1/ext/cards ``` ### 查询参数 | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | page | int | 否 | 页码，默认1 | | page_size | int | 否 | 每页数量，默认20 | | status | string | 否 | 状态筛选：unused/used/disabled | | card_type_id | int | 否 | 卡密类型ID | ### 响应示例 ```json { "code": 200, "message": "success", "data": { "cards": [ { "id": 1, "card_key": "ABCD1234EFGH5678", "card_type_id": 1, "status": "unused", "created_at": "2024-01-01T00:00:00Z" } ], "total": 100, "page": 1, "page_size": 20, "total_page": 5 } } ``` --- ## 生成卡密 批量生成卡密。 ### 请求 ``` POST /api/v1/ext/cards/generate ``` ### 请求体 ```json { "card_type_id": 1, "count": 10 } ``` | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | card_type_id | int | 是 | 卡密类型ID | | count | int | 是 | 生成数量 | ### 响应示例 ```json { "code": 200, "message": "success", "data": { "message": "生成成功", "count": 10, "cards": [ { "id": 1, "card_key": "ABCD1234EFGH5678", "status": "unused" } ] } } ``` --- ## 获取卡密详情 获取单个卡密的详细信息。 ### 请求 ``` GET /api/v1/ext/card/:cardId ``` ### 响应示例 ```json { "code": 200, "message": "success", "data": { "id": 1, "card_key": "ABCD1234EFGH5678", "card_type_id": 1, "status": "unused", "used_at": null, "app_user_id": null, "created_at": "2024-01-01T00:00:00Z" } } ``` ', 'published', 3, datetime('now'), datetime('now') ); -- 消息通知API文档 INSERT INTO docs (category_id, title, slug, content, status, sort, created_at, updated_at) VALUES ( (SELECT id FROM doc_categories WHERE slug = 'extension-api'), '消息通知', 'extension-api-notification', '# 消息通知 ## 发送单个通知 向指定用户发送通知消息。 ### 请求 ``` POST /api/v1/ext/notification ``` ### 请求体 ```json { "user_id": 1, "title": "系统通知", "content": "您的账户已充值成功！", "type": "info" } ``` | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | user_id | int | 是 | 用户ID | | title | string | 是 | 通知标题 | | content | string | 是 | 通知内容 | | type | string | 否 | 类型：info/warning/error | ### 响应示例 ```json { "code": 200, "message": "success", "data": { "message": "发送成功", "notification": { "id": 1, "title": "系统通知", "content": "您的账户已充值成功！" } } } ``` --- ## 批量发送通知 向所有用户发送通知消息。 ### 请求 ``` POST /api/v1/ext/notification/batch ``` ### 请求体 ```json { "title": "系统公告", "content": "系统将于今晚进行维护...", "type": "warning" } ``` ### 响应示例 ```json { "code": 200, "message": "success", "data": { "message": "发送成功", "notification": { "id": 1, "title": "系统公告", "content": "系统将于今晚进行维护..." } } } ``` ', 'published', 4, datetime('now'), datetime('now') ); -- 应用管理API文档 INSERT INTO docs (category_id, title, slug, content, status, sort, created_at, updated_at) VALUES ( (SELECT id FROM doc_categories WHERE slug = 'extension-api'), '应用管理', 'extension-api-app', '# 应用管理 ## 获取应用信息 获取当前应用的基本信息。 ### 请求 ``` GET /api/v1/ext/app/info ``` ### 响应示例 ```json { "code": 200, "message": "success", "data": { "id": 1, "name": "我的应用", "description": "应用描述", "billing_type": "subscription", "encrypt_type": "aes", "bind_type": "device", "max_devices": 3, "multi_open": false, "enable_trial": true, "trial_balance": 7, "status": "active", "created_at": "2024-01-01T00:00:00Z" } } ``` --- ## 获取应用统计 获取应用的统计数据。 ### 请求 ``` GET /api/v1/ext/app/stats ``` ### 响应示例 ```json { "code": 200, "message": "success", "data": { "user_count": 1000, "active_user_count": 500, "card_count": 200, "used_card_count": 150 } } ``` --- ## 获取应用变量 获取应用级别的云端变量。 ### 请求 ``` GET /api/v1/ext/app/variables ``` ### 响应示例 ```json { "code": 200, "message": "success", "data": { "app_version": "1.0.0", "maintenance_mode": "false", "announcement": "欢迎使用本应用" } } ``` --- ## 更新应用变量 更新应用级别的云端变量。 ### 请求 ``` POST /api/v1/ext/app/variables ``` ### 请求体 ```json { "variables": { "app_version": "1.0.1", "maintenance_mode": "true", "announcement": "系统维护中，请稍后..." } } ``` ### 响应示例 ```json { "code": 200, "message": "success", "data": { "message": "更新成功" } } ``` ', 'published', 5, datetime('now'), datetime('now') ); -- 代码示例文档 INSERT INTO docs (category_id, title, slug, content, status, sort, created_at, updated_at) VALUES ( (SELECT id FROM doc_categories WHERE slug = 'extension-api'), '代码示例', 'extension-api-examples', '# 代码示例 ## JavaScript/Node.js ```javascript const crypto = require(''crypto''); const axios = require(''axios''); const ACCESS_KEY = ''your_access_key''; const SECRET_KEY = ''your_secret_key''; const BASE_URL = ''https://your-domain.com/api/v1/ext''; // 生成签名 function generateSignature(method, path, timestamp, body) { const bodyStr = body ? JSON.stringify(body) : ''''; const stringToSign = method + path + timestamp + bodyStr; const hmac = crypto.createHmac(''sha256'', SECRET_KEY); hmac.update(stringToSign); return hmac.digest(''hex''); } // 发送请求 async function request(method, path, body = null) { const timestamp = Math.floor(Date.now() / 1000).toString(); const signature = generateSignature(method, path, timestamp, body); const headers = { ''X-Access-Key'': ACCESS_KEY, ''X-Signature'': signature, ''X-Timestamp'': timestamp, ''Content-Type'': ''application/json'' }; const config = { method, url: BASE_URL + path, headers }; if (body) { config.data = body; } const response = await axios(config); return response.data; } // 使用示例 async function main() { // 获取用户信息 const user = await request(''GET'', ''/user/1''); console.log(''用户信息:'', user); // 用户充值 const result = await request(''POST'', ''/user/1/recharge'', { amount: 100, type: ''days'', description: ''在线充值'' }); console.log(''充值结果:'', result); } main().catch(console.error); ``` ## Python ```python import hmac import hashlib import time import requests import json ACCESS_KEY = ''your_access_key'' SECRET_KEY = ''your_secret_key'' BASE_URL = ''https://your-domain.com/api/v1/ext'' def generate_signature(method, path, timestamp, body=''''): string_to_sign = method + path + timestamp + body signature = hmac.new( SECRET_KEY.encode(''utf-8''), string_to_sign.encode(''utf-8''), hashlib.sha256 ).hexdigest() return signature def request(method, path, body=None): timestamp = str(int(time.time())) body_str = json.dumps(body) if body else '''' signature = generate_signature(method, path, timestamp, body_str) headers = { ''X-Access-Key'': ACCESS_KEY, ''X-Signature'': signature, ''X-Timestamp'': timestamp, ''Content-Type'': ''application/json'' } url = BASE_URL + path response = requests.request(method, url, headers=headers, json=body) return response.json() # 使用示例 if __name__ == ''__main__'': # 获取用户信息 user = request(''GET'', ''/user/1'') print(''用户信息:'', user) # 用户充值 result = request(''POST'', ''/user/1/recharge'', { ''amount'': 100, ''type'': ''days'', ''description'': ''在线充值'' }) print(''充值结果:'', result) ``` ## 在线充值集成示例 以下是一个完整的在线充值集成示例，展示如何实现用户在线支付后自动充值： ```javascript // 支付回调处理 app.post(''/payment/callback'', async (req, res) => { const { order_id, user_id, amount, status } = req.body; // 验证支付状态 if (status !== ''success'') { return res.json({ code: -1, message: ''支付失败'' }); } try { // 调用扩展API为用户充值 const result = await request(''POST'', ''/user/'' + user_id + ''/recharge'', { amount: parseFloat(amount), type: ''days'', description: ''在线支付充值 - 订单号: '' + order_id }); if (result.code === 200) { // 更新订单状态 await updateOrderStatus(order_id, ''completed''); res.json({ code: 0, message: ''充值成功'' }); } else { res.json({ code: -1, message: result.message }); } } catch (error) { console.error(''充值失败:'', error); res.json({ code: -1, message: ''充值失败'' }); } }); ``` ', 'published', 6, datetime('now'), datetime('now') );