-- 扩展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')
);
