# 网络验证授权系统 - 客户端SDK使用文档

## 快速接入

### 1. 复制文件
将 `auth_sdk.php` 复制到你的PHP项目目录。

### 2. 引入并初始化
```php
include 'auth_sdk.php';

// 参数：授权服务器地址、AppID、AppSecret
$auth = new AuthSDK('https://peak.zrlcy.cn', '你的AppID', '你的AppSecret');
```

### 3. 在需要验证的地方调用
```php
$result = $auth->verify();
if ($result['code'] != 200) {
    // 未授权，显示激活页面或跳转
    die('授权失败：' . $result['message']);
}
// 授权通过，继续你的业务逻辑
```

## 完整示例

```php
include 'auth_sdk.php';
$auth = new AuthSDK('https://peak.zrlcy.cn', 'AppID', 'AppSecret');

// 处理激活
if ($_SERVER['REQUEST_METHOD'] == 'POST' && isset($_POST['card_key'])) {
    $result = $auth->activate($_POST['card_key']);
    if ($result['code'] == 200) {
        echo '激活成功！';
    } else {
        echo '激活失败：' . $result['message'];
    }
}

// 验证授权
$result = $auth->verify();
if ($result['code'] == 200) {
    echo '授权有效，到期时间：' . $result['data']['expire_time'];
} else {
    // 显示激活表单
    echo '<form method="post"><input name="card_key"><button>激活</button></form>';
}
```

## API方法说明

| 方法 | 说明 | 返回 |
|------|------|------|
| `activate($card_key)` | 激活卡密 | code=200成功 |
| `verify()` | 验证授权（带12小时缓存） | code=200通过 |
| `verify(true)` | 强制远程验证 | code=200通过 |
| `heartbeat()` | 发送心跳 | code=200正常 |
| `get_announcements($version)` | 获取公告和版本更新 | 公告列表 |
| `is_activated()` | 是否已激活 | bool |
| `get_auth_info()` | 获取授权信息 | array/null |
| `logout()` | 清除本地授权 | bool |

## 返回码说明

| code | 说明 |
|------|------|
| 200 | 成功 |
| 400 | 参数错误 |
| 401 | 应用验证失败（AppID/Secret错误） |
| 403 | 已被拉黑/吊销 |
| 404 | 卡密不存在/未激活 |
| 409 | 域名不匹配（卡密绑定了其他域名） |
| 410 | 卡密已过期 |
| -1 | 网络请求失败（会自动使用离线缓存） |

## 安全建议

1. **AppSecret保密**：不要把AppSecret暴露给前端，所有验证都在服务端进行
2. **关键操作验证**：支付、数据同步等关键操作前调用 `$auth->verify(true)` 强制远程验证
3. **定期心跳**：可以设置定时任务每天调用一次 `$auth->heartbeat()`
4. **缓存目录**：默认使用系统临时目录，建议指定到网站不可访问的目录

## 离线容错

当授权服务器无法访问时，SDK会自动使用本地缓存（最长12小时），保证你的网站不会因为授权服务器故障而瘫痪。缓存过期后才会真正拦截。