外观
对象模型
虹元的一切都建立在一组带租户码的对象上。这一页先讲通用约定，再讲十类核心对象，最后讲感知链路上的六个对象：节点、事件、任务、裁定、订阅、授权。
通用约定
| 项 | 约定 |
|---|---|
| 全局标识 | {对象前缀}_{ULID}，如 per_01J2X…；存量系统保留自增主键，补一列 core_id |
| 租户 | 所有对象携带 tenant_code；云端一租户一库，见下文租户与分库 |
| 时间 | UTC 毫秒时间戳加时区字段 |
| 软删除 | deleted_at 标记，对象标识永不复用 |
| 审计 | 所有对象变更进审计表：谁、何时、改了什么、改前改后 |
| 来源键 | 由外部系统同步进来的对象记 src_system 与 src_pk，同一来源同一主键只落一条 |
建模顺序是先对象、再事件、最后指标。指标只能从已定义的对象与事件聚合，展示层不做计算。
十类核心对象
| 对象 | 前缀 | 定义 | 关键字段 |
|---|---|---|---|
| 人员 | per | 员工、承包商人员、访客的唯一身份 | 姓名、手机（脱敏存）、证件类型、雇主组织、角色、证书、状态 |
| 组织 | org | 集团、基地、项目、部门、班组、承包商、客户单位 | 名称、类型、上级、层级 |
| 场域 | sit | 场站、装置区、楼栋、区域，可分层 | 名称、类型、上级、地理位置、风险等级 |
| 资产 | ast | 设备、装置、车辆等实物 | 名称、类型、所属场域、位号、厂商、生命周期 |
| 任务 | tsk | 工单、检查、整改、审批等可执行工作 | 类型、挂接对象、责任人或组织、时限、状态、来源 |
| 风险 | rsk | 风险源及其分级管控 | 名称、类别、等级（红橙黄蓝）、场域、管控措施、负责人 |
| 规则 | rul | 制度、阈值、审批逻辑、判定口径、响应规则、大模型提示词 | 名称、类型、结构化规则体、版本、生效时间 |
| 事件 | evt | 现场发生的事实，感知或人工上报 | 见下文 |
| 证据 | evd | 事件与处置的证明材料 | 类型（快照、片段、蒙太奇、裁剪图、照片、文档）、地址、指纹 |
| 知识 | kno | 制度文档、案例、经验、口径卡、智悟成文的报告 | 标题、类型、来源引用、密级、版本、有效期、正文 |
几条关系：人员属于组织，多对多带岗位与时间区间；场域与资产各自成树，资产必挂场域；任务的挂接对象可以指向任意对象，这是"感知触发业务"的挂接点；事件必带场域，可带资产与人员，附一到多条证据；知识可引用事件、任务或规则。
组织类型三值：内部组织、承包商、客户单位。客户单位在业务系统里另有租户码时记在集团码字段里，客户与租户不能画等号。
节点
节点是接入虹元的边缘 AI 设备，一台一条：节点键、租户、场域、启用状态、密钥引用、测试模式。库里不存明文密钥，只存环境变量引用或配对协商出的会话密钥。节点键必须全局唯一，两个站的节点都叫同一个名字，同一秒的同类事件在总部会被判成重复。
事件
事件是感知链路的核心对象，原始上报体整体留存，后续契约加字段时旧事件仍可完整回放。
| 字段 | 说明 |
|---|---|
node_key | 上报节点 |
dedup_key | 幂等键，构成 {节点}_{摄像头}_{事件类型}_{窗口起始秒} |
event_type | 叶子类型，如 fire.smoke、person.fight、vehicle.observed |
severity | 严重度提示：低、中、高、紧急。最终定级以人工确认为准 |
category | 告警或观测。观测（如车辆经过）不套规则不建任务 |
occurred_at / received_at | 发生时刻与入库时刻 |
camera_ref / camera_name / site_ref | 设备与场域定位 |
evidence | 证据数组，只存引用与指纹，不存图 |
model | 产生它的模型与版本 |
trace_id | 全链路追踪号，缺则生成 |
verdict 及其时间、裁定人、备注 | 人工裁定 |
judged_* | 机器判定：类型、置信、判定方、模型版本、口径版本 |
expires_at | 保留期到期时刻 |
is_test | 测试事件，与生产事件分流 |
幂等键的作用域是"租户加幂等键"复合唯一，重复上报不改写既有事实，只回既有编号。
保留期按租户配：观测默认 30 天，告警默认 180 天，证据跟随事件。到期时刻在入库时按当时的策略算定，事后改策略不追溯存量。已人工裁定的告警永不自动删，裁定是人的劳动，也是误报率的分子。测试事件固定短保留（默认 7 天），到期不论裁定一律清。
事件被清时，挂在它上面的东西一起收口：测试事件的任务跟着删；真实事件上没结的任务改成已取消，history 里写明是保留期清理；办结的任务原样留着。归并组按剩下的成员重算，见处置与归并。
任务
任务状态机四态：待接手、处理中、已完成、已取消，后两者为终态。任务记来源系统与来源键，同一来源同一键只落一条。任务体是自由结构，智悟往里写严重度、通道、消息、通知留痕、超时升级记录。边缘节点确认真警后，该事件的待接手任务自动视为已接手，值守就在现场。
处置经过记在任务上：流转历史、到场与措施等处置记录、办结结果代码、推给现场的说明。这四项只追加，建单和改任务体时都不许碰。两个人同时办结，只有先到的那个生效，后到的回 409。复盘请求这类不是处置的任务照常流转，不推给现场。详见处置与归并。
裁定
裁定是对事件的最终结论，三值：属实、误报、并入。误报必须填备注，并入必须指明并入哪条。已裁定的不覆盖，再次裁定幂等返回；要改只能新开更正记录。裁定不改写事件本体。
裁定分两层：人工裁定写在 verdict，机器判定写在 judged_*，两者分列。机器判定另带六项溯源：模型键、模型版本、制品指纹、阈值版本、提示词版本、知识版本。
裁定写入后虹元向节点回流，节点把本地告警从待定改成属实或误报。回流尽力而为，节点不可达不让裁定失败，响应里如实带回流结果。
订阅
订阅登记一个消费方从哪里开始、看哪些事件：
| 字段 | 说明 |
|---|---|
consumer | 消费方标识 |
tenant_code | 租户过滤，硬隔离，消费方不能自己放宽 |
event_types / min_severity | 类型与最低严重度过滤 |
cursor_id | 确认到哪，只在消费方确认后前进 |
push_cursor | 推到哪，推送成功即前进 |
callback_url / secret_ref | 可选推送地址与签名密钥引用；地址为空是纯拉取 |
fail_count / next_try_at / last_error | 退避与诊断 |
两个游标不能合并：确认游标保证不丢，推送游标保证不重推。
授权
授权项回答"哪份数据、给谁、为了什么目的、依据什么、有效期多久"：
| 字段 | 说明 |
|---|---|
| 数据集 | 授权的数据集键 |
| 控制者 | 数据的权利主体，租户码 |
| 接收方类型与标识 | 集团、沅虹运营、消费应用、合作方、第三方 |
| 目的 | 与查询携带的目的比对 |
| 粒度 | 明细行、汇总值、按日、按月、指标值 |
| 法律依据与文件 | 合同约定、客户授权、法定义务及文件位置 |
| 状态 | 生效、已撤回、已过期、已暂停、待生效 |
| 有效期 | 起止日期 |
| 批准人 | 谁批的 |
每次状态变更写一条只增不改的流水：动作、操作者、操作方（租户侧或沅虹侧）、理由、时间。撤回必须填理由。
租户与分库
虹元同一套程序有两种形态：
| 形态 | 用在哪 | 库怎么分 |
|---|---|---|
| 单库 | 现场部署（缺省） | 一个库放全部表，按 tenant_code 隔离 |
| 一租户一库 | 公有云 | 主库只放控制面：目录口径与授权、节点与凭据、数据集拉取登记、删除台账、模型台账、实例身份。每个租户的业务数据（事件、任务、知识、归并组、制度库）在自己的 uancore_<租户码> 库里 |
一租户一库时，开哪些租户库以主库的登记为准，库名只能由租户码推出来。新开租户不用重启。每张表归哪边有登记，定向删除、开户与自检都读同一份登记。
凭据决定租户：
| 凭据 | 租户 |
|---|---|
| 客户租户的门户会话 | 固定是会话租户；指明别家回 403 |
| 管理密钥，或沅虹运营租户的门户会话 | 按 x-tenant-code 头或 tenant_code 参数；两处都给又不一致回 400 |
| 节点签名、配对码、对外集成钥匙、查询令牌 | 按凭据在主库查出租户 |
节点配对同样不跨租户：节点名已经属于别的租户时，配对回 409，配对码不作废。
其他对象
- 模型台账。 模型名、版本、运行时、制品指纹、许可、来源、评测引用、状态。判定留痕里的模型键与版本从这里对上。
- 实例身份。 这套虹元代表哪家单位、哪个租户、哪个场站。接入方看到的是它，不填就是实例名。
- 消费方契约。 消费方声明它要哪些数据集、什么目的、什么范围规则、排除哪些维度、保留多少天。
- 质量规则与健康度。 六维质量校验（完整性、准确性、一致性、及时性、唯一性、有效性），资产健康度四态。
- 元数据。 数据域、数据资产、字段（含敏感度分级）、指标（原子、派生、复合）、口径版本、血缘。
- 归并组。 一组告警归成的一件事，分三层，带首出、成员与人工确认的痕迹。见处置与归并。
- 制度文件与条款块。 制度库的文件台账、切块、账号密级、问答留痕。见知识与制度库。