外观
订阅与回流
虹元有两套方向相反的"订阅"，名字相近，语义相反，先分清：
| 名称 | 方向 | 谁动 | 游标 |
|---|---|---|---|
| 事件订阅 | 虹元到消费方（智悟、HSE 等） | 消费方拉取，虹元可选推送 | 事件编号 |
| 数据集订阅 | 业务系统到虹元 | 虹元按调度拉取 | 更新时间加主键 |
回流是第三件事：消费方把裁定与处置写回虹元，虹元再把裁定回流给边缘节点。
事件订阅
为什么是游标拉取
推送必然会失败。游标把这件事翻过来：消费方说"我处理到第 N 条了"，漏没漏它自己清楚。推送掉了不影响正确性，下次拉取自然补上。
接口
| 接口 | 作用 |
|---|---|
POST /api/uancore/events/subscribe | 登记消费方：过滤条件、可选推送地址、起始游标。幂等，重复登记不动游标 |
GET /api/uancore/events/since?consumer=<消费方> | 按游标拉取，返回 items、nextCursor、hasMore |
POST /api/uancore/events/ack | 确认处理到哪了，游标只在这里前进 |
GET /api/uancore/events/subscriptions | 订阅清单与落后量 |
GET /api/uancore/events/list | 运营侧分页查询，可按租户、类型、裁定筛选 |
GET /api/uancore/stats/window | 按时间窗出计数，见下文 |
GET /api/uancore/events/{id}/timeline | 单条事件的处置时间线，见处置与归并 |
登记字段：消费方标识（必填）、租户码、事件类型列表、最低严重度（低、中、高、紧急）、推送地址、签名密钥引用（只存引用不存明文）、起始游标、启用状态。登记需要管理密钥。
不传起始游标时从当前最新开始，从 0 开始会把历史全量重放一遍。
拉取每批默认 200 条，上限 1000。nextCursor 取本批最后一条的编号，被过滤掉的也算在内。
测试事件默认不拉、不推。做联调验证的消费方拉取时带 include_test=true，才连测试事件一起拿。
安全水位
事件编号来自序列，先分配后提交，编号大的可能先可见。拉取只返回入库时刻早于 2 秒前的记录，避免消费方跳过一条还在提交中的事件。
可选推送
登记了推送地址的订阅，虹元每 3 秒推一轮，单轮单订阅最多 100 条。推送带 X-Uan-Consumer 头，配了签名密钥时另带时间戳与 HMAC 签名。失败按次数指数退避，封顶 600 秒，不停用订阅。
推送只推不动确认游标，游标由消费方确认前进。推送失败最坏的结果是对方晚一点通过拉取拿到，不会丢。
消费方可以在推送回执里点名要证据图，现场虹元直传到对方的对象存储，见证据直传。
消费方怎么写
- 启动时登记订阅，重复登记无害。
- 循环：拉取一批，处理，确认到本批最后一条。处理失败不确认，下次重拉。
- 处理要幂等：同一条事件可能因为没确认而再来一次。
智悟就是这样接的：无本地库，游标在虹元，重启从确认位置继续。
按时间窗计数
GET /api/uancore/stats/window?tenant_code=<租户码>&since=<起>&until=<止>给周报、月报取数。翻页查询数不全，全时段统计又切不了周和月，所以单开一个只回计数的口。三个参数都必填，时间写 RFC3339，窗口左闭右开，一次最多 93 天。凭据同事件查询，客户会话只能取自己租户。
| 组 | 落窗口径 | 分组键 |
|---|---|---|
events | 事件发生时刻 | 来源（视频或随手拍）、告警或观测、事件类型、裁定、是否测试、是否有机器判定、判定类型 |
tasks | 任务建单时刻，跳过已删 | 类型、状态、所挂事件是否测试、所挂事件的来源、是否超时、是否升级过 |
knowledge | 知识落库时刻，跳过已删 | 类型 |
每组按计数降序。只回计数，不回明细。回包另带出数时刻 asOf，判任务超时以它为准。一租户一库时各库分别聚合再相加。单条聚合超过 15 秒回 503，缩短窗口再取。
回流
消费方写回裁定
POST /api/uancore/events/{id}/verdict| 字段 | 说明 |
|---|---|
verdict | 属实、误报、并入，三者之外拒绝 |
by | 裁定人标识，工号或系统标识 |
note | 备注，误报时必填 |
merged_into | 并入时必填 |
judged_* | 可选，机器判定：类型、置信、判定方、模型版本、口径版本等 |
disposition | 可选，处置决定：类型、严重度、通道、时限、消息、任务编号、摘要 |
tenant_code | 可选，声称租户，不符则拒绝 |
已裁定的幂等返回，不覆盖。裁定变更本身是需要留痕的事实，要改只能新开更正记录。写入不改事件本体。
虹元回流边缘节点
裁定写入后，虹元向事件里的回流地址推送：本地告警编号、事件编号、裁定、操作者、原因。节点据此把本地告警从待定改成属实或误报。不回流，节点库里的告警永远停在待定，分母一直涨、分子永远为空，误报率就算不出来。
回流尽力而为：节点不可达不让裁定失败，响应里如实带 pushedBack 与错误，界面能显示"已裁定，回流失败"。
任务处置进展（接手、完成、超时升级）同样按事件推给节点，节点记到告警的处置备注里。
数据集订阅
业务系统（随手拍、智营、智建等）向虹元开放只读数据集，虹元按调度拉取。五条原则：
- 只读。 接口只有 GET，没有任何写入、删除或触发动作的接口。
- 单向。 数据从业务系统流向虹元，没有反向通道。
- 虹元不连业务数据库。 包括只读账号在内，不持有任何业务库凭据。
- 字段范围由服务端定。 禁止外流的字段在实现里就不查询、不返回。
- 拉取而非推送。 业务系统不需要知道虹元地址，不用做重试与积压。
业务系统要提供两个接口：
| 接口 | 作用 |
|---|---|
GET /api/subscribe/v1/datasets | 数据集清单自描述：键、结构版本、粒度、度量、更新频率、最早数据 |
GET /api/subscribe/v1/datasets/{key}?cursor=&limit=&tenant= | 按游标取增量，每页默认 1000 行，上限 5000 |
游标是"更新时间加主键"的复合值，边界严格大于，同一游标重复请求返回相同结果。更正推进更新时间再入增量流，删除表现为标记。鉴权与事件接入同一套 HMAC 机制，限流默认每调用方每分钟 60 次，单次查询超过 10 秒返回错误。均值类字段不直接提供，给总和与计数；比率类给分子与分母。业务系统单方面加字段而契约未更新时，虹元拒收该批次并告警。
虹元侧的数据源、调度节拍与同步状态在控制台"数据源与同步状态"页配置，有新行落库才加工一次，全量重算忽略游标从头拉。
分级上行
单套虹元扛不住多场站，或现场要求站端断网期间业务照常时，站端各装一套虹元向总部上行。站端只填一个总部地址，总部不需要预先知道有几个站。
| 配置 | 说明 |
|---|---|
UANCORE_INSTANCE | 站端实例名，必须全局唯一 |
UANCORE_UPLINK_URL | 总部地址，配了才启用上行 |
UANCORE_UPLINK_INTERVAL_MS | 轮询间隔，默认 3000，下限 200 |
UANCORE_UPLINK_BATCH | 单批条数，默认 200，上限 1000 |
两条通道各一个游标：events 按编号推新事件，verdicts 按裁定时间推裁定变更。断链期间游标不动，恢复后从断点续推，不丢不重。总部按"租户加幂等键"去重。GET /api/uancore/uplink/status 同时回答站端推得怎么样与总部收到了谁的数据。能用集中式就别上分级，多一级就多一处可能不一致的地方。