Initial commit: 网络验证平台

2026-04-27 17:22:56 +08:00
commit afe67d704e
780 changed files with 88960 additions and 0 deletions
@@ -0,0 +1,800 @@
+# 应用对接 API 文档
+
+## 概述
+
+本文档描述了开发者应用程序对接网络验证平台的 API 接口。所有 API 请求的基础路径为：
+
+```
+http://your-domain:8080/api/v1/app/{appKey}
+```
+
+其中 `{appKey}` 为开发者在后台创建应用时获取的应用密钥。
+
+## 通用说明
+
+### 请求格式
+
+- 所有请求使用 JSON 格式
+- Content-Type: `application/json`
+
+### 响应格式
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {}
+}
+```
+
+### 错误码
+
+| 错误码 | 说明 |
+|--------|------|
+| 200 | 成功 |
+| 400 | 参数错误 |
+| 404 | 资源不存在 |
+| 500 | 服务器错误 |
+
+---
+
+## 应用信息接口
+
+### 获取应用信息
+
+获取应用的基本信息。
+
+**请求**
+
+```
+GET /api/v1/app/{appKey}/info
+```
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "id": 1,
+    "name": "应用名称",
+    "description": "应用描述",
+    "status": "active"
+  }
+}
+```
+
+### 检查更新
+
+检查应用是否有新版本。
+
+**请求**
+
+```
+GET /api/v1/app/{appKey}/check-update?version=1.0.0
+```
+
+**参数**
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| version | string | 否 | 当前客户端版本号 |
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "has_update": true,
+    "latest_version": "1.0.1",
+    "download_url": "https://example.com/download/1.0.1",
+    "update_notes": "修复若干bug",
+    "update_strategy": "optional",
+    "update_method": "manual"
+  }
+}
+```
+
+**响应字段说明**
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| has_update | boolean | 是否有更新 |
+| latest_version | string | 最新版本号 |
+| download_url | string | 下载地址 |
+| update_notes | string | 更新说明 |
+| update_strategy | string | 更新策略：`optional`(可选更新) 或 `force`(强制更新) |
+| update_method | string | 更新方式：`auto`(自动更新) 或 `manual`(手动更新) |
+
+### 获取公告列表
+
+获取应用的公告列表。
+
+**请求**
+
+```
+GET /api/v1/app/{appKey}/announcements
+```
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": [
+    {
+      "id": 1,
+      "title": "公告标题",
+      "content": "公告内容",
+      "type": "info",
+      "priority": "normal",
+      "created_at": "2024-01-01T00:00:00Z"
+    }
+  ]
+}
+```
+
+---
+
+## 用户认证接口
+
+### 用户注册
+
+注册新用户。
+
+**请求**
+
+```
+POST /api/v1/app/{appKey}/register
+```
+
+**请求体**
+
+```json
+{
+  "username": "testuser",
+  "password": "123456",
+  "device_id": "DEVICE_001"
+}
+```
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| username | string | 是 | 用户名 |
+| password | string | 是 | 密码 |
+| device_id | string | 否 | 设备ID |
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "user_id": 1,
+    "token": ""
+  }
+}
+```
+
+### 用户登录
+
+用户登录验证。
+
+**请求**
+
+```
+POST /api/v1/app/{appKey}/login
+```
+
+**请求体**
+
+```json
+{
+  "username": "testuser",
+  "password": "123456",
+  "device_id": "DEVICE_001"
+}
+```
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| username | string | 是 | 用户名 |
+| password | string | 是 | 密码 |
+| device_id | string | 否 | 设备ID |
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "user_id": 1,
+    "token": ""
+  }
+}
+```
+
+---
+
+## 账户管理接口
+
+### 获取账户信息
+
+获取用户账户详细信息。
+
+**请求**
+
+```
+GET /api/v1/app/{appKey}/account
+```
+
+**请求体**
+
+```json
+{
+  "user_id": 1
+}
+```
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| user_id | uint | 是 | 用户ID |
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "user_id": 1,
+    "username": "testuser",
+    "expire_time": "2024-12-31T23:59:59Z",
+    "status": "active"
+  }
+}
+```
+
+### 心跳检测
+
+客户端心跳检测，保持在线状态。
+
+**请求**
+
+```
+POST /api/v1/app/{appKey}/heartbeat
+```
+
+**请求体**
+
+```json
+{
+  "user_id": 1
+}
+```
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| user_id | uint | 是 | 用户ID |
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "message": "心跳成功"
+  }
+}
+```
+
+---
+
+## 充值与试用接口
+
+### 卡密充值
+
+使用卡密为账户充值。
+
+**请求**
+
+```
+POST /api/v1/app/{appKey}/recharge
+```
+
+**请求体**
+
+```json
+{
+  "user_id": 1,
+  "card_key": "CARD_KEY_123456"
+}
+```
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| user_id | uint | 是 | 用户ID |
+| card_key | string | 是 | 卡密 |
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "message": "充值成功",
+    "value": 30
+  }
+}
+```
+
+### 试用申请
+
+申请试用功能。
+
+**请求**
+
+```
+POST /api/v1/app/{appKey}/trial
+```
+
+**请求体**
+
+```json
+{
+  "user_id": 1
+}
+```
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| user_id | uint | 是 | 用户ID |
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "message": "试用成功",
+    "duration": 7
+  }
+}
+```
+
+---
+
+## 设备管理接口
+
+### 获取设备列表
+
+获取用户绑定的设备列表。
+
+**请求**
+
+```
+GET /api/v1/app/{appKey}/devices
+```
+
+**请求体**
+
+```json
+{
+  "user_id": 1
+}
+```
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| user_id | uint | 是 | 用户ID |
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": [
+    {
+      "device_id": "DEVICE_001",
+      "user_id": 1
+    }
+  ]
+}
+```
+
+### 解绑设备
+
+解绑指定设备。
+
+**请求**
+
+```
+POST /api/v1/app/{appKey}/unbind-device
+```
+
+**请求体**
+
+```json
+{
+  "user_id": 1,
+  "device_id": "DEVICE_001"
+}
+```
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| user_id | uint | 是 | 用户ID |
+| device_id | string | 是 | 设备ID |
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "message": "解绑成功"
+  }
+}
+```
+
+---
+
+## 云端数据接口
+
+**注意**：云端数据接口需要用户登录认证，需要在请求头中携带JWT token：
+```
+Authorization: Bearer {token}
+```
+
+### 获取云端常量
+
+获取应用设置的云端常量。
+
+**请求**
+
+```
+GET /api/v1/app/{appKey}/constants
+```
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": [
+    {
+      "id": 1,
+      "name": "常量名称",
+      "key": "CONSTANT_KEY",
+      "value": "常量值",
+      "var_type": "string",
+      "description": "常量描述"
+    }
+  ]
+}
+```
+
+### 获取指定云端常量
+
+根据key获取指定的云端常量。
+
+**请求**
+
+```
+GET /api/v1/app/{appKey}/constants/{key}
+```
+
+**路径参数**
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| key | string | 是 | 常量key |
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "id": 1,
+    "name": "常量名称",
+    "key": "CONSTANT_KEY",
+    "value": "常量值",
+    "var_type": "string",
+    "description": "常量描述"
+  }
+}
+```
+
+### 获取云端变量
+
+获取用户的云端变量。
+
+**请求**
+
+```
+GET /api/v1/app/{appKey}/variables
+```
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": [
+    {
+      "id": 1,
+      "name": "变量名称",
+      "key": "VARIABLE_KEY",
+      "default_value": "默认值",
+      "var_type": "string",
+      "scope": "user",
+      "description": "变量描述"
+    }
+  ]
+}
+```
+
+### 获取指定云端变量
+
+根据key获取指定的云端变量。
+
+**请求**
+
+```
+GET /api/v1/app/{appKey}/variables/{key}
+```
+
+**路径参数**
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| key | string | 是 | 变量key |
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "id": 1,
+    "name": "变量名称",
+    "key": "VARIABLE_KEY",
+    "default_value": "默认值",
+    "var_type": "string",
+    "scope": "user",
+    "description": "变量描述"
+  }
+}
+```
+
+### 更新云端变量
+
+更新用户的云端变量。
+
+**请求**
+
+```
+POST /api/v1/app/{appKey}/variables
+```
+
+**请求体**
+
+```json
+{
+  "variables": {
+    "key1": "value1",
+    "key2": "value2"
+  }
+}
+```
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| variables | object | 是 | 变量键值对 |
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "message": "更新成功"
+  }
+}
+```
+
+### 调用云端函数
+
+调用云端自定义函数。
+
+**请求**
+
+```
+POST /api/v1/app/{appKey}/call-function
+```
+
+**请求体**
+
+```json
+{
+  "name": "function_name",
+  "params": {
+    "param1": "value1",
+    "param2": "value2"
+  }
+}
+```
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| name | string | 是 | 函数名称 |
+| params | object | 否 | 函数参数 |
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "result": null
+  }
+}
+```
+
+---
+
+## 动态代码接口
+
+**注意**：动态代码接口需要用户登录认证，需要在请求头中携带JWT token：
+```
+Authorization: Bearer {token}
+```
+
+### 获取动态代码
+
+获取应用的动态代码。
+
+**请求**
+
+```
+GET /api/v1/app/{appKey}/dynamic-code
+```
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "code": "function hello() {\n  return 'Hello World';\n}"
+  }
+}
+```
+
+### 更新动态代码
+
+更新应用的动态代码。
+
+**请求**
+
+```
+POST /api/v1/app/{appKey}/dynamic-code
+```
+
+**请求体**
+
+```json
+{
+  "code": "function hello() {\n  return 'Hello World';\n}"
+}
+```
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| code | string | 是 | Goja代码（JavaScript语法） |
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "message": "更新成功"
+  }
+}
+```
+
+**说明**
+
+- 动态代码使用Goja引擎执行（Go语言的JavaScript实现）
+- 支持完整的JavaScript语法
+- 代码执行环境受限，无法访问系统资源
+- 建议代码简洁高效，避免复杂逻辑
+
+---
+
+## 错误响应示例
+
+### 应用不存在
+
+```json
+{
+  "code": 404,
+  "message": "应用不存在",
+  "data": null
+}
+```
+
+### 参数错误
+
+```json
+{
+  "code": 400,
+  "message": "参数错误",
+  "data": null
+}
+```
+
+### 用户不存在
+
+```json
+{
+  "code": 404,
+  "message": "用户不存在",
+  "data": null
+}
+```
+
+### 卡密已使用
+
+```json
+{
+  "code": 400,
+  "message": "卡密已使用",
+  "data": null
+}
+```
+
+---
+
+## 接入流程
+
+1. **创建应用**：在开发者后台创建应用，获取 `appKey` 和 `secretKey`
+2. **配置应用**：设置应用的绑定类型、最大设备数、试用功能等
+3. **创建卡密类型**：根据业务需求创建卡密类型（订阅/计时/点卡）
+4. **生成卡密**：生成卡密供用户充值使用
+5. **客户端对接**：按照本文档进行客户端开发
+
+## 安全建议
+
+1. **HTTPS**：生产环境建议使用 HTTPS 加密传输
+2. **签名验证**：敏感操作建议添加签名验证
+3. **频率限制**：建议对 API 调用频率进行限制
+4. **数据加密**：敏感数据建议加密存储和传输
+
+## 版本历史
+
+| 版本 | 日期 | 说明 |
+|------|------|------|
+| 1.1.0 | 2024-03-10 | 新增动态代码接口（使用Goja引擎） |
+| 1.0.0 | 2024-01-01 | 初始版本 |