Initial commit

developer-front/public/docs/backend-integrations.md

@@ -0,0 +1,130 @@
+# 后台接入
+
+鉴权、接口调用与回调，国内与海外域名与限速差异，日志与监控。
+
+## 鉴权
+
+所有 API 请求都需要进行身份验证。
+
+### API 密钥
+
+在请求头中包含您的 API 密钥：
+
+```http
+Authorization: Bearer YOUR_API_KEY
+Content-Type: application/json
+```
+
+### 请求签名
+
+对于敏感操作，需要使用签名验证：
+
+```javascript
+const crypto = require('crypto')
+
+function generateSignature(params, secret) {
+    const sortedParams = Object.keys(params)
+        .sort()
+        .map(key => `${key}=${params[key]}`)
+        .join('&')
+    
+    return crypto
+        .createHmac('sha256', secret)
+        .update(sortedParams)
+        .digest('hex')
+}
+```
+
+## 接口调用
+
+### RESTful API
+
+基础 URL：
+- 国内：`https://api.jueyuan.com`
+- 海外：`https://api-global.jueyuan.com`
+
+### 示例请求
+
+```javascript
+const axios = require('axios')
+
+const client = axios.create({
+    baseURL: 'https://api.jueyuan.com',
+    headers: {
+        'Authorization': 'Bearer YOUR_API_KEY',
+        'Content-Type': 'application/json'
+    }
+})
+
+// 获取设备列表
+const devices = await client.get('/v1/devices')
+
+// 发送消息到设备
+await client.post('/v1/devices/device-id/messages', {
+    type: 'text',
+    content: 'Hello World'
+})
+```
+
+### 限速说明
+
+不同接口有不同的限速策略：
+
+- **普通接口**：100 次/分钟
+- **高频接口**：1000 次/分钟
+- **批量接口**：10 次/分钟
+
+超过限速会返回 `429 Too Many Requests` 错误。
+
+## 回调处理
+
+### Webhook 配置
+
+在开发者平台配置 Webhook URL，系统会在事件发生时调用该 URL。
+
+### 回调验证
+
+```javascript
+const crypto = require('crypto')
+
+function verifyCallback(signature, payload, secret) {
+    const hash = crypto
+        .createHmac('sha256', secret)
+        .update(JSON.stringify(payload))
+        .digest('hex')
+    
+    return hash === signature
+}
+```
+
+### 回调事件
+
+常见回调事件：
+
+- `device.connected` - 设备连接
+- `device.disconnected` - 设备断开
+- `message.received` - 收到消息
+- `voice.recognized` - 语音识别完成
+
+## 日志与监控
+
+### 日志查询
+
+```javascript
+// 查询设备日志
+const logs = await client.get('/v1/devices/device-id/logs', {
+    params: {
+        startTime: '2024-01-01T00:00:00Z',
+        endTime: '2024-01-02T00:00:00Z',
+        level: 'error'
+    }
+})
+```
+
+### 监控指标
+
+- API 调用次数
+- 错误率
+- 响应时间
+- 设备在线率
+