Skip to content

API.md

Latest commit

 

History

History
438 lines (366 loc) · 7.57 KB

API.md

File metadata and controls

438 lines (366 loc) · 7.57 KB
Raw

OVAM API 文档

认证

检查系统状态

GET /api/admin/auth/status

响应：

{
  "configured": true
}

登录（密码 + TOTP）

POST /api/admin/auth/login
Content-Type: application/json

{
  "password": "your-password",
  "code": "123456",
  "remember_me": true
}

响应：

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 2592000
}

注：

  • 默认有效期为 7 天（604800 秒），可通过环境变量 OVAM_JWT_EXPIRE_HOURS 自定义；
  • 开启 remember_me 时有效期为 30 天（2592000 秒）；
  • 系统支持无感滑动续期：当 Token 剩余有效期不足一半时，API 响应头会自动携带 X-Refresh-Token 供前端无感更新。

修改密码

POST /api/admin/auth/change-password
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "current_password": "old-password",
  "code": "123456",
  "new_password": "new-password"
}

公开接口（客户端）

购买跳转

GET /buy?p=<product_slug>&s=<sku_alias>&d=<device_id>

重定向到爱发电支付页面。

设备激活

POST /api/v1/:slug/activate
Content-Type: application/json

{
  "device_id": "device-123",
  "deviceInfo": {
    "product": "MiBand8",
    "osVersionName": "1.0.0"
  }
}

响应：

{
  "status": "success",
  "license": {
    "payload": { ... },
    "signature": "base64..."
  }
}

云控配置

POST /api/v1/:slug/config
Content-Type: application/json

{
  "device_id": "device-123",
  "product": "MiBand8",
  "app_version_code": 120
}

响应：

{
  "announcements": [],
  "maintenance": {
    "enabled": false,
    "message": "",
    "end_at": 0
  },
  "feature_toggles": {
    "feature_a": true
  },
  "update": {
    "force": false,
    "latest_version_code": 120,
    "update_url": "",
    "changelog": ""
  },
  "extra_rules": []
}

事件上报（通用遥测）

POST /api/v1/:slug/event
Content-Type: application/json

{
  "device_id": "device-123",
  "event_name": "app_start",
  "version_code": 12,
  "product": "vela",
  "behaviors": {
    "open_menu": 5,
    "open_search": 2,
    "start_sync": 1
  }
}

注：

  • behaviors 为该设备自上次成功上报以来新累积的差量计数字典，OVAM 会在底层自动原子累加；
  • 行为名受 config.yaml 中该产品的 allowed_behaviors 白名单限制，非白名单内的行为会被自动过滤丢弃。

反馈上报

POST /api/v1/:slug/feedback
Content-Type: application/json

{
  "device_id": "device-123",
  "content": "用户反馈内容"
}

爱发电 Webhook

POST /api/v1/webhook/afdian?token=<webhook_token>
Content-Type: application/json

{
  "sign": "signature",
  "data": {
    "type": "order",
    "order": { ... }
  }
}

注：URL 中的 token 参数必须与 config.yaml 中的 afdian.webhook_token 一致，否则拒绝处理。

管理后台接口（需 JWT）

统计数据

GET /api/admin/stats
Authorization: Bearer <jwt>

配置管理

获取原始配置

GET /api/admin/config/raw
Authorization: Bearer <jwt>

保存配置

POST /api/admin/config/save
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "server": { ... },
  "database": { ... },
  "products": [ ... ]
}

数据查询

GET /api/admin/data/:table?page=1&size=20&q=keyword&product_slug=&sort=created_at+desc
Authorization: Bearer <jwt>

支持表：devices, orders, events, feedbacks, audit_logs

查询参数：

  • page: 页码（默认 1）
  • size: 每页条数（默认 20，最大 1000）
  • q: 关键词搜索
  • product_slug: 按产品过滤
  • sort: 排序字段（created_at desc）
  • activated: true/false（仅 devices）
  • processed: true/false（仅 orders）

设备管理

保存/更新设备

POST /api/admin/devices/save
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "device_id": "device-123",
  "product_slug": "product-slug",
  "expire_at": 1700000000,
  "is_active": true
}

删除设备

DELETE /api/admin/devices/:slug/:device_id
Authorization: Bearer <jwt>

订单管理

快速修改订单 / 授权 SKU

POST /api/admin/orders/modify
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "out_trade_no": "20210101...",
  "product_slug": "example_product",
  "sku_alias": "f",
  "new_device_id": "device-123",
  "amount": "50.00",
  "recalculate": true
}

手动创建订单

POST /api/admin/orders/create
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "out_trade_no": "MANUAL_001",
  "device_id": "device-123",
  "product_slug": "example_product",
  "sku_alias": "m",
  "amount": "5.00"
}

修复订单设备 ID

POST /api/admin/orders/repair
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "out_trade_no": "20210101...",
  "new_device_id": "device-123"
}

删除订单

DELETE /api/admin/orders/:out_trade_no
Authorization: Bearer <jwt>

爱发电自动补单与同步

手动触发订单对账同步

POST /api/admin/afdian/sync-orders
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "page": 1,
  "per_page": 50,
  "out_trade_no": ""
}

响应：

{
  "result": {
    "total_queried": 50,
    "new_created": 2,
    "success_processed": 2,
    "pending_repair": 0,
    "skipped_existing": 48,
    "errors": []
  },
  "total_count": 100,
  "total_page": 2
}

从爱发电同步产品与 SKU 方案

GET /api/admin/afdian/sync?product_slug=<product_slug>
Authorization: Bearer <jwt>

向爱发电 API 拉取并更新指定产品的赞助方案与 SKU 列表。

动态产品遥测 (Telemetry)

获取产品遥测统计大盘

GET /api/admin/telemetry/:slug/stats
Authorization: Bearer <jwt>

分页查询遥测设备列表

GET /api/admin/telemetry/:slug/devices?page=1&size=50&q=&blocked=false
Authorization: Bearer <jwt>

获取产品特定行为统计

GET /api/admin/telemetry/:slug/behaviors?days=30
Authorization: Bearer <jwt>

封禁/解封产品设备

POST /api/admin/telemetry/:slug/devices/block
POST /api/admin/telemetry/:slug/devices/unblock
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "device_id": "device-123",
  "reason": "违规使用",
  "message": "此设备已被封禁",
  "until": 1720000000
}

获取/保存单个设备云控配置

GET /api/admin/telemetry/:slug/devices/:device_id/config
POST /api/admin/telemetry/:slug/devices/config
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "device_id": "device-123",
  "feature_toggles": {
    "feature_a": false
  }
}

RSA 密钥工具

生成新密钥对

POST /api/admin/keys/gen
Authorization: Bearer <jwt>

响应：

{
  "private_key": "-----BEGIN PRIVATE KEY-----\n...",
  "public_key": "-----BEGIN PUBLIC KEY-----\n..."
}

从私钥提取公钥

POST /api/admin/keys/extract
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "private_key": "-----BEGIN PRIVATE KEY-----\n..."
}

根据产品推导公钥（免脱敏私钥）

GET /api/admin/keys/public?slug=<product_slug>
Authorization: Bearer <jwt>

响应：

{
  "public_key": "-----BEGIN PUBLIC KEY-----\n..."
}

错误响应

{
  "message": "错误描述"
}

HTTP 状态码：

  • 400: 请求参数错误
  • 401: 未认证/认证失败
  • 404: 资源不存在
  • 429: 请求过于频繁（登录速率限制）
  • 500: 服务器内部错误
  • 503: 系统未配置