{
    "code": 1,
    "msg": "操作成功",
    "data": {}
}

参数说明:

• code: 状态码，1表示成功，0表示失败，-1表示特殊错误
• msg: 提示信息
• data: 返回数据（部分接口有）

所有API请求必须包含以下安全参数：

• timestamp：当前时间戳（秒），服务端会验证时间戳是否在有效范围内（±5分钟）
• nonce：随机字符串（建议使用UUID或MD5），服务端会缓存已使用的nonce，防止重复请求
• sign：HMAC-SHA256签名，使用软件的app_secret作为密钥

签名生成步骤：

1. 将所有请求参数（除sign外）按参数名升序排序
2. 将排序后的参数拼接成查询字符串（如：card_no=xxx&device_id=xxx&nonce=xxx&software_id=xxx×tamp=xxx&version=xxx）
3. 使用HMAC-SHA256算法，以app_secret为密钥，对拼接字符串进行签名
4. 将签名结果作为sign参数的值

示例代码（PHP）：

function generateSign($params, $secret) {
    unset($params['sign']);
    ksort($params);
    $string = http_build_query($params);
    return hash_hmac('sha256', $string, $secret);
}

$params = [
    'card_no' => 'FTPM-O0DX-5IN8-AZKR',
    'nonce' => md5(uniqid(mt_rand(), true)),
    'software_id' => 2,
    'timestamp' => time(),
    'version' => '1.0.0' // 登录接口必须包含 version
];

$secret = 'test_secret_key_123456';
$sign = generateSign($params, $secret);
$params['sign'] = $sign;

// 发送请求
$json = json_encode($params);
// ... 使用curl等工具发送请求

• 激活卡密：通过卡密登录接口激活卡密，卡密状态变为已使用
• 卡密有效期：卡密激活后开始计算有效期，到期后无法继续使用
• 卡密使用：所有需要卡密的接口都需要携带card_no和software_id参数
• 卡密唯一性：每张卡密只能使用一次，使用后无法重复使用

{
    "software_id": 2,
    "card_no": "TEST-1234567890",
    "device_id": "DEVICE_001"
}

1. 后台配置

管理员在后台的"软件管理"中可以设置：

• 最低允许版本（min_version）：如 1.0.0，低于此版本的客户端将被拒绝
• 最新版本（latest_version）：如 2.5.0，用于提示用户最新版本号
• 下载地址（download_url）：新版本的下载链接

2. 客户端请求

客户端在调用登录接口（卡密登录、试用登录）时，必须在请求参数中包含 version 字段：

{
    "software_id": 1,
    "version": "1.2.0",  // 客户端当前版本号
    "card_no": "XXXX-XXXX-XXXX-XXXX",
    "timestamp": 1737494400,
    "nonce": "random_string",
    "sign": "hmac_sha256_signature"
}

3. 服务端校验

服务端会自动比较客户端版本号与最低允许版本：

• 如果 客户端版本 >= 最低允许版本：正常处理请求
• 如果 客户端版本 < 最低允许版本：返回强制更新响应（code=100）

{
    "code": 100,  // 特殊状态码，表示强制更新
    "msg": "当前版本过低，请更新后使用",
    "data": {
        "min_version": "2.0.0",      // 最低允许版本
        "latest_version": "2.5.0",   // 最新版本
        "download_url": "https://example.com/download/v2.5.0"  // 下载地址
    }
}

1.0.0  // 初始版本
1.0.1  // 修复了一些bug
1.1.0  // 新增了部分功能
2.0.0  // 重大升级，可能不兼容旧版

当客户端检测到API返回的 code == 100 时，应该：

• 立即弹窗提示：告知用户当前版本过低，需要更新
• 禁止继续使用：直到完成更新后才能使用软件
• 提供更新按钮：点击后打开 data.download_url 下载页面
• 显示版本信息：展示最低要求版本和最新版本号
• 强制退出：如果用户拒绝更新，应退出程序

响应结构示例：

{
    "code": 100,
    "msg": "当前版本过低，请更新后使用",
    "data": {
        "min_version": "2.0.0",
        "latest_version": "2.5.0",
        "download_url": "https://example.com/download/v2.5.0"
    }
}

第一步：换取Token

客户端                      服务器
  │                           │
  │  POST /api/token/getToken  │
  │  {卡密 + 签名}           │
  ├────────────────────────▶│
  │                           │ ① 验证签名
  │                           │ ② 验证卡密有效性
  │                           │ ③ 生成Token（60秒有效）
  │                           │ ④ 存储到Redis+MySQL
  │                           │
  │  返回Token              │
  │◀────────────────────────┤
  │  {token: "abc123..."}    │

第二步：使用Token获取变量

客户端                      服务器
  │                           │
  │  POST /remote_var/getVarByToken
  │  {token + var_key}       │
  ├────────────────────────▶│
  │                           │ ① 从 Redis 验证Token
  │                           │ ② 检查是否已使用
  │                           │ ③ 检查是否过期
  │                           │ ④ 标记为已使用
  │                           │ ⑤ 返回变量值
  │                           │
  │  返回变量值            │
  │◀────────────────────────┤
  │  {var_value: "..."}      │
  │                           │
  │  ⚠️ Token已失效         │
  │  需要重新获取           │

1、极短有效期：60秒

• Token生成后只有60秒有效期
• 超过60秒后自动失效，无法使用
• 即使被黑客窃取，也只有不到60秒的窗口期

2、一次性使用

• 每个Token只能使用一次
• 使用后立即标记为已使用，从 Redis 中删除
• 再次使用相同Token会返回“Token已失效”错误
• 如需获取多个变量，必须每次都重新获取Token

3、安全隔离

• 卡密信息只在获取Token时传输一次
• 后续远程变量请求只使用Token，不再需要卡密
• 即使变量请求被监听，也无法获取真实卡密

4、Redis加速 新

• Token存储采用 MySQL + Redis 双存储
• Token验证优先从 Redis 读取，响应速度提升 3.6倍
• Redis 不可用时自动降级到 MySQL，不影响功能

• code = 1：表示请求成功，返回的数据在data字段中
• code = 0：表示请求失败，msg字段会包含具体的错误信息

• 必须使用HTTPS：所有API请求必须使用HTTPS协议，确保数据传输安全
• 卡密存储：建议在客户端安全存储卡密（如使用加密存储），避免明文保存
• 心跳超时检测：如果心跳失败超过一定次数，应该提示用户重新输入卡密
• 日志安全：记录API调用日志时，避免记录完整的卡密信息
• 输入验证：在客户端实现卡密格式验证，避免无效请求
• 用户体验：建议在客户端显示卡密到期时间信息
• 错误处理：妥善处理网络错误和API错误，避免泄露敏感信息