{"openapi":"3.1.0","info":{"title":"MControl Open API","version":"0.2.0","description":"MControl 物联平台的开放接口。控制台里的每个动作都是同一套 API。\n\n## 鉴权\n- **API Key**（推荐给第三方系统）：`Authorization: Bearer <accessKey>.<secret>`，在控制台「设置 → API Key」创建；权限点与范围与成员一致，可设 IP 白名单与有效期。连续 20 次 403 会冻结。\n- **登录会话**：浏览器 Cookie（控制台自己用）。\n- **设备凭证**（仅 `/api/device/v1/*`）：`X-Device-Key` + `X-Device-Secret`。\n\n## 约定\n- 时间一律 ISO 8601（UTC）；分页 `page` / `pageSize`；错误体 `{ code, message, requestId }`。\n- 所有列表 / 详情都按调用者的权限范围过滤：看不到的设备就像不存在（404）。\n- 实时数据：WebSocket `/ws?ticket=…`（`POST /api/v1/ws-ticket` 换票据），或订阅 Webhook；也可用 API Key 作为 MQTT 订阅凭证直接订阅 `/{productKey}/+/thing/property/post`。\n\n## 20 行 Python 拉昨日读数\n```python\nimport requests, csv, io\nBASE = \"https://mcontrol.onenata.app\"\nKEY = \"mck_xxx.yyy\"  # 控制台创建的 API Key（readonly 模板即可）\nr = requests.get(f\"{BASE}/api/v1/telemetry/export\",\n                 params={\"range\": \"yesterday\", \"agg\": \"1h\", \"props\": \"energy,voltage_a\"},\n                 headers={\"Authorization\": f\"Bearer {KEY}\"}, timeout=60)\nr.raise_for_status()\nfor row in csv.DictReader(io.StringIO(r.content.decode('utf-8-sig'))):\n    print(row[\"bucket\"], row[\"device\"], row[\"prop\"], row[\"avg\"])\n```","contact":{"name":"MControl","email":"support@onenata.ca"}},"servers":[{"url":"https://mcontrol.onenata.app"}],"tags":[{"name":"设备","description":"设备注册、详情、历史数据、指令、影子、批量操作"},{"name":"产品","description":"产品与物模型（TSL）、解析脚本"},{"name":"空间","description":"空间树"},{"name":"数据导出","description":"遥测 / 告警 / 设备清单 CSV，定时导出任务"},{"name":"规则与告警","description":"规则引擎（阈值 / 离线 / 事件，组合条件、防抖、静默）、告警状态机与指派、异常示警"},{"name":"通知与 Webhook","description":"邮件 / 企业微信 / 钉钉 / 飞书 / Webhook 通知渠道；事件 Webhook 订阅"},{"name":"看板","description":"看板、批量取数、公开分享与嵌入"},{"name":"组织","description":"API Key、当前用户、审计"},{"name":"系统","description":"健康检查与本文档"},{"name":"设备侧 HTTP","description":"设备用设备凭证调用的接口（上报 / 取指令 / 传图）"}],"paths":{"/api/v1/devices":{"get":{"tags":["设备"],"summary":"设备列表","description":"按访问者的 device:read 范围过滤；支持搜索、状态 / 产品 / 空间筛选、排序、分页。\n\n需要权限点：`device:read`","parameters":[{"name":"page","in":"query","description":"页码，从 1 开始","schema":{"type":"integer"}},{"name":"pageSize","in":"query","description":"每页条数（≤ 200）","schema":{"type":"integer"}},{"name":"q","in":"query","description":"名称 / DeviceKey 模糊搜索","schema":{"type":"string"}},{"name":"status","in":"query","description":"状态","schema":{"type":"string","enum":["UNACTIVATED","ONLINE","OFFLINE","SLEEPING","DISABLED"]}},{"name":"productId","in":"query","description":"产品 id","schema":{"type":"string"}},{"name":"spaceId","in":"query","description":"空间 id（含子树）","schema":{"type":"string"}},{"name":"sort","in":"query","description":"排序列","schema":{"type":"string","enum":["name","status","lastSeenAt","createdAt"]}},{"name":"dir","in":"query","description":"asc | desc","schema":{"type":"string"}}],"responses":{"200":{"description":"分页列表","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Page"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Device"}},"summary":{"type":"object","properties":{},"description":"按状态计数"}}}]}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"post":{"tags":["设备"],"summary":"注册设备","description":"返回三元组与四份示例代码；**Secret 只返回这一次**。\n\n需要权限点：`device:create`","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceCreate"}}}},"responses":{"201":{"description":"已创建","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceCreated"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"DeviceKey 已被占用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/devices/{id}":{"get":{"tags":["设备"],"summary":"设备详情","description":"含影子（需 device:shadow.read）、最近 50 条事件、最近 20 条指令与当前访问者的权限位。\n\n需要权限点：`device:read`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"responses":{"200":{"description":"设备","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Device"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"不存在或不可见","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"patch":{"tags":["设备"],"summary":"修改设备","description":"需要权限点：`device:update`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"spaceId":{"type":"string"},"tags":{"type":"object","properties":{}},"status":{"type":"string","enum":["DISABLED","OFFLINE"],"description":"DISABLED 禁用 / OFFLINE 启用"}}}}}},"responses":{"200":{"description":"设备","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Device"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"delete":{"tags":["设备"],"summary":"删除设备","description":"需要权限点：`device:delete`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/devices/{id}/telemetry":{"get":{"tags":["设备"],"summary":"历史数据","description":"跨度 < 6h 返回原始点；< 3d 按 1 分钟、< 60d 按 1 小时、其余按 1 天聚合（avg / min / max / n），可用 agg 强制。\n\n需要权限点：`device:history.read`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}},{"name":"props","in":"query","description":"属性标识符，逗号分隔；空 = 全部","schema":{"type":"string"}},{"name":"from","in":"query","description":"ISO 时间；默认 to − 24h","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"ISO 时间；默认现在","schema":{"type":"string","format":"date-time"}},{"name":"agg","in":"query","description":"auto | raw | 1m | 1h | 1d","schema":{"type":"string"}},{"name":"limit","in":"query","description":"最多返回行数（≤ 10000）","schema":{"type":"integer"}}],"responses":{"200":{"description":"序列","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Telemetry"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/devices/{id}/events":{"get":{"tags":["设备"],"summary":"事件流","description":"上下线、告警、物模型事件；raw=1 时附最近 50 条原始报文（需 device:raw.read）。\n\n需要权限点：`device:history.read`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}},{"name":"limit","in":"query","description":"≤ 500","schema":{"type":"integer"}},{"name":"raw","in":"query","description":"1 = 附原始报文","schema":{"type":"string"}}],"responses":{"200":{"description":"事件","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/DeviceEvent"}}}}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/devices/{id}/commands":{"get":{"tags":["设备"],"summary":"指令历史","description":"需要权限点：`device:read`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"responses":{"200":{"description":"指令","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Command"}}}}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"post":{"tags":["设备"],"summary":"调用服务（下发指令）","description":"写入指令队列，设备在线立即下发，离线则上线后补发；物模型标记 critical 的服务需 device:control.critical 且必须填 reason。\n\n需要权限点：`device:control.invoke` 或 `device:control.critical`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommandCreate"}}}},"responses":{"201":{"description":"已入队","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Command"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/devices/{id}/shadow":{"get":{"tags":["设备"],"summary":"设备影子","description":"需要权限点：`device:shadow.read`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"responses":{"200":{"description":"影子","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shadow"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"patch":{"tags":["设备"],"summary":"写期望值","description":"只允许物模型 access=rw 的属性，按量程校验；设备在线即下发 shadow/desired（retained），离线上线后补发。\n\n需要权限点：`device:config.write`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"desired":{"type":"object","properties":{}},"clear":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"影子","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shadow"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/devices/bulk":{"post":{"tags":["设备"],"summary":"批量操作","description":"禁用 / 启用 / 移动空间 / 删除，只对权限范围内的设备生效，其余计入 skipped。\n\n需要权限点：`device:update` 或 `device:delete`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["disable","enable","move","delete"]},"ids":{"type":"array","items":{"type":"string"}},"spaceId":{"type":"string","description":"move 时的目标空间；null = 移出"}},"required":["action","ids"]}}}},"responses":{"200":{"description":"结果","content":{"application/json":{"schema":{"type":"object","properties":{"affected":{"type":"integer"},"skipped":{"type":"integer"}}}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/devices/export":{"get":{"tags":["设备"],"summary":"导出设备清单（CSV）","description":"跟随列表筛选，最多 5000 行。\n\n需要权限点：`device:read`","parameters":[{"name":"q","in":"query","description":"搜索","schema":{"type":"string"}},{"name":"status","in":"query","description":"状态","schema":{"type":"string"}},{"name":"productId","in":"query","description":"产品","schema":{"type":"string"}},{"name":"spaceId","in":"query","description":"空间","schema":{"type":"string"}}],"responses":{"200":{"description":"CSV（带 BOM）","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/devices/import":{"post":{"tags":["设备"],"summary":"CSV 批量导入","description":"dryRun=true 只预检；正式导入返回每行结果与一次性凭证。\n\n需要权限点：`device:create`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"productId":{"type":"string"},"csv":{"type":"string","description":"CSV 文本：name,deviceKey,space,tags…"},"dryRun":{"type":"boolean"}},"required":["productId","csv"]}}}},"responses":{"200":{"description":"导入结果","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"created":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"integer"},"message":{"type":"string"}}}},"credentials":{"type":"array","items":{"type":"object","properties":{"deviceKey":{"type":"string"},"secret":{"type":"string"}}}}}}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/products":{"get":{"tags":["产品"],"summary":"产品列表","description":"需要权限点：`product:read`","responses":{"200":{"description":"列表","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"post":{"tags":["产品"],"summary":"创建产品","description":"需要权限点：`product:create`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"category":{"type":"string"},"nodeType":{"type":"string","enum":["DIRECT","GATEWAY","SUBDEVICE"]},"protocol":{"type":"string","enum":["MQTT","HTTP","COAP","MODBUS_GATEWAY","IMAGE_UPLOAD","CLOUD"]},"authMode":{"type":"string","enum":["KEY_SECRET","X509","DYNAMIC"]},"tsl":{"$ref":"#/components/schemas/Tsl"},"useGenericTsl":{"type":"boolean"},"offlineAfterSec":{"type":"integer"},"description":{"type":"string"}},"required":["name"]}}}},"responses":{"201":{"description":"产品","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/products/{id}":{"get":{"tags":["产品"],"summary":"产品详情（含物模型）","description":"需要权限点：`product:read`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"responses":{"200":{"description":"产品","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"patch":{"tags":["产品"],"summary":"修改产品 / 物模型 / 解析脚本","description":"需要权限点：`product:update` 或 `product:tsl.edit` 或 `product:script.edit`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"category":{"type":"string"},"offlineAfterSec":{"type":"integer"},"description":{"type":"string"},"tsl":{"$ref":"#/components/schemas/Tsl"},"codecScript":{"type":"string"}}}}}},"responses":{"200":{"description":"产品","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"delete":{"tags":["产品"],"summary":"删除产品（须无设备）","description":"需要权限点：`product:delete`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/spaces":{"get":{"tags":["空间"],"summary":"空间树（扁平列表，按 parentId 组树）","description":"需要权限点：`space:read`","responses":{"200":{"description":"列表","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Space"}}}}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"post":{"tags":["空间"],"summary":"创建空间","description":"需要权限点：`space:create`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parentId":{"type":"string"}},"required":["name"]}}}},"responses":{"201":{"description":"空间","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Space"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/spaces/{id}":{"patch":{"tags":["空间"],"summary":"重命名 / 移动","description":"需要权限点：`space:update`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parentId":{"type":"string","description":"移动到…（整棵子树 path 改写）"}}}}}},"responses":{"200":{"description":"空间","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Space"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"delete":{"tags":["空间"],"summary":"删除空间","description":"需要权限点：`space:delete`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}},{"name":"moveDevicesTo","in":"query","description":"设备迁到的空间 id","schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/telemetry/export":{"get":{"tags":["数据导出"],"summary":"导出遥测（CSV）","description":"第三方拉「昨日读数」的推荐接口：`?range=yesterday&agg=1h`。范围只含 device:history.read 可见设备；≤ 24h 默认原始点，≤ 7d 按小时，其余按天。最多 200000 行（响应头 X-Truncated=1 表示截断）。\n\n需要权限点：`export:data.export`","parameters":[{"name":"deviceIds","in":"query","description":"设备 id，逗号分隔","schema":{"type":"string"}},{"name":"spaceId","in":"query","description":"空间（含子树）","schema":{"type":"string"}},{"name":"productId","in":"query","description":"产品","schema":{"type":"string"}},{"name":"tag","in":"query","description":"标签 key:value","schema":{"type":"string"}},{"name":"props","in":"query","description":"属性标识符，逗号分隔；空 = 全部","schema":{"type":"string"}},{"name":"range","in":"query","description":"时间范围","schema":{"type":"string","enum":["last1h","last24h","yesterday","last7d","lastWeek","last30d","lastMonth"]}},{"name":"agg","in":"query","description":"auto | raw | 1m | 1h | 1d","schema":{"type":"string"}}],"responses":{"200":{"description":"CSV（带 BOM）：bucket/time, device, deviceKey, space, prop, avg|value, min, max, last, n","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/exports":{"get":{"tags":["数据导出"],"summary":"导出任务列表","description":"需要权限点：`export:report.generate`","responses":{"200":{"description":"列表","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ExportJob"}}}}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"post":{"tags":["数据导出"],"summary":"创建导出任务（可定时）","description":"schedule = daily / weekly / monthly 时按 Workspace 时区的 hour 点自动运行，产物存对象存储 30 天，可推送到通知渠道（邮件附下载链接）。\n\n需要权限点：`export:data.export`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["telemetry","alarms","devices"]},"params":{"type":"object","properties":{"scope":{"$ref":"#/components/schemas/RuleScope"},"props":{"type":"array","items":{"type":"string"}},"range":{"type":"string"},"agg":{"type":"string"},"status":{"type":"string"}}},"schedule":{"type":"string","enum":["daily","weekly","monthly"]},"hour":{"type":"integer"},"channelIds":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"}},"required":["name","kind","params"]}}}},"responses":{"201":{"description":"任务","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportJob"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/exports/{id}":{"patch":{"tags":["数据导出"],"summary":"修改导出任务","description":"需要权限点：`export:data.export`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"params":{"type":"object","properties":{}},"schedule":{"type":"string"},"hour":{"type":"integer"},"channelIds":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"任务","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportJob"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"delete":{"tags":["数据导出"],"summary":"删除导出任务","description":"需要权限点：`export:data.export`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/exports/{id}/run":{"post":{"tags":["数据导出"],"summary":"立即运行","description":"需要权限点：`export:report.generate`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"responses":{"200":{"description":"运行记录","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportRun"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/exports/{id}/runs":{"get":{"tags":["数据导出"],"summary":"运行历史","description":"需要权限点：`export:report.generate`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}},{"name":"limit","in":"query","description":"≤ 100","schema":{"type":"integer"}}],"responses":{"200":{"description":"列表","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ExportRun"}}}}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/exports/runs/{runId}/download":{"get":{"tags":["数据导出"],"summary":"下载产物","description":"需要权限点：`export:report.generate`","parameters":[{"name":"runId","in":"path","required":true,"description":"运行 id","schema":{"type":"string"}}],"responses":{"200":{"description":"CSV","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"产物已过期","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/events":{"get":{"tags":["数据导出"],"summary":"全域最近事件（7 天）","description":"需要权限点：`device:history.read`","parameters":[{"name":"limit","in":"query","description":"≤ 200","schema":{"type":"integer"}}],"responses":{"200":{"description":"事件","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/DeviceEvent"}}}}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/stats":{"get":{"tags":["数据导出"],"summary":"总览 KPI","description":"需要权限点：`device:read`","responses":{"200":{"description":"KPI","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Stats"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/venues":{"get":{"tags":["场馆经营"],"summary":"场馆收费标准列表","description":"只返回当前用户可见空间上的场馆（与 3D 园区同一套空间范围）。\n\n需要权限点：`space:read`","responses":{"200":{"description":"列表 + 电价","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Venue"}},"tariff":{"$ref":"#/components/schemas/VenueTariff"}}}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/venues/overview":{"get":{"tags":["场馆经营"],"summary":"经营总览（首页「经营」区）","description":"每个场馆的今日预定情况、当月 / 预计收入；总进线电表推算的当月 / 预计用电与电费；能耗占收入比。口径见各字段说明。\n\n需要权限点：`space:read`","responses":{"200":{"description":"总览","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VenueOverview"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/venues/tariff":{"get":{"tags":["场馆经营"],"summary":"电价","description":"需要权限点：`workspace:read`","responses":{"200":{"description":"电价","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VenueTariff"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"put":{"tags":["场馆经营"],"summary":"设置电价","description":"需要权限点：`workspace:update`","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VenueTariff"}}}},"responses":{"200":{"description":"电价","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VenueTariff"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/venues/{spaceId}":{"get":{"tags":["场馆经营"],"summary":"某空间的收费标准","description":"需要权限点：`space:read`","parameters":[{"name":"spaceId","in":"path","required":true,"description":"空间 id","schema":{"type":"string"}}],"responses":{"200":{"description":"场馆","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Venue"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"空间不存在或没有设置收费","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"put":{"tags":["场馆经营"],"summary":"设置 / 修改收费标准（按空间 upsert）","description":"需要权限点：`space:update`","parameters":[{"name":"spaceId","in":"path","required":true,"description":"空间 id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VenueInput"}}}},"responses":{"200":{"description":"已更新","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Venue"}}}},"201":{"description":"已创建","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Venue"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"delete":{"tags":["场馆经营"],"summary":"取消对外收费（预定一并删除）","description":"需要权限点：`space:update`","parameters":[{"name":"spaceId","in":"path","required":true,"description":"空间 id","schema":{"type":"string"}}],"responses":{"200":{"description":"结果","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"bookingsDeleted":{"type":"integer"}}}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/venues/{spaceId}/bookings":{"get":{"tags":["场馆经营"],"summary":"预定列表","description":"需要权限点：`space:read`","parameters":[{"name":"spaceId","in":"path","required":true,"description":"空间 id","schema":{"type":"string"}},{"name":"from","in":"query","description":"开始时间 ≥（默认本月初）","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"开始时间 <（默认下月初）","schema":{"type":"string","format":"date-time"}},{"name":"status","in":"query","description":"confirmed | completed | cancelled | all（默认不含已取消）","schema":{"type":"string"}}],"responses":{"200":{"description":"列表","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Booking"}},"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"post":{"tags":["场馆经营"],"summary":"新建预定","description":"单元数不能超过场馆容量；同一时段已订单元 + 本次 > 容量返回 409。\n\n需要权限点：`space:update`","parameters":[{"name":"spaceId","in":"path","required":true,"description":"空间 id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingInput"}}}},"responses":{"201":{"description":"预定","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"该时段已订满","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/venues/{spaceId}/bookings/{id}":{"get":{"tags":["场馆经营"],"summary":"预定详情","description":"需要权限点：`space:read`","parameters":[{"name":"spaceId","in":"path","required":true,"description":"空间 id","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"预定 id","schema":{"type":"string"}}],"responses":{"200":{"description":"预定","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"patch":{"tags":["场馆经营"],"summary":"改状态（取消 / 完成）、金额、客户、备注","description":"需要权限点：`space:update`","parameters":[{"name":"spaceId","in":"path","required":true,"description":"空间 id","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"预定 id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["CONFIRMED","COMPLETED","CANCELLED"]},"amount":{"type":"number"},"customer":{"type":"string"},"note":{"type":"string"}}}}}},"responses":{"200":{"description":"预定","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"delete":{"tags":["场馆经营"],"summary":"删除预定","description":"需要权限点：`space:update`","parameters":[{"name":"spaceId","in":"path","required":true,"description":"空间 id","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"预定 id","schema":{"type":"string"}}],"responses":{"200":{"description":"结果","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/rules":{"get":{"tags":["规则与告警"],"summary":"规则列表","description":"需要权限点：`rule:read`","responses":{"200":{"description":"列表","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Rule"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}}}}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"post":{"tags":["规则与告警"],"summary":"创建规则","description":"范围不能超出创建者自己的权限范围（全域 / 产品 / 标签范围需要 WORKSPACE 级 rule:create）。条件组 and / or 一层；防抖、静默、自动恢复见字段说明。\n\n需要权限点：`rule:create`","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuleInput"}}}},"responses":{"201":{"description":"规则","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rule"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/rules/{id}":{"get":{"tags":["规则与告警"],"summary":"规则详情","description":"需要权限点：`rule:read`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"responses":{"200":{"description":"规则","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rule"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"patch":{"tags":["规则与告警"],"summary":"修改规则","description":"需要权限点：`rule:update`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuleInput"}}}},"responses":{"200":{"description":"规则","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rule"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"delete":{"tags":["规则与告警"],"summary":"删除规则（其未关闭告警一并关闭）","description":"需要权限点：`rule:delete`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"responses":{"200":{"description":"结果","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"closedAlarms":{"type":"integer"}}}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/rules/{id}/enable":{"post":{"tags":["规则与告警"],"summary":"启用 / 禁用规则","description":"需要权限点：`rule:enable`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]}}}},"responses":{"200":{"description":"成功"},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/rules/templates":{"get":{"tags":["规则与告警"],"summary":"预置规则模板","description":"需要权限点：`rule:read`","responses":{"200":{"description":"模板","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"rule":{"$ref":"#/components/schemas/RuleInput"}}}}}}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/rules/preview":{"post":{"tags":["规则与告警"],"summary":"规则预演","description":"用范围内设备的当前状态 / 影子跑一遍条件，返回此刻会命中的设备（不保存、不触发通知）。\n\n需要权限点：`rule:read`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"$ref":"#/components/schemas/RuleScope"},"conditions":{"$ref":"#/components/schemas/RuleConditions"}},"required":["scope","conditions"]}}}},"responses":{"200":{"description":"预演结果","content":{"application/json":{"schema":{"type":"object","properties":{"devices":{"type":"integer"},"matchedCount":{"type":"integer"},"unknown":{"type":"integer","description":"事件类条件无法在预演中判断的设备数"},"matched":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"deviceKey":{"type":"string"},"matched":{"type":"array","items":{"type":"object","properties":{}}}}}}}}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/alarms":{"get":{"tags":["规则与告警"],"summary":"告警列表","description":"只返回设备在 alarm:read 范围内的告警。\n\n需要权限点：`alarm:read`","parameters":[{"name":"status","in":"query","description":"active | acked | open（默认）| resolved | all","schema":{"type":"string"}},{"name":"severity","in":"query","description":"info | warn | critical","schema":{"type":"string"}},{"name":"ruleId","in":"query","description":"规则","schema":{"type":"string"}},{"name":"deviceId","in":"query","description":"设备","schema":{"type":"string"}},{"name":"assignee","in":"query","description":"me | none | <userId>","schema":{"type":"string"}},{"name":"q","in":"query","description":"标题 / 设备搜索","schema":{"type":"string"}},{"name":"from","in":"query","description":"触发时间 ≥","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"触发时间 ≤","schema":{"type":"string","format":"date-time"}},{"name":"page","in":"query","description":"页码，从 1 开始","schema":{"type":"integer"}},{"name":"pageSize","in":"query","description":"每页条数（≤ 200）","schema":{"type":"integer"}},{"name":"sort","in":"query","description":"firedAt | severity | status | device | lastSeenAt","schema":{"type":"string"}},{"name":"dir","in":"query","description":"asc | desc","schema":{"type":"string"}}],"responses":{"200":{"description":"分页列表","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Page"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Alarm"}}}}]}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/alarms/summary":{"get":{"tags":["规则与告警"],"summary":"告警汇总（铃铛 / 总览）","description":"需要权限点：`alarm:read`","parameters":[{"name":"anomalies","in":"query","description":"0 = 不带异常扫描汇总","schema":{"type":"string"}}],"responses":{"200":{"description":"汇总","content":{"application/json":{"schema":{"type":"object","properties":{"alarms":{"type":"object","properties":{"active":{"type":"integer"},"acked":{"type":"integer"},"open":{"type":"integer"},"critical":{"type":"integer"},"warn":{"type":"integer"},"info":{"type":"integer"},"mine":{"type":"integer"}}},"anomalies":{"type":"object","properties":{"critical":{"type":"integer"},"warn":{"type":"integer"},"info":{"type":"integer"},"total":{"type":"integer"}}},"attention":{"type":"integer","description":"需要关注的数量：待处理告警 + 严重 / 警告异常"}}}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/alarms/{id}":{"get":{"tags":["规则与告警"],"summary":"告警详情 + 时间线","description":"需要权限点：`alarm:read`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"responses":{"200":{"description":"告警","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Alarm"},{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/AlarmEvent"}}}}]}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/alarms/{id}/ack":{"post":{"tags":["规则与告警"],"summary":"确认 / 取消确认","description":"需要权限点：`alarm:ack`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"acked":{"type":"boolean","description":"默认 true"},"note":{"type":"string"}}}}}},"responses":{"200":{"description":"告警","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Alarm"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/alarms/{id}/resolve":{"post":{"tags":["规则与告警"],"summary":"人工关闭","description":"条件仍成立时规则引擎会再开一条新告警。\n\n需要权限点：`alarm:resolve`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string"}}}}}},"responses":{"200":{"description":"告警","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Alarm"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/alarms/{id}/assign":{"post":{"tags":["规则与告警"],"summary":"指派","description":"需要权限点：`alarm:assign`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assigneeId":{"type":"string","description":"成员 userId；null = 取消指派"}},"required":["assigneeId"]}}}},"responses":{"200":{"description":"告警","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Alarm"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/alarms/{id}/comment":{"post":{"tags":["规则与告警"],"summary":"备注","description":"需要权限点：`alarm:ack`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string"}},"required":["note"]}}}},"responses":{"200":{"description":"时间线","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/AlarmEvent"}}}}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/alarms/bulk":{"post":{"tags":["规则与告警"],"summary":"批量确认 / 关闭 / 指派","description":"需要权限点：`alarm:ack` 或 `alarm:resolve` 或 `alarm:assign`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["ack","resolve","assign"]},"ids":{"type":"array","items":{"type":"string"}},"note":{"type":"string"},"assigneeId":{"type":"string"}},"required":["action","ids"]}}}},"responses":{"200":{"description":"结果","content":{"application/json":{"schema":{"type":"object","properties":{"affected":{"type":"integer"},"skipped":{"type":"integer"}}}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/alarms/export":{"get":{"tags":["规则与告警"],"summary":"导出告警记录（CSV）","description":"需要权限点：`export:report.generate`","parameters":[{"name":"range","in":"query","description":"时间范围","schema":{"type":"string","enum":["last1h","last24h","yesterday","last7d","lastWeek","last30d","lastMonth"]}},{"name":"status","in":"query","description":"all | open | resolved","schema":{"type":"string"}}],"responses":{"200":{"description":"CSV","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/alarms/history":{"get":{"tags":["规则与告警"],"summary":"告警 / 异常历史（设备事件，30 天）","description":"需要权限点：`alarm:read`","parameters":[{"name":"severity","in":"query","description":"critical | warn | info","schema":{"type":"string"}},{"name":"kind","in":"query","description":"异常类型","schema":{"type":"string"}},{"name":"deviceId","in":"query","description":"设备","schema":{"type":"string"}},{"name":"before","in":"query","description":"游标：上一页最后一条的 time","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","description":"≤ 200","schema":{"type":"integer"}}],"responses":{"200":{"description":"事件","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/DeviceEvent"}},"nextBefore":{"type":"string","format":"date-time"}}}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/ai/anomalies":{"get":{"tags":["规则与告警"],"summary":"异常示警报告（规则扫描：离线 / 无上报 / 超量程 / 电量 / 信号 / 突变 / 平线）","description":"需要权限点：`alarm:read`","parameters":[{"name":"fresh","in":"query","description":"1 = 即时扫描","schema":{"type":"string"}},{"name":"summary","in":"query","description":"1 = 只返回汇总","schema":{"type":"string"}},{"name":"hours","in":"query","description":"序列窗口（小时）","schema":{"type":"number"}}],"responses":{"200":{"description":"报告","content":{"application/json":{"schema":{"type":"object","properties":{"scannedAt":{"type":"string","format":"date-time"},"devicesScanned":{"type":"integer"},"anomalies":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"severity":{"type":"string"},"deviceId":{"type":"string"},"deviceName":{"type":"string"},"prop":{"type":"string"},"value":{"type":"number"},"message":{"type":"string"},"since":{"type":"string","format":"date-time"}}}},"summary":{"type":"object","properties":{"total":{"type":"integer"},"critical":{"type":"integer"},"warn":{"type":"integer"},"info":{"type":"integer"}}}}}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/channels":{"get":{"tags":["通知与 Webhook"],"summary":"通知渠道列表","description":"需要权限点：`rule:read`","responses":{"200":{"description":"列表","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}}}}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"post":{"tags":["通知与 Webhook"],"summary":"创建通知渠道","description":"需要权限点：`rule:update`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["email","wecom","dingtalk","feishu","webhook"]},"config":{"type":"object","properties":{}},"enabled":{"type":"boolean"}},"required":["name","type","config"]}}}},"responses":{"201":{"description":"渠道","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Channel"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/channels/{id}":{"patch":{"tags":["通知与 Webhook"],"summary":"修改通知渠道","description":"需要权限点：`rule:update`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"config":{"type":"object","properties":{}},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"渠道","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Channel"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"delete":{"tags":["通知与 Webhook"],"summary":"删除通知渠道（自动从规则中移除）","description":"需要权限点：`rule:update`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/channels/{id}/test":{"post":{"tags":["通知与 Webhook"],"summary":"发送测试消息","description":"需要权限点：`rule:update`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"responses":{"200":{"description":"结果","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"status":{"type":"integer"},"error":{"type":"string"}}}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/webhooks":{"get":{"tags":["通知与 Webhook"],"summary":"Webhook 订阅列表","description":"需要权限点：`apikey:read`","responses":{"200":{"description":"列表","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"events":{"type":"array","items":{"type":"string"}}}}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"post":{"tags":["通知与 Webhook"],"summary":"创建 Webhook 订阅","description":"签名密钥只在这次响应里返回。事件推送体见 WebhookPayload；失败按 10s / 60s / 5min 重试 3 次，连续失败 100 次自动停用。\n\n需要权限点：`apikey:create`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["device.online","device.offline","device.property","device.event","command.updated","alarm.fired","alarm.acked","alarm.resolved"]}},"scope":{"$ref":"#/components/schemas/RuleScope"},"headers":{"type":"object","properties":{}},"enabled":{"type":"boolean"}},"required":["name","url","events"]}}}},"responses":{"201":{"description":"订阅（含 secret）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/webhooks/{id}":{"get":{"tags":["通知与 Webhook"],"summary":"订阅详情","description":"需要权限点：`apikey:read`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"responses":{"200":{"description":"订阅","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"patch":{"tags":["通知与 Webhook"],"summary":"修改订阅","description":"需要权限点：`apikey:create`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"scope":{"$ref":"#/components/schemas/RuleScope"},"headers":{"type":"object","properties":{}},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"订阅","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"delete":{"tags":["通知与 Webhook"],"summary":"删除订阅","description":"需要权限点：`apikey:revoke`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/webhooks/{id}/test":{"post":{"tags":["通知与 Webhook"],"summary":"发送 ping","description":"需要权限点：`apikey:create`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"responses":{"200":{"description":"结果","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"status":{"type":"integer"},"error":{"type":"string"},"deliveryId":{"type":"string"}}}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/webhooks/{id}/deliveries":{"get":{"tags":["通知与 Webhook"],"summary":"投递记录（最近 200 条）","description":"需要权限点：`apikey:read`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}},{"name":"limit","in":"query","description":"≤ 200","schema":{"type":"integer"}}],"responses":{"200":{"description":"列表","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}}}}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/dashboards":{"get":{"tags":["看板"],"summary":"看板列表","description":"需要权限点：`dashboard:read`","responses":{"200":{"description":"列表","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Dashboard"}}}}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"post":{"tags":["看板"],"summary":"创建看板","description":"需要权限点：`dashboard:create`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"template":{"type":"string","description":"device_overview = 设备总览模板"},"layout":{"type":"object","properties":{}},"theme":{"type":"string"},"rotateSec":{"type":"integer"}},"required":["name"]}}}},"responses":{"201":{"description":"看板","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dashboard"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/dashboards/{id}":{"get":{"tags":["看板"],"summary":"看板详情","description":"需要权限点：`dashboard:read`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"responses":{"200":{"description":"看板","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dashboard"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"patch":{"tags":["看板"],"summary":"保存布局（乐观锁 version）","description":"需要权限点：`dashboard:update`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"layout":{"type":"object","properties":{}},"theme":{"type":"string"},"rotateSec":{"type":"integer"},"version":{"type":"integer"}}}}}},"responses":{"200":{"description":"看板","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dashboard"}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"版本冲突","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"delete":{"tags":["看板"],"summary":"删除看板","description":"需要权限点：`dashboard:delete`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/dashboards/data":{"post":{"tags":["看板"],"summary":"批量取数","description":"一次刷新一个请求；每个查询独立出错不影响其它；范围叠加访问者授权。\n\n需要权限点：`dashboard:read`","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardDataRequest"}}}},"responses":{"200":{"description":"结果","content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"results":{"type":"object","properties":{},"description":"{ [queryId]: 数据 }"}}}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/dashboards/{id}/shares":{"get":{"tags":["看板"],"summary":"分享链接列表","description":"需要权限点：`dashboard:share.public`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"post":{"tags":["看板"],"summary":"创建公开分享 / 嵌入链接","description":"返回 /present/share/{token}；加 `?embed=1` 得到无边框版本，可放进 `<iframe>`。\n\n需要权限点：`dashboard:share.public`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"password":{"type":"string","description":"可选，≥ 4 位"},"expiresInDays":{"type":"integer","description":"null = 永久"}}}}}},"responses":{"201":{"description":"链接","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"token":{"type":"string"},"url":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"hasPassword":{"type":"boolean"}}}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"delete":{"tags":["看板"],"summary":"撤销分享","description":"需要权限点：`dashboard:share.public`","parameters":[{"name":"id","in":"path","required":true,"description":"资源 id","schema":{"type":"string"}},{"name":"shareId","in":"query","description":"分享 id","schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/api-keys":{"get":{"tags":["组织"],"summary":"API Key 列表","description":"需要权限点：`apikey:read`","responses":{"200":{"description":"列表","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}}}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]},"post":{"tags":["组织"],"summary":"创建 API Key（仅登录会话可调）","description":"Key 的权限 = 请求权限 ∩ 创建者在目标范围内的权限；Secret 只返回一次。Key 也可作为 MQTT 订阅凭证：username `key:<accessKey>`、password `<secret>`，只能订阅本 Workspace 产品的 Topic。\n\n需要权限点：`apikey:create`","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"template":{"type":"string","enum":["readonly","device_register","full"]},"permissions":{"type":"array","items":{"type":"string"}},"scopeType":{"type":"string","enum":["WORKSPACE","SPACE","PRODUCT","TAG","DEVICES"]},"scopeRef":{"type":"string"},"ipAllowlist":{"type":"array","items":{"type":"string"}},"expiresAt":{"type":"string","format":"date-time"}},"required":["name"]}}}},"responses":{"201":{"description":"Key（含 secret）","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"accessKey":{"type":"string"},"secret":{"type":"string"},"token":{"type":"string","description":"Authorization: Bearer <token>"},"permissions":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/me":{"get":{"tags":["组织"],"summary":"当前用户、可用 Workspace 与权限点","responses":{"200":{"description":"我","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"}}},"workspaces":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}}}},"currentWorkspaceId":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}}}}}}},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/v1/audit":{"get":{"tags":["组织"],"summary":"审计日志","description":"需要权限点：`workspace:audit.read`","parameters":[{"name":"page","in":"query","description":"页码，从 1 开始","schema":{"type":"integer"}},{"name":"pageSize","in":"query","description":"每页条数（≤ 200）","schema":{"type":"integer"}},{"name":"action","in":"query","description":"动作前缀","schema":{"type":"string"}},{"name":"q","in":"query","description":"搜索","schema":{"type":"string"}}],"responses":{"200":{"description":"成功"},"401":{"description":"未登录 / API Key 无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"缺少权限点或超出范围","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearerAuth":[]},{"session":[]}]}},"/api/health":{"get":{"tags":["系统"],"summary":"健康检查（免登录）","responses":{"200":{"description":"ok / degraded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"503":{"description":"down","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}},"security":[]}},"/api/v1/openapi.json":{"get":{"tags":["系统"],"summary":"本文档（OpenAPI 3.1）","responses":{"200":{"description":"成功"}},"security":[]}},"/api/device/v1/property":{"post":{"tags":["设备侧 HTTP"],"summary":"HTTP 属性上报","description":"低功耗 / 无 MQTT 栈设备用。请求头 `X-Device-Key` + `X-Device-Secret`（或 `X-Device-Signature: sig:<ts>:<hmac>`）。走与 MQTT 相同的入库管道。","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyPost"}}}},"responses":{"200":{"description":"已入队","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"id":{"type":"string"}}}}}},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"设备凭证无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"deviceKey":[],"deviceSecret":[]}]}},"/api/device/v1/commands":{"get":{"tags":["设备侧 HTTP"],"summary":"长轮询取指令","description":"`?wait=25` 最多挂起 25 秒；返回 PENDING 指令并标记 SENT。","parameters":[{"name":"wait","in":"query","description":"挂起秒数（≤ 25）","schema":{"type":"integer"}}],"responses":{"200":{"description":"指令","content":{"application/json":{"schema":{"type":"object","properties":{"commands":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"service":{"type":"string"},"params":{"type":"object","properties":{}}}}}}}}}}},"security":[{"deviceKey":[],"deviceSecret":[]}]}},"/api/device/v1/commands/{id}/reply":{"post":{"tags":["设备侧 HTTP"],"summary":"指令回执","parameters":[{"name":"id","in":"path","required":true,"description":"指令 id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","description":"< 400 为成功"},"data":{"type":"object","properties":{}}},"required":["code"]}}}},"responses":{"200":{"description":"成功"},"400":{"description":"参数错误","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"deviceKey":[],"deviceSecret":[]}]}},"/api/device/v1/media":{"post":{"tags":["设备侧 HTTP"],"summary":"图片上传（抄表）","description":"multipart：`image` 文件（≤ 5 MB）+ `meta` JSON `{ reading, confidence, battery, rssi, temperature, ts }`；读数与终端健康走上行管道。","responses":{"201":{"description":"已保存","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"reading":{"type":"number"}}}}}}},"security":[{"deviceKey":[],"deviceSecret":[]}]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API Key：`<accessKey>.<secret>`"},"session":{"type":"apiKey","in":"cookie","name":"authjs.session-token","description":"控制台登录会话"},"deviceKey":{"type":"apiKey","in":"header","name":"X-Device-Key"},"deviceSecret":{"type":"apiKey","in":"header","name":"X-Device-Secret"}},"schemas":{"Error":{"type":"object","properties":{"code":{"type":"string","description":"机器可读错误码：unauthorized / forbidden / not_found / bad_request / conflict / internal"},"message":{"type":"string","description":"中文说明"},"requestId":{"type":"string"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}}},"description":"参数校验明细（400）"}},"required":["code","message"]},"Page":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"}},"required":["total","page","pageSize"]},"Device":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"deviceKey":{"type":"string"},"status":{"type":"string","enum":["UNACTIVATED","ONLINE","OFFLINE","SLEEPING","DISABLED"]},"lastSeenAt":{"type":"string","format":"date-time"},"lastOnlineAt":{"type":"string","format":"date-time"},"spaceId":{"type":"string"},"gatewayId":{"type":"string"},"tags":{"type":"object","properties":{}},"shadowReported":{"type":"object","properties":{},"description":"最新上报值（需 device:shadow.read）"},"shadowDesired":{"type":"object","properties":{}},"productId":{"type":"string"},"product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"productKey":{"type":"string"},"category":{"type":"string"},"nodeType":{"type":"string"}}},"space":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"createdAt":{"type":"string","format":"date-time"}},"required":["id","name","deviceKey","status"]},"DeviceCreate":{"type":"object","properties":{"productId":{"type":"string"},"name":{"type":"string"},"deviceKey":{"type":"string","description":"可选：IMEI / SN；不填自动生成"},"spaceId":{"type":"string"},"tags":{"type":"object","properties":{}}},"required":["productId","name"]},"DeviceCreated":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"productKey":{"type":"string"},"deviceKey":{"type":"string"},"secret":{"type":"string","description":"只返回这一次"},"endpoints":{"type":"object","properties":{"mqttHost":{"type":"string"},"mqttPort":{"type":"integer"},"mqttTlsPort":{"type":"integer"},"mqttWsUrl":{"type":"string"},"httpBase":{"type":"string"}}},"examples":{"type":"object","properties":{"mqttjs":{"type":"string"},"python":{"type":"string"},"at":{"type":"string"},"http":{"type":"string"}}}},"required":["id","deviceKey","secret"]},"Product":{"type":"object","properties":{"id":{"type":"string"},"productKey":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"nodeType":{"type":"string","enum":["DIRECT","GATEWAY","SUBDEVICE"]},"protocol":{"type":"string"},"authMode":{"type":"string"},"tsl":{"$ref":"#/components/schemas/Tsl"},"offlineAfterSec":{"type":"integer"},"description":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","productKey","name"]},"Tsl":{"type":"object","properties":{"properties":{"type":"array","items":{"type":"object","properties":{"identifier":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["int","float","double","bool","enum","string","date","struct","array","image"]},"unit":{"type":"string"},"min":{"type":"number"},"max":{"type":"number"},"access":{"type":"string","enum":["r","rw"]}}}},"events":{"type":"array","items":{"type":"object","properties":{"identifier":{"type":"string"},"name":{"type":"string"},"level":{"type":"string"}}}},"services":{"type":"array","items":{"type":"object","properties":{"identifier":{"type":"string"},"name":{"type":"string"},"critical":{"type":"boolean"}}}}}},"Space":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"parentId":{"type":"string"},"path":{"type":"string","description":"物化路径 root.xxx.yyy"},"sortOrder":{"type":"integer"}},"required":["id","name","path"]},"SeriesPoint":{"type":"object","properties":{"t":{"type":"string","format":"date-time"},"v":{"type":"number","description":"原始值或桶内平均"},"min":{"type":"number"},"max":{"type":"number"},"n":{"type":"integer","description":"桶内点数"},"s":{"type":"string","description":"字符串值（raw）"},"q":{"type":"integer","description":"质量位：0 正常 1 可疑 2 人工纠正"}},"required":["t"]},"Telemetry":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"agg":{"type":"string","enum":["raw","1m","1h","1d"]},"series":{"type":"object","properties":{},"description":"{ [prop]: SeriesPoint[] }"},"truncated":{"type":"boolean"}}},"Command":{"type":"object","properties":{"id":{"type":"string"},"deviceId":{"type":"string"},"service":{"type":"string"},"params":{"type":"object","properties":{}},"status":{"type":"string","enum":["PENDING","SENT","ACKED","FAILED","EXPIRED"]},"result":{"type":"object","properties":{}},"reason":{"type":"string"},"sentAt":{"type":"string","format":"date-time"},"ackedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","service","status"]},"CommandCreate":{"type":"object","properties":{"service":{"type":"string","description":"物模型服务标识符"},"params":{"type":"object","properties":{}},"reason":{"type":"string","description":"高危服务必填"},"ttlSec":{"type":"integer","description":"过期秒数，默认 48h"}},"required":["service"]},"Shadow":{"type":"object","properties":{"reported":{"type":"object","properties":{}},"desired":{"type":"object","properties":{}},"sync":{"type":"object","properties":{},"description":"{ [key]: 'synced' | 'pending' }"}}},"DeviceEvent":{"type":"object","properties":{"time":{"type":"string","format":"date-time"},"deviceId":{"type":"string"},"event":{"type":"string","description":"online / offline / alarm / alarm_resolved / anomaly / <物模型事件>"},"payload":{"type":"object","properties":{}}},"required":["time","event"]},"RuleScope":{"type":"object","properties":{"kind":{"type":"string","enum":["all","product","space","tag","devices"]},"productId":{"type":"string"},"spaceId":{"type":"string"},"tag":{"type":"string","description":"key:value"},"deviceIds":{"type":"array","items":{"type":"string"}}},"required":["kind"],"description":"设备范围"},"RuleCondition":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["threshold"]},"prop":{"type":"string","description":"物模型属性标识符"},"cmp":{"type":"string","enum":[">",">=","<","<=","==","!="]},"value":{"type":"number"}},"required":["type","prop","cmp","value"]},{"type":"object","properties":{"type":{"type":"string","enum":["out_of_range"]},"prop":{"type":"string"},"min":{"type":"number"},"max":{"type":"number"}},"required":["type","prop"]},{"type":"object","properties":{"type":{"type":"string","enum":["offline"]},"durationSec":{"type":"integer","description":"离线持续秒数，0 = 一离线就算"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["stale"]},"durationSec":{"type":"integer","description":"无上报持续秒数（≥ 60）"}},"required":["type","durationSec"]},{"type":"object","properties":{"type":{"type":"string","enum":["status"]},"status":{"type":"string","enum":["ONLINE","OFFLINE","SLEEPING","DISABLED","UNACTIVATED"]}},"required":["type","status"]},{"type":"object","properties":{"type":{"type":"string","enum":["event"]},"event":{"type":"string","description":"事件标识符，* = 任意"},"paramProp":{"type":"string"},"cmp":{"type":"string","enum":[">",">=","<","<=","==","!="]},"value":{"type":"number"}},"required":["type","event"]}]},"RuleConditions":{"type":"object","properties":{"op":{"type":"string","enum":["and","or"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/RuleCondition"}}},"required":["items"]},"RuleInput":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"enabled":{"type":"boolean"},"severity":{"type":"string","enum":["info","warn","critical"]},"scope":{"$ref":"#/components/schemas/RuleScope"},"conditions":{"$ref":"#/components/schemas/RuleConditions"},"debounceSec":{"type":"integer","description":"条件持续满足 N 秒才触发"},"silenceSec":{"type":"integer","description":"同设备同规则 N 秒内不重复通知"},"recoverSec":{"type":"integer","description":"条件不再满足并持续 N 秒后自动关闭"},"notifyOnResolve":{"type":"boolean"},"message":{"type":"string","description":"通知文案模板：{device} {rule} {prop} {value} {unit} {severity} {time}"},"channelIds":{"type":"array","items":{"type":"string"}}},"required":["name","scope","conditions"]},"Rule":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"enabled":{"type":"boolean"},"severity":{"type":"string"},"scope":{"$ref":"#/components/schemas/RuleScope"},"scopeLabel":{"type":"string"},"conditions":{"$ref":"#/components/schemas/RuleConditions"},"debounceSec":{"type":"integer"},"silenceSec":{"type":"integer"},"recoverSec":{"type":"integer"},"notifyOnResolve":{"type":"boolean"},"message":{"type":"string"},"channelIds":{"type":"array","items":{"type":"string"}},"lastFiredAt":{"type":"string","format":"date-time"},"fireCount":{"type":"integer"},"activeAlarms":{"type":"integer"},"totalAlarms":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","enabled","severity","scope","conditions"]},"Alarm":{"type":"object","properties":{"id":{"type":"string"},"ruleId":{"type":"string"},"rule":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"deviceId":{"type":"string"},"device":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"deviceKey":{"type":"string"},"status":{"type":"string"},"space":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}},"severity":{"type":"string","enum":["info","warn","critical"]},"status":{"type":"string","enum":["ACTIVE","ACKED","RESOLVED"]},"title":{"type":"string"},"message":{"type":"string"},"detail":{"type":"object","properties":{"matched":{"type":"array","items":{"type":"object","properties":{}}},"snapshot":{"type":"object","properties":{}}}},"prop":{"type":"string"},"value":{"type":"number"},"firedAt":{"type":"string","format":"date-time"},"lastSeenAt":{"type":"string","format":"date-time"},"count":{"type":"integer","description":"活动期间重复命中次数"},"ackedAt":{"type":"string","format":"date-time"},"assignee":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"}}},"resolvedAt":{"type":"string","format":"date-time"},"resolvedBy":{"type":"string","enum":["auto","manual","rule_deleted"]},"notifiedAt":{"type":"string","format":"date-time"}},"required":["id","deviceId","severity","status","title","firedAt"]},"AlarmEvent":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["fired","notified","notify_failed","notify_skipped","acked","unacked","assigned","commented","resolved"]},"actorUserId":{"type":"string"},"actorName":{"type":"string"},"note":{"type":"string"},"detail":{"type":"object","properties":{}},"createdAt":{"type":"string","format":"date-time"}},"required":["id","type","createdAt"]},"Channel":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["email","wecom","dingtalk","feishu","webhook"]},"config":{"type":"object","properties":{},"description":"按类型：email {to[]}；wecom / feishu {webhookUrl}；dingtalk {webhookUrl, secret?}；webhook {url, secret?, headers?}"},"enabled":{"type":"boolean"},"lastUsedAt":{"type":"string","format":"date-time"},"lastError":{"type":"string"},"rules":{"type":"integer","description":"引用它的规则数"}},"required":["id","name","type"]},"Webhook":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["device.online","device.offline","device.property","device.event","command.updated","alarm.fired","alarm.acked","alarm.resolved"]}},"scope":{"$ref":"#/components/schemas/RuleScope"},"headers":{"type":"object","properties":{}},"enabled":{"type":"boolean"},"failCount":{"type":"integer"},"lastStatus":{"type":"integer"},"lastError":{"type":"string"},"lastDeliveredAt":{"type":"string","format":"date-time"},"secret":{"type":"string","description":"仅创建响应返回一次；用于校验 X-MControl-Signature"}},"required":["id","name","url","events"]},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"event":{"type":"string"},"payload":{"type":"object","properties":{}},"status":{"type":"string","enum":["PENDING","OK","FAILED"]},"attempts":{"type":"integer"},"responseStatus":{"type":"integer"},"error":{"type":"string"},"durationMs":{"type":"integer"},"deliveredAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"WebhookPayload":{"type":"object","properties":{"id":{"type":"string","description":"投递 id（幂等键）"},"event":{"type":"string","enum":["device.online","device.offline","device.property","device.event","command.updated","alarm.fired","alarm.acked","alarm.resolved"]},"ts":{"type":"integer","description":"毫秒时间戳"},"workspaceId":{"type":"string"},"attempt":{"type":"integer"},"data":{"type":"object","properties":{},"description":"按事件：device.property {deviceId, deviceKey, props, quality, ts}；device.online/offline {deviceId, deviceKey, status}；device.event {event, payload}；command.updated {commandId, status, result}；alarm.* {alarmId, ruleId, deviceId, severity, status, title}"}},"required":["id","event","ts","data"],"description":"推送体。请求头 X-MControl-Signature: t=<ts>,v1=<hex(HMAC-SHA256(secret, `${t}.${body}`))>、X-MControl-Event、X-MControl-Delivery"},"ExportJob":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["telemetry","alarms","devices"]},"params":{"type":"object","properties":{"scope":{"$ref":"#/components/schemas/RuleScope"},"props":{"type":"array","items":{"type":"string"}},"range":{"type":"string","enum":["last1h","last24h","yesterday","last7d","lastWeek","last30d","lastMonth"]},"agg":{"type":"string","enum":["auto","raw","1m","1h","1d"]},"status":{"type":"string","enum":["all","open","resolved"]}}},"schedule":{"type":"string","enum":["daily","weekly","monthly"]},"hour":{"type":"integer"},"channelIds":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"nextRunAt":{"type":"string","format":"date-time"},"lastRunAt":{"type":"string","format":"date-time"},"lastStatus":{"type":"string"},"lastRun":{"$ref":"#/components/schemas/ExportRun"}},"required":["id","name","kind","params"]},"ExportRun":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["RUNNING","OK","FAILED"]},"trigger":{"type":"string"},"fileName":{"type":"string"},"size":{"type":"integer"},"rows":{"type":"integer"},"error":{"type":"string"},"startedAt":{"type":"string","format":"date-time"},"finishedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"}}},"Dashboard":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"layout":{"type":"object","properties":{"cols":{"type":"integer"},"widgets":{"type":"array","items":{"type":"object","properties":{}}}}},"theme":{"type":"string"},"rotateSec":{"type":"integer"},"isDefault":{"type":"boolean"},"version":{"type":"integer","description":"乐观锁：PATCH 时带上，冲突返回 409"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","layout"]},"DashboardDataRequest":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"agg":{"type":"string"},"queries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"mode":{"type":"string","enum":["latest","series","kpi","status"]},"source":{"$ref":"#/components/schemas/RuleScope"},"props":{"type":"array","items":{"type":"string"}},"stat":{"type":"string","enum":["last","avg","min","max","sum","count"]}}}}},"required":["queries"]},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"accessKey":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"scopeType":{"type":"string"},"scopeRef":{"type":"string"},"ipAllowlist":{"type":"array","items":{"type":"string"}},"expiresAt":{"type":"string","format":"date-time"},"lastUsedAt":{"type":"string","format":"date-time"},"revokedAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"Stats":{"type":"object","properties":{"total":{"type":"integer"},"status":{"type":"object","properties":{"UNACTIVATED":{"type":"integer"},"ONLINE":{"type":"integer"},"OFFLINE":{"type":"integer"},"SLEEPING":{"type":"integer"},"DISABLED":{"type":"integer"}}},"products":{"type":"integer"},"reported24h":{"type":"integer"},"pendingCommands":{"type":"integer"},"onlineRate":{"type":"number"}}},"Health":{"type":"object","properties":{"ok":{"type":"boolean"},"status":{"type":"string","enum":["ok","degraded","down"]},"version":{"type":"string"},"db":{"type":"string"},"redis":{"type":"string"},"worker":{"type":"string"},"ingestBacklog":{"type":"integer"},"dbSkewMs":{"type":"integer"}}},"Venue":{"type":"object","properties":{"id":{"type":"string"},"spaceId":{"type":"string"},"name":{"type":"string","description":"空间名"},"path":{"type":"string","description":"空间物化路径"},"unit":{"type":"string","enum":["hour","session","day"],"description":"计费单位：按小时 / 按场次 / 按天"},"price":{"type":"number","description":"平时单价（元 / 单位）"},"peakPrice":{"type":"number","description":"高峰单价；空 = 不分时段"},"peakNote":{"type":"string","description":"高峰时段说明"},"openFrom":{"type":"string","description":"每天开售 HH:mm（Workspace 时区）"},"openTo":{"type":"string","description":"每天停售 HH:mm"},"capacity":{"type":"integer","description":"可同时出租的单元数（片 / 泳道 / 整馆）"},"unitLabel":{"type":"string","description":"单元名称"},"enabled":{"type":"boolean"},"sortOrder":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","spaceId","unit","price"]},"VenueInput":{"type":"object","properties":{"unit":{"type":"string","enum":["hour","session","day"]},"price":{"type":"number"},"peakPrice":{"type":"number"},"peakNote":{"type":"string"},"openFrom":{"type":"string","description":"HH:mm"},"openTo":{"type":"string","description":"HH:mm"},"capacity":{"type":"integer"},"unitLabel":{"type":"string"},"enabled":{"type":"boolean"},"sortOrder":{"type":"integer"}},"required":["price"]},"VenueTariff":{"type":"object","properties":{"electricity":{"type":"number","description":"电价（元 / kWh）"}},"required":["electricity"]},"Booking":{"type":"object","properties":{"id":{"type":"string"},"venueId":{"type":"string"},"startAt":{"type":"string","format":"date-time"},"endAt":{"type":"string","format":"date-time"},"units":{"type":"integer","description":"占用单元数"},"amount":{"type":"number","description":"应收金额（元）"},"status":{"type":"string","enum":["CONFIRMED","COMPLETED","CANCELLED"]},"customer":{"type":"string"},"source":{"type":"string","description":"web / phone / walk_in / api / demo"},"note":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","venueId","startAt","endAt","amount","status"]},"BookingInput":{"type":"object","properties":{"startAt":{"type":"string","format":"date-time"},"endAt":{"type":"string","format":"date-time"},"units":{"type":"integer","description":"默认 1，不能超过场馆容量"},"amount":{"type":"number","description":"不填按 时长（小时）× 单元数 × 平时单价"},"status":{"type":"string","enum":["CONFIRMED","COMPLETED","CANCELLED"]},"customer":{"type":"string"},"source":{"type":"string"},"note":{"type":"string"}},"required":["startAt","endAt"]},"VenueOverview":{"type":"object","properties":{"generatedAt":{"type":"string","format":"date-time"},"tz":{"type":"string","description":"Workspace 时区，月 / 日窗口按它切"},"currency":{"type":"string"},"month":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"},"daysInMonth":{"type":"integer"},"elapsedDays":{"type":"number","description":"月初到现在过了几天（小数）"},"year":{"type":"integer"},"month":{"type":"integer"}}},"tariff":{"$ref":"#/components/schemas/VenueTariff"},"revenue":{"type":"object","properties":{"mtd":{"type":"number","description":"当月收入：本月已开始且未取消的预定金额"},"bookedFuture":{"type":"number","description":"本月剩余时间已预定金额"},"projected":{"type":"number","description":"预计月收入 = mtd + max(已预定, 日均 × 剩余天数)"},"lastMonth":{"type":"number","description":"上月收入；没有上月数据为空"},"bookings":{"type":"integer","description":"本月预定数"}}},"energy":{"type":"object","properties":{"meterName":{"type":"string","description":"总进线电表（tags.meter = main）"},"mtdKwh":{"type":"number","description":"本月用电：月内最后读数 − 最早读数，历史不足一月按日均补"},"projectedKwh":{"type":"number","description":"预计月用电 = 日均 × 当月天数"},"costMtd":{"type":"number","description":"本月电费 = 用电 × 电价"},"costProjected":{"type":"number"},"ratioMtd":{"type":"number","description":"能耗占收入比 = 本月电费 / 当月收入"},"ratioProjected":{"type":"number","description":"预计能耗占比 = 预计电费 / 预计收入"}}},"venues":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"spaceId":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["building","ground"]},"ground":{"type":"string","description":"室外场地类型"},"unit":{"type":"string"},"price":{"type":"number"},"peakPrice":{"type":"number"},"peakNote":{"type":"string"},"openFrom":{"type":"string"},"openTo":{"type":"string"},"capacity":{"type":"integer"},"unitLabel":{"type":"string"},"today":{"type":"object","properties":{"bookings":{"type":"integer"},"bookedUnitHours":{"type":"number","description":"今日已订 单元·小时"},"sellableUnitHours":{"type":"number","description":"今日可售 = 开放小时 × 单元数"},"utilization":{"type":"number","description":"0–1"},"inUse":{"type":"integer","description":"此刻使用中的预定数"},"next":{"type":"object","properties":{"startAt":{"type":"string","format":"date-time"},"endAt":{"type":"string","format":"date-time"},"units":{"type":"integer"},"customer":{"type":"string"}},"description":"下一场预定"}}},"month":{"type":"object","properties":{"mtd":{"type":"number"},"bookedFuture":{"type":"number"},"projected":{"type":"number"},"bookings":{"type":"integer"},"unitHours":{"type":"number"},"lastMonth":{"type":"number"}}},"energy":{"type":"object","properties":{"mtdKwh":{"type":"number"},"projectedKwh":{"type":"number"},"costMtd":{"type":"number"},"costProjected":{"type":"number"},"ratioMtd":{"type":"number"},"ratioProjected":{"type":"number"}},"description":"楼栋子树里分项电表算出的用电 / 电费；室外场地或没有分项表为空"}}}}},"required":["generatedAt","month","revenue","energy","venues"]},"PropertyPost":{"type":"object","properties":{"id":{"type":"string","description":"报文 id（可选）"},"params":{"type":"object","properties":{},"description":"{ 属性标识符: 值 }"},"ts":{"type":"integer","description":"秒或毫秒时间戳（可选）"}},"required":["params"]}}},"x-permissions":{"workspace:read":"查看 Workspace 信息","workspace:update":"修改 Workspace 设置","workspace:delete":"删除 Workspace","workspace:billing":"计费与套餐","workspace:audit.read":"查看审计日志","member:read":"查看成员","member:invite":"邀请成员","member:update_role":"调整成员角色与范围","member:remove":"移除成员","role:read":"查看角色","role:create":"创建角色","role:update":"修改角色","role:delete":"删除角色","apikey:read":"查看 API Key","apikey:create":"创建 API Key","apikey:rotate":"轮换 API Key","apikey:revoke":"吊销 API Key","product:read":"查看产品","product:create":"创建产品","product:update":"修改产品","product:delete":"删除产品","product:tsl.edit":"编辑物模型","product:script.edit":"编辑解析脚本","product:publish_template":"发布为模板","device:read":"查看设备","device:create":"注册设备","device:update":"修改设备","device:delete":"删除设备","device:shadow.read":"查看设备影子","device:history.read":"查看历史数据","device:raw.read":"查看原始报文 / 图片","device:control.invoke":"调用普通服务","device:control.critical":"调用高危服务","device:config.write":"写期望值 / 参数","space:read":"查看空间","space:create":"创建空间","space:update":"修改空间","space:delete":"删除空间","space:assign_device":"分配设备到空间","site_kind:read":"查看业态","site_kind:create":"创建业态","site_kind:update":"修改业态","site_kind:delete":"删除业态","dashboard:read":"查看看板","dashboard:create":"创建看板","dashboard:update":"编辑看板","dashboard:delete":"删除看板","dashboard:share.public":"对外分享看板","dashboard:present":"大屏模式","rule:read":"查看规则","rule:create":"创建规则","rule:update":"修改规则","rule:delete":"删除规则","rule:enable":"启用 / 禁用规则","alarm:read":"查看告警","alarm:ack":"确认告警","alarm:resolve":"处理告警","alarm:assign":"指派告警","export:data.export":"导出数据","export:report.generate":"生成报表","template_market:browse":"浏览模板市场","template_market:install":"安装模板","template_market:publish":"发布模板"}}