YBO 技术文档

主题

P08 · YBO Mate——数据模型与 API 附录(Level 2) ​

1. 范围与职责归属 ​

本附录定义 Mate 云端实体模型、面向设备的 MQTT 接口面以及面向应用的 REST/WebSocket 接口面,覆盖 P08-mate.md FR-01–FR-30。它仅涉及软件——不含芯片、不含总线时序;其摄入的每个 YBO-CAN 载荷均定义于 X01-ybo-can-protocol.md §4,每个配置对象均定义于 X02-config-schema.md §3。

参与方负责绝不做
Mate 云端聚合:船舶模型、单一时间线、时序汇总、静态告警存档、自动化编写/签名、登记/维护/文档、船队视图、OTA 编排、配置备份(P08-mate.md §2)保护、默认状态或本地告警逻辑;运行时为固件签名(P08-mate.md §6);充当实时状态的事实来源
HUB / 独立 AIR-GW实时状态的事实来源:STATE 回读、已同步任务的本地执行、地理围栏/锚泊评估、存储转发缓冲(P03-hub.md §9、P05-air-gateway.md FR-12/17)接受未签名配置或过期命令(P03-hub.md §10)
应用(iOS/Android/web/fleet)仅渲染 STATE——命令状态在设备回读前为 pending,约 5 s 后回退(P08-mate.md FR-05、PRODUCT-PLAN.md §1 控制面准则)乐观状态;除本地模式(FR-12)之外的设备直连

2. 实体模型 ​

存储类别 (t):下列实体使用关系型存储;TELEM 采样使用时序存储;剪辑、文档与交接包使用对象存储(P08-mate.md §3 云端拓扑,技术栈按 PRODUCT-PLAN.md §6 第 6 项)。约定 (t):id = UUIDv7;*_ref = 外部 id;所有时间戳为 RFC 3339 UTC;vessel、channel 与 input 的实体 id 与 Studio id 相同,使云端、bundle 与 PDF 指称同一事物(P08-mate.md §5 船舶模型行、X02-config-schema.md §3)。

单一船舶时间线规则(P08-mate.md FR-10):每一个历史事实——状态变化、告警阶段、命令结果、自动化运行、快速日志、工作日志、文档事件、交接修订、配置部署、OTA 步骤、在线状态变化——都恰好对应一行 timeline_event。其他实体只保存当前状态及对 timeline_event 的引用;任何实体都不保存第二份历史。

2.1 船舶与拓扑(镜像已部署的 Studio 配置版本) ​

实体字段类型必填说明
vesselid, hull_id, nameuuid, string, string是hull_id 来自 X02-config-schema.md 的 vessel 对象;单一船东账户
vesselowner_ref, tier, config_version_iduuid, enum, int是tier ∈ {free, premium, security, fleet}(P08-mate.md §7);当前生效的 Studio 版本(X02-config-schema.md §2)
vesselinstall_mode, region, offline_sinceenum, enum, timestamp是/是/否system 或 standalone_air(X02-config-schema.md G-13);EU 托管已定(P08-mate.md §6)
deviceid, vessel_ref, class, uiduuid, uuid, enum, string是class ∈ X01 node classes;64 位出厂 UID 十六进制(X01-ybo-can-protocol.md §2)
devicerole, cert_serial, fw_version, last_seenenum, string, string, timestamp是/是/否/否role ∈ {uplink, bus_node};每艘船恰好一个 uplink(§3)
channelid, device_ref, index, typestring, uuid, int, enum是id 与 type 在部署时从 X02-config-schema.md §4.1 复制;绝不在 Mate 中编辑
channelcircuit_name, zone, critical, statestring, string, bool, enum是state ∈ X01 channel-state enum,仅由 STATE 写入(X01-ybo-can-protocol.md §4.3)
channelcurrent_a, level_pct, trip_reason, last_seennumber, number, enum, timestamp否最近一次回读,附每个值各自的 "last seen"(P08-mate.md FR-06)
inputid, device_ref, index, type, rolestring, uuid, int, enum, enum是来自 X02-config-schema.md §3 inputs;type ∈ {di, ai}
inputvalue, unit, quality, last_seennumber, string, enum, timestamp否quality ∈ {ok, wire_break, sensor_fault},取自 TELEM 标志(X01-ybo-can-protocol.md §4.4)

2.2 时间线与运行 ​

实体字段类型必填说明
timeline_eventid, vessel_ref, kinduuid, uuid, enum是kind ∈ {state, alarm, command, automation_run, quick_log, work_log, document, handover, config_deploy, ota, presence} (t)
timeline_eventts_device, ts_receivedtimestamp, timestamp否/是每条记录均含两者(P08-mate.md §5 时间线行);节点时钟未同步时 ts_device 为 null(X01-ybo-can-protocol.md §9)
timeline_eventsource_kind, source_ref, payloadenum, string, json是source_kind ∈ {device, channel, input, user, task, cloud};payload 结构按 kind 定义,仅追加
alarmid, vessel_ref, severity, code, channel_refuuid, uuid, enum, enum, string是/是/是/是/否severity ∈ {notice, warning, critical};code 来自 X01-ybo-can-protocol.md §4.5 加云端代码(地理围栏、MOB、Eye、离线)(t)
alarmraised_at, cleared_at, acked_at, acked_bytimestamp ×3, uuid是/否/否/否ALARM raise/clear/acknowledge 的阶段镜像;流程见 §6
alarmdelivery, clip_refjson, uuid否面向 FR-08 SLA 的按接收人推送/确认日志;置顶的 Eye 剪辑(P08-mate.md FR-27)
automation_taskid, vessel_ref, name, enabled, versionuuid, uuid, string, bool, int是§7 schema;签名 blob 即 Hub 存储并执行的内容
automation_tasktrigger, action, params, on_critical_alarmjson, enum, json, enum是action 仅取白名单枚举(X02-config-schema.md G-05);on_critical_alarm 默认 suppress (t)(P08-mate.md FR-16)
audit_recordid, vessel_ref, device_ref, device_sequuid, uuid, uuid, int是摄入的 X01 AUDIT(§4.6)加云端侧操作;(device_ref, device_seq)唯一约束对重放去重
audit_recordactor_kind, actor_ref, action, channel_ref, resultenum, string, enum, string, enum是/是/是/否/是何人/何事/何时/结果(P08-mate.md FR-19);仅追加,保留 ≥5 年 (t)

2.3 船舶管理、船队与身份 ​

实体字段类型必填说明
registry_itemid, vessel_ref, model, serial, install_dateuuid, uuid, string, string, date是/是/是/否/否设备登记册(P08-mate.md FR-21)
registry_itemwarranty_until, manual_refs, channel_refdate, array, string否channel_ref 自动在记录旁关联实时状态与运行时长
maintenance_taskid, vessel_ref, registry_ref, basis, intervaluuid, uuid, uuid, enum, number是basis ∈ {engine_h, runtime_h, calendar_d},基于真实计数器(P08-mate.md FR-22)
maintenance_taskdue_at, last_done_ref, handover_visiblejson, uuid, bool否/否/是完成记录是一条 work_log 时间线事件,照片/票据作为 document 引用
documentid, vessel_ref, kind, object_ref, expiry, reminder_daysuuid, uuid, enum, string, date, int是/是/是/是/否/否提醒仅为建议性,绝不构成适航性声明(P08-mate.md FR-23)
handover_packid, vessel_ref, doc_number, revision, effective_dateuuid, uuid, string, int, date是Studio 版本链中的受控工件(P08-mate.md FR-24)
handover_packconfig_version_id, mode, object_refint, enum, string是mode ∈ {full, guest_briefing};由系统生成,绝不手工编辑
fleetid, operator_ref, name, vessel_refs, checklist_templatesuuid, uuid, string, array, json是/是/是/是/否船队版(P08-mate.md FR-26);合规项引用 document 到期日
userid, email, authuuid, string, json是Passkey 或密码 + TOTP (t)(P08-mate.md §6);不要求其他个人数据
grantid, user_ref, scope_ref, role, expires_atuuid, uuid, uuid, enum, timestamp是/是/是/是/否scope_ref = 船舶或船队;role ∈ {owner, crew, charter_guest, service_provider, fleet_operator}(P08-mate.md FR-17);service_provider 授权有时限(expires_at 必填)

所有权转移(P08-mate.md FR-04)在档案导出完成后于单个事务中改写 vessel.owner_ref,删除全部既有 grant 行与会话,并追加一条 kind 为 handover 的 timeline_event;历史、登记册与审计随船舶一并转移。

3. 身份与入网 ​

步骤规则来源
设备身份HUB 与独立 AIR-GW 携带出厂预置的每设备 X.509 证书,仅出站经双向 TLS 连接;无共享密钥,无入站端口P08-mate.md FR-01、P03-hub.md §9、P05-air-gateway.md FR-17
认领流程应用扫描设备上的 QR 认领码 → 云端打开 ≤10 min (t) 的配对窗口 → 用户在设备上物理确认(按钮/屏幕)→ 云端将设备绑定到船舶与船东账户并签发船舶绑定P08-mate.md FR-02
独立 AIR-GW认领流程相同;网关即该船的上行链路(role=uplink)。之后若在同一艘船上认领 Hub,则由 Hub 接管 role=uplink,网关重新注册为 role=bus_node,无需重新认领;网关缓冲的审计经 Hub 回放P08-mate.md FR-03、P05-air-gateway.md §10 模式故障切换
证书生命周期 (t)出厂出生证书:设备整个生命周期有效,仅用于引导;运行证书:有效期 1 年,自到期前 60 天起经既有 mTLS 会话自动续期;续期与吊销事件作为时间线 presence 事件记录新增,§11
离线宽限 (t)运行证书在离线期间(越冬封存)过期的设备,可在最后一次联络后 24 个月内凭出生证书续期;超过则须重新认领新增,§11
吊销所有权转移、盗窃报案或密钥泄露会在 broker 处吊销运行证书;设备退回仅本地模式——保护与本地告警不受影响(失效安全准则,PRODUCT-PLAN.md §1)P08-mate.md FR-04

4. MQTT 接口面 ​

主题方案沿用 P08-mate.md §5,ybo/v1/<vessel>/<device>/...;broker 为 EU 区域 mTLS(P08-mate.md §3)。所有主题均为 QoS 1;仅在注明处使用 retained 标志。设备载荷是 X01 消息族(X01-ybo-can-protocol.md §4)的 JSON 编码,由 Hub/网关附加 ts_device。

主题(后缀)方向QoS载荷参照速率/限制
telemetry设备 → 云端1TELEM 页(X01-ybo-can-protocol.md §4.4)批量上送Hub 上报速率;批次 ≤60 s 或 32 KB (t);每船摄入上限持续 5 msg/s (t)
event设备 → 云端1STATE 回读与本地事件(X01-ybo-can-protocol.md §4.3)变化时上送;突发 ≤50/s (t)
alarm设备 → 云端1ALARM raise/clear(X01-ybo-can-protocol.md §4.5)+ 地理围栏/MOB立即上送,越过存储转发队列 (t)
alarm/ack云端 → 设备1{alarm_id, instance, acked_by, ts} → 总线上的 ALARM acknowledge用户确认时下发;两侧均计入审计
audit设备 → 云端1AUDIT 记录(X01-ybo-can-protocol.md §4.6)批量 ≤60 s (t);重连后补齐缺口(§9)
cmd云端 → 设备1{cmd_id (idempotency key), channel_ref, action, value, expires_at, sig}——有效期 ≤60 s (t),仅限白名单动作每船 ≤2/s (t);过期命令记录在案、绝不执行(P08-mate.md FR-20、P03-hub.md §10)
cmd/ack设备 → 云端1来自 ACK/STATE 生命周期的 {cmd_id, result, state}(X01-ybo-can-protocol.md §5)每个 cmd_id 一条;按 cmd_id 判重、幂等
config云端 ↔ 设备1签名 Studio bundle 中继 + {version_id, status} 回复(X02-config-schema.md §9)仅限部署会话;Hub 负责校验,云端仅做传输
ota云端 ↔ 设备1{image_id, ring, url, sha256, sig} 推送要约 + 进度/健康上报;ring 依次 internal → pilot → fleet,超过失败阈值自动中止 (t)按 ring 计划执行(P08-mate.md FR-29)
presence设备 → 云端1出生消息 + MQTT last-will {online: false} retained由 broker 管理;驱动 vessel.offline_since

5. REST/应用接口面 ​

全部位于 /v1 之下,按 P08-mate.md §5;WebSocket /v1/vessels/{id}/live 流式推送与 REST 资源所暴露的相同 STATE/告警/时间线事件。角色列 = 最低角色(grant.role);charter_guest 为只读加舒适性回路;每次写操作都在设备上(而非云端)重新检查舵位锁。

路径动词用途角色
/vessels · /vessels/{id}GET船舶列表与模型(设备、通道、输入、层级、offline_since)crew
/vessels/{id}/statusGET实时回读快照,每个值附各自 last_seen——仅 STATE(P08-mate.md FR-05/06)charter_guest
/vessels/{id}/timelineGET单一时间线,可按时间范围、kind、来源过滤(P08-mate.md FR-10)crew
/vessels/{id}/alarms · /alarms/{id}/ackGET · POST打开/历史告警;确认(写入 alarm/ack,§6)crew
/vessels/{id}/commandsPOST, GET下发命令(cmd_id 幂等,有效期 ≤60 s (t));轮询 pending → confirmed/revertedcrew(舒适性回路:charter_guest)
/vessels/{id}/tasksCRUD自动化任务(§7);云端校验并签名,Hub 执行owner
/vessels/{id}/registry · /maintenance · /documentsCRUD登记册、维护、文档;service_provider 仅可写工作记录(P08-mate.md FR-17)owner(工作日志:service_provider)
/vessels/{id}/handoverPOST, GET生成/列出交接包(受控工件,P08-mate.md FR-24)owner
/vessels/{id}/exportPOST, GET完整档案导出,机器可读 + PDF(P08-mate.md FR-25);须重新认证owner
/vessels/{id}/transferPOST导出完成后的所有权转移(P08-mate.md FR-04);须重新认证owner
/vessels/{id}/grantsCRUD角色与限时服务访问owner
/fleet/vessels · /fleet/checklists · /fleet/complianceGET · CRUD · GET多船状态、周转检查清单、合规(P08-mate.md FR-26)fleet_operator

6. 告警模型 ​

条目规则
严重级别notice = 记录 + 角标;warning = 推送,允许静音,自动清除;critical = 推送到全部船东/船员设备,重复直至确认,忽略静音模式(P08-mate.md §5 严重级别行、FR-07)
确认一次确认在所有位置闭环:应用 → /alarms/{id}/ack → alarm/ack 主题 → YBO-CAN 上的 ALARM acknowledge(X01-ybo-can-protocol.md §4.5)→ 设备停止本地重复;acked_by 必须与设备侧 AUDIT 记录一致,不一致本身即产生一条 notice (t)
值守/静音按用户、按船舶的模式:watch 将 warning 的送达提升为 critical 式重复;silent 静音 notice/warning 推送;两种模式均绝不抑制 critical(P08-mate.md FR-07)
升级带退避的重复 → 第二联系人 → SMS,目前仅是送达链配置桩;送达链本身仍未定(P08-mate.md §10 第 2 项、OPEN-QUESTIONS P8-6),须在 Security GA 前关闭
送达 SLA 挂钩alarm.delivery 记录每个接收人的入队/发送/送达/确认时间戳,使 FR-08 目标(4G 下 p95 Hub 事件 → 手机 ≤30 s (t))可在生产环境度量,并按每次送达记录降级情况(Wi-Fi/Starlink 传剪辑、4G 传快照、最小链路仅文本)
准则云端只做中继与记录;地理围栏/锚泊及所有安全告警均在 Hub 或模块上评估(P08-mate.md FR-09、PRODUCT-PLAN.md §1 失效安全准则);Mate 不是有人值守的安防服务(P08-mate.md §1)

7. 自动化任务 schema ​

字段类型必填说明
triggerjson是{kind: schedule, cron, timezone} 或 {kind: event, source_ref, condition, threshold, debounce_s};在 Hub/网关上评估,绝不在云端评估
action, paramsenum, json是action ∈ {set_level, run_scene, request_source, shed_feed, notify} (t)——即 X02-config-schema.md G-05 的白名单;仅随版本发布变更,绝不随配置变更(P08-mate.md FR-13)
on_critical_alarmenum是suppress(默认 (t))或 proceed,待 OPEN-QUESTIONS P8-8 定夺(P08-mate.md FR-16)
signed_blob, versionbytes, int是云端对照白名单与该船配置校验、签名并同步到 Hub;Hub 在存储前校验;云端不可达时任务持续运行(P08-mate.md FR-14)
guardrails——任务绝不能成为 critical 通道的唯一控制路径(X02-config-schema.md G-01);执行以发起方 automation 携带任务 id 进入 X01 §5 命令生命周期,故舵位锁、权限与失配升级完全照常适用
逐次执行审计——每次运行写入一条 audit_record 与一条 kind 为 automation_run 的 timeline_event,含创建者、触发时间、动作、结果与重试次数(P08-mate.md FR-15);离线时缓冲、稍后同步

8. 数据保留与隐私 ​

分层保留 (t)——引用 Level-1 各行(P08-mate.md §5 时序行、§6 保留行);所有数值待 OPEN-QUESTIONS P8-2 定夺,并在云端 beta 进入时(M10)冻结:

数据类别FreePremiumSecurityFleet
原始遥测30 天30 天30 天30 天
1 分钟汇总90 天 (t)1 年1 年1 年
1 小时汇总1 年 (t)≥5 年≥5 年≥5 年
位置历史30 天船舶整个生命周期,船东可清除船舶整个生命周期,船东可清除船舶整个生命周期,按运营方策略 (t)
摄像剪辑n/an/a30 天滚动;告警剪辑置顶保留至确认后再加 90 天按合同 (t)
审计记录≥5 年 (t)≥5 年 (t)≥5 年 (t)≥5 年 (t)
议题规则
GDPR 数据类别个人数据:位置历史、摄像剪辑、船员名册、用户账户、工作日志照片;控制者/处理者映射与 DPIA 筛查须在云端 beta 前完成(P08-mate.md §6、COMPLIANCE-MATRIX.md);EU 托管已定
位置与剪辑在已预订的租赁期间,船东/运营方看不到细于船队区域的实时位置,除非有 critical 告警处于激活状态也看不到内部剪辑(P08-mate.md §6 (t),待 P8-2 与 P11-1/2);剪辑访问计入审计日志
导出/export 即数据可携带性义务(P08-mate.md FR-25、§6):完整档案,机器可读 + PDF,可重新导入
删除账户删除移除个人数据与授权;船舶历史做匿名化而非销毁,使转售档案得以留存 (t)——匿名化范围在云端 beta 前交由法务确认(§11)

9. 离线与同步 ​

条目规则
存储转发Hub 按上报速率缓冲全部遥测/事件 ≥7 天(P08-mate.md §5);独立 AIR-GW 在 NVM 中缓冲审计(P05-air-gateway.md FR-12);重连时设备按序回放:先告警,再审计,最后遥测回填 (t)
对账云端按(device_ref, family, device_seq)及 cmd_id 去重;回放记录幂等;vessel.offline_since 仅在 presence 出生消息之后清除
时钟规则每条记录携带 ts_device 与 ts_received(P08-mate.md §5);时间线排序键优先取 ts_device,缺失时按 X01-ybo-can-protocol.md §9 由 Hub 回填,再缺失则取 ts_received 并标记 clock_unsynced (t);云端绝不改写设备时间戳
缺口处理缺失的设备序号区间在时间线上创建一个打开的 gap 标记;Hub 用 AUDIT gap request(X01-ybo-can-protocol.md §4.6)拉取节点缺口,补齐后由云端关闭该标记;超过缓冲深度仍未补齐的缺口以 data_lost 关闭并在 UI 中显示
离线命令命令在 ≤60 s (t) 内过期,链路恢复后绝不执行(P08-mate.md FR-20);已同步的自动化继续在本地运行;应用缓存最后状态与只读档案(P08-mate.md §5 离线行)

10. 验证 ​

测试方法通过判据
契约测试§4/§5 中每个 MQTT 载荷与 REST 资源在 CI 中对照生成的 JSON Schema 校验,设备模拟器与云端两侧同时进行已发布 schema 100 % 得到覆盖;未知字段策略按 X02-config-schema.md §8
负载1,000 艘模拟船舶以 Hub 上报速率运行 72 h(P08-mate.md §9 beta)无摄入丢失;p95 API 延迟 ≤500 ms;broker CPU <70 % (t)
命令幂等性重复 cmd_id 突发、5 min 链路中断后的过期命令每个 cmd_id 仅执行一次;过期后零执行
离线同步清单(a) 72 h 上行中断并恢复;(b) 缓冲溢出超过 7 天;(c) 节点时钟未同步;(d) 缓冲中途网关 → Hub 上行切换;(e) broker 故障切换后的重复回放时间线完整且有序;data_lost 缺口有标记、绝不静默;无重复;无需重新认领(P08-mate.md FR-03、§9)
告警 SLA跨 Wi-Fi/4G/最小链路的 500 条 critical 告警4G 下 p95 ≤30 s (t);遵守降级阶梯;确认可关闭设备侧重复(P08-mate.md §9)
隐私导出/删除往返;租赁隐私角色矩阵;保留到期作业审计导出可重新导入;无越权读取;过期数据已清除(P08-mate.md §9 beta 访问控制行)

11. 案头可决事项 ​

决策建议理由冻结门槛
Id 与时间戳约定UUIDv7 id、RFC 3339 UTC、按 ts_device 排序并回填与 X02-config-schema.md 的 bundle_id 选择一致;可排序 id 简化时间线分页云端 beta 进入 M10(P08-mate.md §10 第 1 项)
MQTT 批量与速率上限60 s / 32 KB 批次;每船遥测 5 msg/s、2 cmd/s、50 event/s (t)使 1,000 船 beta 保持在单一 broker 规格内;告警绕过批量云端 beta 进入 M10
证书生命周期与离线宽限运行证书 1 年,到期前 60 天起续期,出生证书宽限 24 个月越冬离线一季的船必须无需进厂即可重连云端 beta 前的安全评审
时间线 kind 枚举与缺口标记§2.2 的 11 种 kind 枚举加 gap/data_lost覆盖 FR-10 所列来源的最小集合Mate v1 范围冻结
Free 层汇总保留与匿名化删除范围Free 层 90 天 / 1 年汇总;账户删除时对船舶历史做匿名化使 Free 层成本保持在获客成本门槛内(P08-mate.md §7);保留转售档案云端 beta 进入 M10,并按 OPEN-QUESTIONS P8-2 交法务

12. 变更记录 ​

日期变更参考
2026-08-28初始附录:含单一时间线规则的实体模型、身份/认领流程、MQTT 与 REST 接口面、告警/自动化/保留/离线模型、验证清单PLAN-029

最后更新: