跳转到内容

P03 · YBO Mate —— 软件设计附录:数据模型与 API

类型设计状态草案版本R0.2更新2026-09-22

集成范围更新(2026-09-10):本文的独立 AIR-HUB 云上行、设备身份与存储转发条目依赖单独选择的网关扩展;当前基础 Air Hub只推荐 BLE/CAN,不作云客户端。HUB 相关条目不受影响。

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

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

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

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

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

章节标题:“2.1 船舶与拓扑(镜像已部署的 Studio 配置版本)”
实体 字段 类型 必填 说明
vessel id, hull_id, name uuid, string, string 是 hull_id 来自 X02-config-schema.md 的 vessel 对象;单一船东账户
vessel owner_ref, tier, config_version_id uuid, enum, int 是 tier ∈ {free, premium, security, fleet}(P03-mate.md §2.5);当前生效的 Studio 版本(X02-config-schema.md §2)
vessel install_mode, region, offline_since enum, enum, timestamp 是/是/否 system 或 standalone_air(X02-config-schema.md G-13);EU 托管已定(P03-mate.md §7)
device id, vessel_ref, class, uid uuid, uuid, enum, string 是 class ∈ X01 node classes;64 位出厂 UID 十六进制(X01-ybo-can-protocol.md §2)
device role, cert_serial, fw_version, last_seen enum, string, string, timestamp 是/是/否/否 role ∈ {uplink, bus_node};每艘船恰好一个 uplink(§3)
channel id, device_ref, index, type string, uuid, int, enum 是 id 与 type 在部署时从 X02-config-schema.md §4.1 复制;绝不在 Mate 中编辑
channel circuit_name, zone, critical, state string, string, bool, enum 是 state ∈ X01 channel-state enum,仅由 STATE 写入(X01-ybo-can-protocol.md §4.3)
channel current_a, level_pct, trip_reason, last_seen number, number, enum, timestamp 否 最近一次回读,附每个值各自的 "last seen"(P03-mate.md SFR-06)
input id, device_ref, index, type, role string, uuid, int, enum, enum 是 来自 X02-config-schema.md §3 inputs;type ∈ {di, ai}
input value, unit, quality, last_seen number, string, enum, timestamp 否 quality ∈ {ok, wire_break, sensor_fault},取自 TELEM 标志(X01-ybo-can-protocol.md §4.4)
实体 字段 类型 必填 说明
timeline_event id, vessel_ref, kind uuid, uuid, enum 是 kind ∈ {state, alarm, command, automation_run, quick_log, work_log, document, handover, config_deploy, ota, presence} (t)
timeline_event ts_device, ts_received timestamp, timestamp 否/是 每条记录均含两者(P03-mate.md §5.2 时间线行);节点时钟未同步时 ts_device 为 null(X01-ybo-can-protocol.md §9)
timeline_event source_kind, source_ref, payload enum, string, json 是 source_kind ∈ {device, channel, input, user, task, cloud};payload 结构按 kind 定义,仅追加
alarm id, vessel_ref, severity, code, channel_ref uuid, uuid, enum, enum, string 是/是/是/是/否 severity ∈ {notice, warning, critical};code 来自 X01-ybo-can-protocol.md §4.5 加云端代码(地理围栏、MOB、Eye、离线)(t)
alarm raised_at, cleared_at, acked_at, acked_by timestamp ×3, uuid 是/否/否/否 ALARM raise/clear/acknowledge 的阶段镜像;流程见 §6
alarm delivery, clip_ref json, uuid 否 面向 SFR-08 SLA 的按接收人推送/确认日志;置顶的 Eye 剪辑(P03-mate.md SFR-27)
automation_task id, vessel_ref, name, enabled, version uuid, uuid, string, bool, int 是 §7 schema;签名 blob 即 Hub 存储并执行的内容
automation_task trigger, action, params, on_critical_alarm json, enum, json, enum 是 action 仅取白名单枚举(X02-config-schema.md G-05);on_critical_alarm 默认 suppress (t)(P03-mate.md SFR-16)
audit_record id, vessel_ref, device_ref, device_seq uuid, uuid, uuid, int 是 摄入的 X01 AUDIT(§4.6)加云端侧操作;(device_ref, device_seq)唯一约束对重放去重
audit_record actor_kind, actor_ref, action, channel_ref, result enum, string, enum, string, enum 是/是/是/否/是 何人/何事/何时/结果(P03-mate.md SFR-19);仅追加,保留 ≥5 年 (t)
实体 字段 类型 必填 说明
registry_item id, vessel_ref, model, serial, install_date uuid, uuid, string, string, date 是/是/是/否/否 设备登记册(P03-mate.md SFR-21)
registry_item warranty_until, manual_refs, channel_ref date, array, string 否 channel_ref 自动在记录旁关联实时状态与运行时长
maintenance_task id, vessel_ref, registry_ref, basis, interval uuid, uuid, uuid, enum, number 是 basis ∈ {engine_h, runtime_h, calendar_d},基于真实计数器(P03-mate.md SFR-22)
maintenance_task due_at, last_done_ref, handover_visible json, uuid, bool 否/否/是 完成记录是一条 work_log 时间线事件,照片/票据作为 document 引用
document id, vessel_ref, kind, object_ref, expiry, reminder_days uuid, uuid, enum, string, date, int 是/是/是/是/否/否 提醒仅为建议性,绝不构成适航性声明(P03-mate.md SFR-23)
handover_pack id, vessel_ref, doc_number, revision, effective_date uuid, uuid, string, int, date 是 Studio 版本链中的受控工件(P03-mate.md SFR-24)
handover_pack config_version_id, mode, object_ref int, enum, string 是 mode ∈ {full, guest_briefing};由系统生成,绝不手工编辑
fleet id, operator_ref, name, vessel_refs, checklist_templates uuid, uuid, string, array, json 是/是/是/是/否 船队版(P03-mate.md SFR-26);合规项引用 document 到期日
user id, email, auth uuid, string, json 是 Passkey 或密码 + TOTP (t)(P03-mate.md §7);不要求其他个人数据
grant id, user_ref, scope_ref, role, expires_at uuid, uuid, uuid, enum, timestamp 是/是/是/是/否 scope_ref = 船舶或船队;role ∈ {owner, crew, charter_guest, service_provider, fleet_operator}(P03-mate.md SFR-17);service_provider 授权有时限(expires_at 必填)

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

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

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

主题(后缀) 方向 QoS 载荷参照 速率/限制
telemetry 设备 → 云端 1 TELEM 页(X01-ybo-can-protocol.md §4.4)批量上送 Hub 上报速率;批次 ≤60 s 或 32 KB (t);每船摄入上限持续 5 msg/s (t)
event 设备 → 云端 1 STATE 回读与本地事件(X01-ybo-can-protocol.md §4.3) 变化时上送;突发 ≤50/s (t)
alarm 设备 → 云端 1 ALARM raise/clear(X01-ybo-can-protocol.md §4.5)+ 地理围栏/MOB 立即上送,越过存储转发队列 (t)
alarm/ack 云端 → 设备 1 {alarm_id, instance, acked_by, ts} → 总线上的 ALARM acknowledge 用户确认时下发;两侧均计入审计
audit 设备 → 云端 1 AUDIT 记录(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);过期命令记录在案、绝不执行(P03-mate.md SFR-20、P03-mate.md §3.3)
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 计划执行(P03-mate.md SFR-29)
presence 设备 → 云端 1 出生消息 + MQTT last-will {online: false} retained 由 broker 管理;驱动 vessel.offline_since

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

路径 动词 用途 角色
/vessels · /vessels/{id} GET 船舶列表与模型(设备、通道、输入、层级、offline_since) crew
/vessels/{id}/status GET 实时回读快照,每个值附各自 last_seen——仅 STATE(P03-mate.md SFR-05/06) charter_guest
/vessels/{id}/timeline GET 单一时间线,可按时间范围、kind、来源过滤(P03-mate.md SFR-10) crew
/vessels/{id}/alarms · /alarms/{id}/ack GET · POST 打开/历史告警;确认(写入 alarm/ack,§6) crew
/vessels/{id}/commands POST, GET 下发命令(cmd_id 幂等,有效期 ≤60 s (t));轮询 pending → confirmed/reverted crew(舒适性回路:charter_guest)
/vessels/{id}/tasks CRUD 自动化任务(§7);云端校验并签名,Hub 执行 owner
/vessels/{id}/registry · /maintenance · /documents CRUD 登记册、维护、文档;service_provider 仅可写工作记录(P03-mate.md SFR-17) owner(工作日志:service_provider)
/vessels/{id}/handover POST, GET 生成/列出交接包(受控工件,P03-mate.md SFR-24) owner
/vessels/{id}/export POST, GET 完整档案导出,机器可读 + PDF(P03-mate.md SFR-25);须重新认证 owner
/vessels/{id}/transfer POST 导出完成后的所有权转移(P03-mate.md SFR-04);须重新认证 owner
/vessels/{id}/grants CRUD 角色与限时服务访问 owner
/fleet/vessels · /fleet/checklists · /fleet/compliance GET · CRUD · GET 多船状态、周转检查清单、合规(P03-mate.md SFR-26) fleet_operator
条目 规则
严重级别 notice = 记录 + 角标;warning = 推送,允许静音,自动清除;critical = 推送到全部船东/船员设备,重复直至确认,忽略静音模式(P03-mate.md §5.2 严重级别行、SFR-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(P03-mate.md SFR-07)
升级 带退避的重复 → 第二联系人 → SMS,目前仅是送达链配置桩;送达链本身仍未定(P03-mate.md §10 软件 2、OPEN-QUESTIONS §P3 软件 6),须在 Security GA 前关闭
送达 SLA 挂钩 alarm.delivery 记录每个接收人的入队/发送/送达/确认时间戳,使 SFR-08 目标(4G 下 p95 Hub 事件 → 手机 ≤30 s (t))可在生产环境度量,并按每次送达记录降级情况(Wi-Fi/Starlink 传剪辑、4G 传快照、最小链路仅文本)
准则 云端只做中继与记录;地理围栏/锚泊及所有安全告警均在 Hub 或模块上评估(P03-mate.md SFR-09、product-plan.md §1 失效安全准则);Mate 不是有人值守的安防服务(P03-mate.md §1)
字段 类型 必填 说明
trigger json 是 {kind: schedule, cron, timezone} 或 {kind: event, source_ref, condition, threshold, debounce_s};在 Hub/网关上评估,绝不在云端评估
action, params enum, json 是 action ∈ {set_level, run_scene, request_source, shed_feed, notify} (t)——即 X02-config-schema.md G-05 的白名单;仅随版本发布变更,绝不随配置变更(P03-mate.md SFR-13)
on_critical_alarm enum 是 suppress(默认 (t))或 proceed,待 OPEN-QUESTIONS §P3 软件 8 定夺(P03-mate.md SFR-16)
signed_blob, version bytes, int 是 云端对照白名单与该船配置校验、签名并同步到 Hub;Hub 在存储前校验;云端不可达时任务持续运行(P03-mate.md SFR-14)
guardrails — — 任务绝不能成为 critical 通道的唯一控制路径(X02-config-schema.md G-01);执行以发起方 automation 携带任务 id 进入 X01 §5 命令生命周期,故舵位锁、权限与失配升级完全照常适用
逐次执行审计 — — 每次运行写入一条 audit_record 与一条 kind 为 automation_run 的 timeline_event,含创建者、触发时间、动作、结果与重试次数(P03-mate.md SFR-15);离线时缓冲、稍后同步

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

数据类别 Free Premium Security Fleet
原始遥测 30 天 30 天 30 天 30 天
1 分钟汇总 90 天 (t) 1 年 1 年 1 年
1 小时汇总 1 年 (t) ≥5 年 ≥5 年 ≥5 年
位置历史 30 天 船舶整个生命周期,船东可清除 船舶整个生命周期,船东可清除 船舶整个生命周期,按运营方策略 (t)
摄像剪辑 n/a n/a 30 天滚动;告警剪辑置顶保留至确认后再加 90 天 按合同 (t)
审计记录 ≥5 年 (t) ≥5 年 (t) ≥5 年 (t) ≥5 年 (t)
议题 规则
GDPR 数据类别 个人数据:位置历史、摄像剪辑、船员名册、用户账户、工作日志照片;控制者/处理者映射与 DPIA 筛查须在云端 beta 前完成(P03-mate.md §7、compliance-matrix.md);EU 托管已定
位置与剪辑 在已预订的租赁期间,船东/运营方看不到细于船队区域的实时位置,除非有 critical 告警处于激活状态也看不到内部剪辑(P03-mate.md §7 (t),待 §P3 软件 2 与 §P11 1/2);剪辑访问计入审计日志
导出 /export 即数据可携带性义务(P03-mate.md SFR-25、§7):完整档案,机器可读 + PDF,可重新导入
删除 账户删除移除个人数据与授权;船舶历史做匿名化而非销毁,使转售档案得以留存 (t)——匿名化范围在云端 beta 前交由法务确认(§11)
条目 规则
存储转发 Hub 按上报速率缓冲全部遥测/事件 ≥7 天(P03-mate.md §5.2);独立 AIR-HUB 在 NVM 中缓冲审计(扩展,P05-air-hub-design.md §2.4);重连时设备按序回放:先告警,再审计,最后遥测回填 (t)
对账 云端按(device_ref, family, device_seq)及 cmd_id 去重;回放记录幂等;vessel.offline_since 仅在 presence 出生消息之后清除
时钟规则 每条记录携带 ts_device 与 ts_received(P03-mate.md §5.2);时间线排序键优先取 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) 内过期,链路恢复后绝不执行(P03-mate.md SFR-20);已同步的自动化继续在本地运行;应用缓存最后状态与只读档案(P03-mate.md §5.2 离线行)
测试 方法 通过判据
契约测试 §4/§5 中每个 MQTT 载荷与 REST 资源在 CI 中对照生成的 JSON Schema 校验,设备模拟器与云端两侧同时进行 已发布 schema 100 % 得到覆盖;未知字段策略按 X02-config-schema.md §8
负载 1,000 艘模拟船舶以 Hub 上报速率运行 72 h(P03-mate.md §9.4 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 缺口有标记、绝不静默;无重复;无需重新认领(P03-mate.md SFR-03、§9)
告警 SLA 跨 Wi-Fi/4G/最小链路的 500 条 critical 告警 4G 下 p95 ≤30 s (t);遵守降级阶梯;确认可关闭设备侧重复(P03-mate.md §9.4)
隐私 导出/删除往返;租赁隐私角色矩阵;保留到期作业审计 导出可重新导入;无越权读取;过期数据已清除(P03-mate.md §9.4 beta 访问控制行)
决策 建议 理由 冻结门槛
Id 与时间戳约定 UUIDv7 id、RFC 3339 UTC、按 ts_device 排序并回填 与 X02-config-schema.md 的 bundle_id 选择一致;可排序 id 简化时间线分页 云端 beta 进入 M10(P03-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 覆盖 SFR-10 所列来源的最小集合 Mate v1 范围冻结
Free 层汇总保留与匿名化删除范围 Free 层 90 天 / 1 年汇总;账户删除时对船舶历史做匿名化 使 Free 层成本保持在获客成本门槛内(P03-mate.md §8.2);保留转售档案 云端 beta 进入 M10,并按 OPEN-QUESTIONS §P3 软件 2 交法务
日期 版本 变更 记录
2026-08-28 R0.1 初始附录:含单一时间线规则的实体模型、身份/认领流程、MQTT 与 REST 接口面、告警/自动化/保留/离线模型、验证清单 PLAN-029
2026-09-22 R0.2 关系行、标题与变更记录按文档规范;规格章节引用改到 R0.3 编号;软件条目误引的 FR-07/08/10/12 改为 SFR-;OPEN-QUESTIONS 引用改为 §P3 软件 n 任务 20260922-0746