主题
P07 · YBO Studio——配置工具(软件):每艘船电气配置及其文档的唯一真实来源
- 治理摘要: PRODUCT-PLAN.md §P7(按计划优先级表为 T0 层级:Core → Hub → Studio → Sense ≈ Key → Mate)
- 生命周期状态: spec-draft (t)
- 应用架构附录(Level 2): P07-studio-architecture.md
- 最后更新: 2026-08-27
1. 定位与层级
| 项目 | 表述(除另有标注外均引自 PRODUCT-PLAN.md) |
|---|---|
| 角色 | Web 应用(浏览器,无需安装;支持离线的 PWA,面向船厂使用),对终端用户完全开放;回路清单 → 通道分配 → 保护预设 → 绑定 → 报警规则 → 自动生成接线文档(PDF) |
| 客户 | 首先是安装商与改装船厂(渠道获客工具),其次是船主、新造船生产线(生产模式)与销售(虚拟船) |
| 层级/人员 | T0 上市关键,"配置工具护城河";SW1 负责 Studio(§2 人员分配图);Studio schema 必须在 DVT 配置测试前冻结(§4) |
| 商业模式 | 永久免费——无付费层级、无许可证密钥;收入来自硬件、YBO AC 项目和 Mate 各层级 |
| 绝不能是 | 控制面原则之外的运行时控制界面;单独做出安全决策的工具(HD 馈线与 >25 A 负载始终进入工程评审);ERP/PLM;明文密钥或未签名配置的传输渠道 |
2. 范围与边界
| 范围内(v1,按 §4 为 M4–M12) | 范围外/由其他部分负责 |
|---|---|
| 回路清单、通道分配、保护预设、PWM/调光映射、脉冲通道定义、YBO AC Layer 2 的 AC 策略表 | 运行时监控、远程开关、报警推送、登记、维护、运行时角色(驾驶台锁定、船主/船员/租船客人)——P08-mate.md、OPEN-QUESTIONS.md P8-9 |
| Key(P6)与 Air(P5)的开关/键盘/场景绑定,含 Air Gateway 独立模式 | AC 板设计、保护、联锁——合作工坊;P04-ac-interface.md |
| 编译为模块端逻辑(Core/Sense/网关)的报警规则;文档、部署/回滚/版本管理、虚拟船、生产模式、权限、离线 PWA、签名 bundle、审计 | 报警逻辑的执行(始终在模块端,失效安全原则 §1);固件镜像与 OTA 传输——P03-hub.md;云托管——§6 第 6 项 |
3. 系统位置
| 方向 | 对端 | 流动内容 |
|---|---|---|
| 依赖 | Hub(P3)+ 模块固件 | 部署端点(船上网络 HTTPS)、节点发现、配置回读与部署结果、审计日志汇聚、用于回滚的保留版本;模块能力文档(通道数/额定值、PWM/半桥/脉冲支持与脉冲上限、NVM 绑定表格式、规则容量) |
| 依赖 | Mate 云(P8) | 账户/身份、每个版本的云备份、远程部署中继(mTLS MQTT,无入站端口,§3)、与 Mate 演示模式共用的虚拟船数据集 |
| 被依赖 | Core S/M/HD、Sense、YBO AC(P4) | 通道映射、保护预设、默认状态映射、脉冲参数、输入类型/阈值、AC 干接点角色、Modbus 采集映射、策略表 |
| 被依赖 | Key(P6)、Air(P5)、Mate(P8) | 写入 Core/键盘 NVM(Key)与网关 NVM(Air)的按键语义与绑定表;独立模式下的 N2K/Modbus 目标;与接线文档同一版本链的交付包(§P8) |
4. 功能需求
回路清单与通道分配
- FR-01 每艘船体一份回路清单(名称、区域、负载类型、额定/浪涌电流、导线线径与长度、关键等级、AC/DC 域);所有下游产物均由其派生;拖放分配将每个回路映射到已发现模块的物理通道,部署前列出未分配回路与未使用通道。
- FR-02 映射规则(§P1):符合条件的 ≤25 A 支路回路 → Core S/M;馈线与 >25 A 负载 → Core HD 工程评审,加以标记,绝不自动分配为直接开关。
- FR-03 通道类型约束:调光仅限具备 PWM 能力的通道,照明区域引导至 Core S(§P1 需求 7);执行器仅限 Core M 半桥通道;AC 线圈通道声明为感性负载并定义默认状态,每个自锁回路一个通道(§P1 需求 8);双向/充电回路在 OPEN-QUESTIONS.md P1-4 关闭前予以拒绝。
保护预设与合理性检查
- FR-04 每通道的保护电流、脱扣曲线预设与过温行为来自通道最大额定值范围内经验证的预设;自由填写的值需要安装商角色覆盖并记入审计日志。
- FR-05 线径与脱扣设定的合理性检查:当脱扣值超过所声明导线载流量时阻止部署;存在硬件最大脱扣跳线时仅作提示(OPEN-QUESTIONS.md P1-8)。
- FR-06 每个模块输入馈线与区域馈线均带有必填的上游熔断器/断路器字段;空字段在接线 PDF 上打印 "UPSTREAM PROTECTION NOT DECLARED"(§P1 需求 3)。
- FR-07 经验证、带版本的船型模板预填充清单、预设与报警规则;用户提交的模板在治理流程(P7-4)建立前仅保留在本地。
- FR-08 脉冲通道类型(P4 自锁继电器):脉宽 50 ms – 1 s 且绝不超过模块上报的固件强制上限;确认窗口 5 s;再次动作间隔 ≥12 s;重试先读取状态,仅当状态 ≠ 目标时才发脉冲;连续 N 次不匹配(N = 3 (t))触发报警而不再重试。
- FR-09 报警规则(阈值、去抖、迟滞、严重级别 notice/warning/critical)在模块规则容量内编译为 Sense、Core 与 Air Gateway(Tag)的模块端逻辑;AC 安全规则(岸电丢失、发电机无输出、接触器回读不匹配)仅绑定到 Sense 数字输入,并标记为"Hub 失效后仍有效"。
开关、键盘与场景绑定
- FR-10 Key 的按键语义:切换、点动、调光(按住)、场景(长按 ≥1 s)、联锁组、驾驶台锁定;Air 手势限于短按/按住 ≥500 ms/双击;场景是带每步延时的有序通道/电平列表,未经安装商覆盖不得将关键等级回路切为 OFF。
- FR-11 护栏:无线(Air)绑定绝不作为关键等级回路的唯一控制;Studio 在接受前要求存在有线 Key 或旁路路径。
- FR-12 绑定表编译为目标的 NVM 格式(Key 为 Core/键盘 NVM,Air 为网关 NVM)并回读;Hub 不在运行时环路中。
- FR-13 Air Gateway 独立模式:目标为第三方 N2K 数字开关通道(PGN 127502 命令 / 127501 回读)或 RS-485 Modbus 寄存器;Studio 说明套件前提条件,并拒绝没有此类目标的独立项目(§6 第 11 项)。
AC 策略(YBO AC Layer 2)
- FR-14 策略表——电源优先级(岸电 > 发电机 > 逆变器)、切换延时、按馈线的卸载顺序、基于 SOC/太阳能的逆变器窗口、静音时段——部署到 Hub/Core 并在本地执行;对 Modbus 采集模块映射进行验证,使轮询周期短于 5 s 确认窗口。
- FR-15 护栏:安全关键 AC 馈线以及任何缺少 (c) 层干接点的切换路径不得绑定到自动化;SSR 类器件绝不可选作电源切换。
文档生成
- FR-16 一键从已部署版本生成接线 PDF(通道列表、端子图、上游保护、电缆清单、绑定表),作为带文档编号、修订号与生效日期的受控产物。
- FR-17 竣工与交付包来自与 Mate 数字交付(§P8)同一版本链,并携带已部署 bundle 的配置哈希;安装商签署的配置报告(姓名、日期、设置哈希)(t) 遵循 P7-2 决定的格式。
部署、回滚与版本管理
- FR-18 每次部署都是一个新的不可变版本;部署前显示语义差异(回路、预设、绑定、规则)并需明确确认。
- FR-19 部署经本地 Hub 或 Mate 中继进行;UI 仅显示每个模块经设备确认的回读(约 5 s 窗口,重试提示),绝不显示乐观状态。
- FR-20 一键回滚可重新部署任一保留版本;失败或部分确认的部署自动提供回滚;云备份在线时自动进行,离线时排队,密钥仅存在于加密备份内。
虚拟船与生产模式
- FR-21 虚拟船模拟器(无硬件)接受任意部署,模拟回读、脉冲时序、绑定、场景与报警规则,并作为 Mate 演示模式背后的数据集;电气检查深度按 P7-5。
- FR-22 生产模式 (t):基础型号与客户选配模板 → 带版本的每船体构建清单 → 下线检查表(回路/保护/通信)并记录例外 → 受控的竣工与交付包。
权限与离线
- FR-23 两种配置角色:安装商(全部设置)与船主(名称、场景、调光电平、非关键绑定);安装商可锁定安全关键设置——模型待 P7-1 决定。
- FR-24 PWA 完全离线可用:缓存的项目与 schema 片段、本地部署到 Hub、缓存会话在链路恢复时同步(P7-3)。
安全与审计
- FR-25 bundle 由用户密钥签名,在线时由云端复核签名;Hub 拒绝未签名、重放或 schema 降级的 bundle;绝不提供未获批准的无线频段或目的地配置——Studio 从 Air Gateway 读取签名的固件允许列表(§3 区域矩阵)。
- FR-26 每次部署、回滚、覆盖与角色变更均在 Hub 上记入审计日志(谁/什么/何时/结果)并镜像到云端。
5. 数据、配置与接口
| 项目 | 定义 |
|---|---|
| Schema 归属 | 由 Studio 拥有的单一 JSON 配置 schema(§1 配置模型);模块发布能力文档(产品、硬件版本、固件版本、通道数/额定值、PWM/半桥/脉冲支持、脉冲上限、绑定表版本、规则容量),Studio 在提供选项前据此验证 |
| 版本管理 | Schema major.minor:minor 新增向后兼容,major 变更随 Studio 附带迁移脚本;每个 bundle 记录 schema 版本、Studio 构建号、能力哈希与父版本;Hub 保留最近 N 个版本(N = 10 (t)) |
| Bundle 内容 | inventory、assignment、protection、bindings(按目标 NVM 格式)、alarms、ac-policy、defaults、documents(生成的 PDF + 元数据)、signature |
| 传输 | Studio → Hub:船上网络 HTTPS 或 Mate 云中继;Hub → 模块:YBO CAN FD 配置片段;Hub → Air Gateway/Key:经同一路径写入 NVM 的绑定表 |
| 发现 | Hub 枚举 YBO CAN 节点与 N2K 数字开关设备(独立模式 Air 目标);Studio 绝不假定未上报能力的模块存在 |
| 导出格式 | 接线/竣工/交付 PDF;签名 bundle JSON;CSV 电缆清单;N2K 设备列表;每船体构建清单 |
| 存储 | 浏览器 IndexedDB(PWA 缓存);Hub eMMC(已部署 + 历史);Mate 云,EU 区域(备份,§6 第 6 项) |
6. 安全、隐私与合规
| 领域 | 要求 |
|---|---|
| 合规条目 | COMPLIANCE-MATRIX.md §2 "Studio / Mate / cloud":适用范围内的 CRA,账户适用 GDPR/ePrivacy;P0 门槛:数据地图与控制者/处理者角色、DPIA 筛查、SBOM/依赖与漏洞流程、安全更新政策、法律顾问确认 CRA 角色 |
| CRA 证据 | 每次发布的 SBOM、签名发布、首次 EU 销售前漏洞接收渠道上线(矩阵 §4)、支持期声明;报告义务自 2026 年 9 月 11 日起,主要义务自 2027 年 12 月 11 日起(矩阵 §1) |
| 身份与数据 | 每用户的安装商/船主账户、每设备的 Hub 身份、无共享密码、有界离线会话 (t);bundle 除账户与船体身份外不含个人数据;Air 密钥与 Wi-Fi 凭据仅存在于加密备份内;EU 托管(§P8) |
7. 成本/商业挂钩
引自计划:永久免费——它是面向安装商的渠道获客工具;无 BOM、无 MSRP、无订阅。成本为 SW1 人力(§2 人员分配图)加上 Mate 后端内的备份存储(变动成本报价缺失,§5)。挂钩:虚拟船作为售前工具与 Mate 演示模式;安装商签署的报告作为面向保险人/验船师的交付物(P7-2);生产模式作为新造船协同工程的切入点(§4 M15+)。
8. 参照基准
| 参照对象 | 访问方式/治理(引述) | 对 Studio 的启示 |
|---|---|---|
| CZone Configuration Tool | 需要 USB 转 CAN 适配器(Mastervolt USB-CAN、Kvaser Leaf Lite、Navico ST10);船厂/经销商工作流;OEM 配置文件终端用户不可编辑——04a-czone-product-matrix.md | 无适配器、无经销商锁定:浏览器 + Hub,对终端用户开放 |
| Garmin EmpirBus Studio | 面向船厂与合格安装商;需要 Programming Interface v2 010-02575-00 及匹配版本——04b-garmin-empirbus-product-matrix.md | 通过能力发现进行版本固定,而非匹配桌面构建版本 |
| Maretron N2KAnalyzer V3 | 六个按设备编写的官方 Quick Configuration Package——04c-maretron-mpower-product-matrix.md | 经验证的船型模板(FR-07)一次部署应用于全船 |
| E-T-A PowerPlex Suite | 项目文件、版本、节点地址与密码必须导出到离线工程 PC——04d-eta-powerplex-product-matrix.md | 带版本、云端备份、可回滚的 bundle(FR-18–20) |
| Victron VictronConnect | 蓝牙/USB/网络配置、监控、固件更新与演示模式——04e-victron-marine-product-matrix.md | 演示/虚拟船模式作为销售资产(FR-21) |
9. 验证计划
| 阶段(§4) | 测试 | 方法 | 通过标准 |
|---|---|---|---|
| M4–5 原型 | Schema 验证 + 分配护栏 | JSON-schema 语料(有效、无效、降级、超出能力的 bundle);在虚拟船上对 FR-02/03/11/15 做单元测试 | 所有无效 bundle 均被拒绝并给出字段级提示,无有效 bundle 被拒绝;每个违规均被阻止,每次覆盖均记入审计日志 |
| M6–7 v1 | 文档生成 | 部署、生成 PDF、与清单比对 | PDF 与已部署 bundle 哈希一致;文档编号/修订号每次部署递增 |
| M6–7 v1 | Hub 上的部署/回滚 | 带 Core 与 Sense/Key EVT 单元的 Hub SOM 台架 | 每个节点在 5 s 内回读;回滚恢复先前 bundle 且回读一致 |
| M8–9 | 脉冲通道行为 | 经 Core 驱动的台架自锁继电器(iTL 类);注入丢失脉冲 | 先读状态再重试、≥12 s 间隔、N 次不匹配后报警、无双重切换 |
| M8–9 | Hub 关闭时的绑定表 | Key 与 Air Gateway NVM 写入/回读,Hub 断电 | 按键与开关可操作 Core;仅无线的关键绑定被拒绝 |
| M10–11 | 模拟器一致性与离线 PWA | 同一 bundle 分别用于虚拟船与演示船;48 h 无网络船厂场景 | 5 s 窗口内状态序列一致;本地部署、备份与审计同步无冲突 |
| M12 | 护栏完整 + 安全 | 被篡改、重放、降级的 bundle;角色提权 | 全部被拒绝;审计条目完整;为该发布生成 SBOM |
10. 待决事项与依赖
- ⚑ 角色与权限模型(安装商锁定安全关键设置)——OPEN-QUESTIONS.md P7-1;阻碍 FR-23 冻结。
- ⚑ 认证配置/安装商签署报告以及验船师与保险人接受的内容——P7-2;尽早与 2–3 位验船师验证。
- 离线账户(P7-3)、模板治理(P7-4)、模拟深度(P7-5)、上市语言(P7-6)。
- 硬件最大脱扣跳线与纯软件护栏之争(P1-8,决定 FR-05 是否阻止部署)、通道上的充电回路(P1-4,FR-03)、旁路粒度与显示(P1-3)。
- Core 基础上的固件/协议归属(PRODUCT-PLAN.md §6 第 1b 项)——决定 Studio 直接写入 Core 配置还是经网关节点;schema v0 仅"在供应商权利允许的范围内"(§4 M1–3);云栈/托管(§6 第 6 项);Key N2K 配置文件(P6-7)与 12 键型号(P6-6)对绑定表格式的影响。
- 产品专属 (t):N = 3 次脉冲不匹配、N = 10 个保留版本、离线会话时长——在 DVT 配置测试前的 Studio schema 冻结时冻结(§4)。
11. 变更记录
| 日期 | 变更 | 参考 |
|---|---|---|
| 2026-08-27 | 依据 PRODUCT-PLAN §1/§P1/§P4–P8/§4、OPEN-QUESTIONS P7 与 COMPLIANCE-MATRIX 起草初版规格 | PLAN-028 |