快速开始¶

闲沐工坊数据服务平台为电子墨水屏/小屏设备提供统一的数据取数网关：设备一次接入，即可消费平台上的彩票开奖、整点新闻播报、电台收听等数据源；开发者按插件规范即可上线新数据源。

本页帮助你用 10 分钟 走通：注册账号 → 绑定设备 → 订阅数据源 → 设备出数据。

1. 平台组成¶

组成	入口	说明
数据网关	`GET /api/v1/data/{source_code}`	设固件唯一取数路径（统一响应/错误码）
用户中心	`/portal/`	注册登录、设备绑定、订阅、用量
文档站	`/handbook/`（本站）	接入手册与数据源目录
调试	`/docs`（Swagger，需 `ENABLE_DOCS=true`）	OpenAPI 调试补充，生产默认关闭，对外接口以本站为准

管理后台仅对管理员开放，入口不在公开文档披露；运营能力（账号、订阅、公告）对用户的可见面是用户中心与本站。

2. 用户：绑定设备并取数¶

注册/登录 用户中心 /portal/：邮箱即账号（开启邮箱验证时需 6 位邮箱验证码）；
绑定设备：输入设备 SN 发起绑定，在设备屏幕读取 6 位确认码回填网页（5 分钟有效、一次即焚）；
订阅数据源：在「数据源订阅」页开通需要的源（如 lottery_ssq 双色球）；
设备开机后自动拉取源清单并轮询取数。

流程细节（激活与心跳、确认码状态机、绑定上限、老账号兼容等）见设备接入手册。

3. 开发者：上线一个新数据源¶

新数据源上线四步：继承基类 → 放入 plugins/ → 后台审核 → 上线，全程不改框架代码、不重启服务、不升级设备固件。详见插件开发指南。

# plugins/my_source/__init__.py 最小骨架
from app.core.plugins.base import BaseDataSource

class MySource(BaseDataSource):
    source_code = "my_source"
    name = "我的数据源"
    source_name = "数据来自 ……，仅供信息展示"

    def meta(self): ...

    async def fetch(self, params): ...

DATASOURCE = MySource

4. 30 秒体验（curl）¶

# 设备激活（换 Token）
curl -X POST https://api.wwzu.com/api/v1/device/activate \
  -H 'Content-Type: application/json' \
  -d '{"sn":"XMBOX-2026-000001","model":"xmbox_v1","fw_version":"1.0.3","activation_key":"<出厂密钥>"}'

# 取双色球最新开奖
curl "https://api.wwzu.com/api/v1/data/lottery_ssq" \
  -H 'X-Device-SN: XMBOX-2026-000001' \
  -H 'X-Device-Token: <device_token>'

成功响应（统一信封）：

{
  "code": 0,
  "msg": "success",
  "data": {
    "source": "lottery_ssq",
    "version": "v1",
    "updated_at": "2026-08-30 21:35:00",
    "stale": false,
    "payload": {
      "period": "2026098",
      "date": "2026-08-30",
      "red": [3, 9, 14, 22, 26, 31],
      "blue": 11,
      "pool_amount": "",
      "sale_period": "2026102",
      "source_name": "数据来自中国福利彩票官网，仅供信息展示，不构成任何投注建议"
    }
  },
  "server_time": 1788000000
}

5. 约定速览¶

全站 HTTPS；所有接口前缀 /api/v1；
设备鉴权：请求头 X-Device-SN + X-Device-Token；用户/管理端：Authorization: Bearer <access_token>；
code 是设备端唯一判断依据，HTTP 状态码与错误码族对齐（错误码总表见设备接入手册）；
时间一律北京时间 YYYY-MM-DD HH:mm:ss；server_time 为秒级 Unix 时间戳。