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 | 初始版本 |
@@ -0,0 +1,630 @@
+# 扩展功能API文档
+
+## 概述
+
+扩展功能允许开发者通过Webhook和开放API将平台功能与自己的业务系统对接，实现自动化业务流程。
+
+## 功能特性
+
+- **Webhook回调**: 实时接收平台事件通知
+- **开放API**: 通过API密钥访问平台功能
+- **签名验证**: 确保请求安全可靠
+- **权限控制**: 细粒度的API访问权限管理
+
+---
+
+## 一、Webhook配置
+
+### 1.1 创建Webhook
+
+**接口**: `POST /api/v1/dev/extension/webhooks`
+
+**请求参数**:
+```json
+{
+  "application_id": 1,
+  "name": "商城系统",
+  "url": "https://your-server.com/webhook",
+  "secret_key": "your_secret_key",
+  "events": ["user.registered", "user.recharged"],
+  "retry_count": 3,
+  "timeout": 10
+}
+```
+
+**参数说明**:
+- `application_id` (必填): 应用ID
+- `name` (必填): Webhook名称
+- `url` (必填): 回调URL
+- `secret_key` (可选): 密钥，用于验证回调请求
+- `events` (必填): 订阅的事件类型数组
+- `retry_count` (可选): 重试次数，默认3次
+- `timeout` (可选): 超时时间（秒），默认10秒
+
+### 1.2 查询Webhook列表
+
+**接口**: `GET /api/v1/dev/extension/webhooks?application_id=1`
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "data": [
+    {
+      "id": 1,
+      "application_id": 1,
+      "name": "商城系统",
+      "url": "https://your-server.com/webhook",
+      "secret_key": "your_secret_key",
+      "events": "[\"user.registered\",\"user.recharged\"]",
+      "status": "active",
+      "retry_count": 3,
+      "timeout": 10,
+      "created_at": "2024-01-01T00:00:00Z"
+    }
+  ]
+}
+```
+
+### 1.3 更新Webhook
+
+**接口**: `PUT /api/v1/dev/extension/webhooks/:id`
+
+**请求参数**: 同创建Webhook
+
+### 1.4 删除Webhook
+
+**接口**: `DELETE /api/v1/dev/extension/webhooks/:id`
+
+### 1.5 测试Webhook
+
+**接口**: `POST /api/v1/dev/extension/webhooks/:id/test`
+
+### 1.6 查看Webhook日志
+
+**接口**: `GET /api/v1/dev/extension/webhooks/logs?webhook_id=1`
+
+---
+
+## 二、Webhook事件
+
+### 2.1 支持的事件类型
+
+| 事件代码 | 事件名称 | 触发时机 |
+|---------|---------|---------|
+| `user.registered` | 用户注册 | 新用户注册成功时 |
+| `user.login` | 用户登录 | 用户登录成功时 |
+| `user.recharged` | 用户充值 | 用户充值成功时 |
+| `user.expired` | 用户到期 | 用户会员到期时 |
+| `card.used` | 卡密使用 | 卡密被使用时 |
+| `card.expired` | 卡密过期 | 卡密过期时 |
+| `abnormal.detected` | 异常检测 | 检测到异常行为时 |
+
+### 2.2 回调数据格式
+
+当事件触发时，平台会向配置的URL发送POST请求：
+
+```json
+{
+  "event": "user.registered",
+  "timestamp": 1234567890,
+  "data": {
+    "user_id": 123,
+    "username": "testuser",
+    "email": "test@example.com",
+    "application_id": 1
+  }
+}
+```
+
+### 2.3 验证回调请求
+
+如果配置了`secret_key`，平台会在请求头中添加：
+
+```
+X-Webhook-Secret: your_secret_key
+```
+
+您的服务器应验证此头部以确保请求来自平台。
+
+---
+
+## 三、API密钥管理
+
+### 3.1 创建API密钥
+
+**接口**: `POST /api/v1/dev/extension/api-keys`
+
+**请求参数**:
+```json
+{
+  "application_id": 1,
+  "name": "商城对接",
+  "permissions": ["user.read", "user.recharge"],
+  "expires_at": "2025-12-31T23:59:59Z"
+}
+```
+
+**参数说明**:
+- `application_id` (必填): 应用ID
+- `name` (必填): 密钥名称
+- `permissions` (可选): 权限列表
+- `expires_at` (可选): 过期时间
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "data": {
+    "id": 1,
+    "application_id": 1,
+    "name": "商城对接",
+    "access_key": "abc123...",
+    "secret_key": "xyz789...",
+    "permissions": "[\"user.read\",\"user.recharge\"]",
+    "status": "active",
+    "created_at": "2024-01-01T00:00:00Z"
+  }
+}
+```
+
+**重要**: `secret_key`只在创建时返回一次，请妥善保存！
+
+### 3.2 查询API密钥列表
+
+**接口**: `GET /api/v1/dev/extension/api-keys?application_id=1`
+
+### 3.3 更新API密钥
+
+**接口**: `PUT /api/v1/dev/extension/api-keys/:id`
+
+### 3.4 删除API密钥
+
+**接口**: `DELETE /api/v1/dev/extension/api-keys/:id`
+
+### 3.5 重新生成密钥
+
+**接口**: `POST /api/v1/dev/extension/api-keys/:id/regenerate`
+
+**注意**: 重新生成后，旧密钥立即失效！
+
+---
+
+## 四、开放API接口
+
+### 4.1 认证方式
+
+所有开放API请求都需要进行签名认证：
+
+**请求头**:
+```
+X-Access-Key: your_access_key
+X-Signature: calculated_signature
+X-Timestamp: 1234567890
+```
+
+**签名算法**:
+```javascript
+// 1. 构造签名字符串
+const stringToSign = METHOD + PATH + TIMESTAMP + BODY
+
+// 示例
+const method = "POST"
+const path = "/api/v1/ext/user/123/recharge"
+const timestamp = "1234567890"
+const body = JSON.stringify({
+  "amount": 100,
+  "type": "points",
+  "description": "商城充值"
+})
+
+const stringToSign = method + path + timestamp + body
+// 结果: "POST/api/v1/ext/user/123/recharge1234567890{\"amount\":100,\"type\":\"points\",\"description\":\"商城充值\"}"
+
+// 2. 计算签名
+const signature = HMAC-SHA256(secretKey, stringToSign)
+```
+
+**Python示例**:
+```python
+import hmac
+import hashlib
+import time
+import json
+
+def calculate_signature(secret_key, method, path, timestamp, body):
+    string_to_sign = method + path + str(timestamp) + body
+    signature = hmac.new(
+        secret_key.encode('utf-8'),
+        string_to_sign.encode('utf-8'),
+        hashlib.sha256
+    ).hexdigest()
+    return signature
+
+# 使用示例
+access_key = "your_access_key"
+secret_key = "your_secret_key"
+method = "POST"
+path = "/api/v1/ext/user/123/recharge"
+timestamp = int(time.time())
+body = json.dumps({
+    "amount": 100,
+    "type": "points",
+    "description": "商城充值"
+})
+
+signature = calculate_signature(secret_key, method, path, timestamp, body)
+
+headers = {
+    "X-Access-Key": access_key,
+    "X-Signature": signature,
+    "X-Timestamp": str(timestamp),
+    "Content-Type": "application/json"
+}
+```
+
+### 4.2 用户相关接口
+
+#### 4.2.1 查询用户信息
+
+**接口**: `GET /api/v1/ext/user/:userId`
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "data": {
+    "id": 123,
+    "username": "testuser",
+    "email": "test@example.com",
+    "points": 1000,
+    "level": 1,
+    "status": "active",
+    "expiry_at": "2024-12-31T23:59:59Z",
+    "last_login_at": "2024-01-01T12:00:00Z",
+    "created_at": "2024-01-01T00:00:00Z"
+  }
+}
+```
+
+#### 4.2.2 查询用户列表
+
+**接口**: `GET /api/v1/ext/users?page=1&page_size=20&status=active&search=test`
+
+**参数说明**:
+- `page`: 页码，默认1
+- `page_size`: 每页数量，默认20
+- `status`: 用户状态筛选
+- `search`: 搜索关键词（用户名或邮箱）
+
+#### 4.2.3 为用户充值
+
+**接口**: `POST /api/v1/ext/user/:userId/recharge`
+
+**请求参数**:
+```json
+{
+  "amount": 100,
+  "type": "points",
+  "description": "商城充值"
+}
+```
+
+**参数说明**:
+- `amount` (必填): 充值数量
+- `type` (必填): 充值类型
+  - `points`: 充值积分
+  - `days`: 充值天数
+- `description` (可选): 充值说明
+
+#### 4.2.4 扣除用户余额
+
+**接口**: `POST /api/v1/ext/user/:userId/deduct`
+
+**请求参数**:
+```json
+{
+  "amount": 50,
+  "type": "points",
+  "description": "购买商品"
+}
+```
+
+#### 4.2.5 更新用户积分
+
+**接口**: `POST /api/v1/ext/user/:userId/points`
+
+**请求参数**:
+```json
+{
+  "points": 500
+}
+```
+
+### 4.3 卡密相关接口
+
+#### 4.3.1 查询卡密列表
+
+**接口**: `GET /api/v1/ext/cards?page=1&page_size=20&status=unused&card_type_id=1`
+
+#### 4.3.2 生成卡密
+
+**接口**: `POST /api/v1/ext/cards/generate`
+
+**请求参数**:
+```json
+{
+  "card_type_id": 1,
+  "count": 10
+}
+```
+
+#### 4.3.3 查询卡密详情
+
+**接口**: `GET /api/v1/ext/card/:cardId`
+
+### 4.4 通知相关接口
+
+#### 4.4.1 发送通知
+
+**接口**: `POST /api/v1/ext/notification`
+
+**请求参数**:
+```json
+{
+  "user_id": 123,
+  "title": "系统通知",
+  "content": "您的充值已到账",
+  "type": "system"
+}
+```
+
+#### 4.4.2 批量发送通知
+
+**接口**: `POST /api/v1/ext/notification/batch`
+
+**请求参数**:
+```json
+{
+  "title": "系统公告",
+  "content": "系统将于今晚维护",
+  "type": "announcement"
+}
+```
+
+### 4.5 应用信息接口
+
+#### 4.5.1 获取应用信息
+
+**接口**: `GET /api/v1/ext/app/info`
+
+#### 4.5.2 获取应用统计
+
+**接口**: `GET /api/v1/ext/app/stats`
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "data": {
+    "user_count": 1000,
+    "active_user_count": 800,
+    "card_count": 500,
+    "used_card_count": 300
+  }
+}
+```
+
+---
+
+## 五、权限说明
+
+### 5.1 可用权限列表
+
+| 权限代码 | 权限名称 | 说明 |
+|---------|---------|------|
+| `user.read` | 查看用户 | 查询用户信息和列表 |
+| `user.recharge` | 用户充值 | 为用户充值积分或天数 |
+| `user.deduct` | 用户扣费 | 扣除用户积分或天数 |
+| `card.read` | 查看卡密 | 查询卡密信息和列表 |
+| `card.generate` | 生成卡密 | 生成新的卡密 |
+| `notification.send` | 发送通知 | 发送用户通知 |
+
+---
+
+## 六、错误码说明
+
+| 错误码 | 说明 |
+|-------|------|
+| 200 | 成功 |
+| 400 | 请求参数错误 |
+| 401 | 认证失败（缺少认证信息、签名错误、密钥无效等） |
+| 403 | 权限不足 |
+| 404 | 资源不存在 |
+| 500 | 服务器内部错误 |
+
+---
+
+## 七、最佳实践
+
+### 7.1 安全建议
+
+1. **妥善保管密钥**: Secret Key只在创建时显示一次，请立即保存
+2. **定期更换密钥**: 建议定期重新生成API密钥
+3. **最小权限原则**: 只授予必要的权限
+4. **验证Webhook**: 验证回调请求的来源和完整性
+5. **使用HTTPS**: 确保所有通信都使用HTTPS
+
+### 7.2 性能优化
+
+1. **批量操作**: 使用批量接口减少请求次数
+2. **缓存数据**: 合理缓存用户信息等数据
+3. **异步处理**: Webhook回调建议异步处理业务逻辑
+
+### 7.3 错误处理
+
+1. **重试机制**: 实现请求重试逻辑，处理网络异常
+2. **日志记录**: 记录所有API请求和响应，便于排查问题
+3. **超时设置**: 合理设置请求超时时间
+
+---
+
+## 八、完整示例
+
+### 8.1 Python示例
+
+```python
+import requests
+import hmac
+import hashlib
+import time
+import json
+
+class ExtensionAPI:
+    def __init__(self, access_key, secret_key, base_url="http://localhost:8080"):
+        self.access_key = access_key
+        self.secret_key = secret_key
+        self.base_url = base_url
+    
+    def _calculate_signature(self, method, path, timestamp, body=""):
+        string_to_sign = method + path + str(timestamp) + body
+        signature = hmac.new(
+            self.secret_key.encode('utf-8'),
+            string_to_sign.encode('utf-8'),
+            hashlib.sha256
+        ).hexdigest()
+        return signature
+    
+    def _get_headers(self, method, path, body=""):
+        timestamp = int(time.time())
+        signature = self._calculate_signature(method, path, timestamp, body)
+        return {
+            "X-Access-Key": self.access_key,
+            "X-Signature": signature,
+            "X-Timestamp": str(timestamp),
+            "Content-Type": "application/json"
+        }
+    
+    def get_user(self, user_id):
+        path = f"/api/v1/ext/user/{user_id}"
+        headers = self._get_headers("GET", path)
+        response = requests.get(f"{self.base_url}{path}", headers=headers)
+        return response.json()
+    
+    def recharge_user(self, user_id, amount, recharge_type, description=""):
+        path = f"/api/v1/ext/user/{user_id}/recharge"
+        body = json.dumps({
+            "amount": amount,
+            "type": recharge_type,
+            "description": description
+        })
+        headers = self._get_headers("POST", path, body)
+        response = requests.post(f"{self.base_url}{path}", headers=headers, data=body)
+        return response.json()
+
+# 使用示例
+api = ExtensionAPI("your_access_key", "your_secret_key")
+
+# 查询用户
+user = api.get_user(123)
+print(user)
+
+# 为用户充值100积分
+result = api.recharge_user(123, 100, "points", "商城充值")
+print(result)
+```
+
+### 8.2 Node.js示例
+
+```javascript
+const crypto = require('crypto');
+const axios = require('axios');
+
+class ExtensionAPI {
+  constructor(accessKey, secretKey, baseUrl = 'http://localhost:8080') {
+    this.accessKey = accessKey;
+    this.secretKey = secretKey;
+    this.baseUrl = baseUrl;
+  }
+
+  calculateSignature(method, path, timestamp, body = '') {
+    const stringToSign = method + path + timestamp + body;
+    return crypto
+      .createHmac('sha256', this.secretKey)
+      .update(stringToSign)
+      .digest('hex');
+  }
+
+  getHeaders(method, path, body = '') {
+    const timestamp = Math.floor(Date.now() / 1000);
+    const signature = this.calculateSignature(method, path, timestamp, body);
+    return {
+      'X-Access-Key': this.accessKey,
+      'X-Signature': signature,
+      'X-Timestamp': timestamp.toString(),
+      'Content-Type': 'application/json'
+    };
+  }
+
+  async getUser(userId) {
+    const path = `/api/v1/ext/user/${userId}`;
+    const headers = this.getHeaders('GET', path);
+    const response = await axios.get(`${this.baseUrl}${path}`, { headers });
+    return response.data;
+  }
+
+  async rechargeUser(userId, amount, type, description = '') {
+    const path = `/api/v1/ext/user/${userId}/recharge`;
+    const body = JSON.stringify({ amount, type, description });
+    const headers = this.getHeaders('POST', path, body);
+    const response = await axios.post(`${this.baseUrl}${path}`, body, { headers });
+    return response.data;
+  }
+}
+
+// 使用示例
+const api = new ExtensionAPI('your_access_key', 'your_secret_key');
+
+// 查询用户
+api.getUser(123).then(user => console.log(user));
+
+// 为用户充值100积分
+api.rechargeUser(123, 100, 'points', '商城充值').then(result => console.log(result));
+```
+
+---
+
+## 九、常见问题
+
+### Q1: 签名验证失败怎么办？
+
+**A**: 请检查以下几点：
+1. 确保使用正确的Secret Key
+2. 确保时间戳是当前Unix时间戳（秒级）
+3. 确保签名字符串的拼接顺序正确：METHOD + PATH + TIMESTAMP + BODY
+4. 确保Body是原始JSON字符串，不要格式化或添加空格
+
+### Q2: Webhook回调失败怎么办？
+
+**A**: 
+1. 检查回调URL是否可访问
+2. 查看Webhook日志了解失败原因
+3. 确保服务器能正确处理POST请求
+4. 检查是否设置了正确的超时时间
+
+### Q3: API密钥泄露了怎么办？
+
+**A**: 立即删除旧密钥并创建新密钥，或者使用"重新生成"功能。
+
+### Q4: 如何测试API接口？
+
+**A**: 可以使用Postman、curl等工具，参考本文档中的签名算法构造请求。
+
+---
+
+## 十、技术支持
+
+如有问题，请通过以下方式获取帮助：
+- 查看平台文档
+- 提交工单
+- 联系技术支持