# 应用对接 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 | 初始版本 |
