Skip to content

Latest commit

 

History

History
168 lines (109 loc) · 19 KB

backend-dashboard.md

File metadata and controls

168 lines (109 loc) · 19 KB

第三方仪表盘后端接入

本文对应匹配的 OpenTest 2.5.0 后端公共接口。日常插件构建使用宿主安装到 Maven 本地仓库的公开依赖;文末四个公共 JAR 的导出用于独立合同验收。软件验证不代替设备验收。

插件可以在任何独立工程中开发,不需要放入 opentest-plugins。按已安装内容开发准备匹配的 Maven 依赖;前端使用随仓 dev-kit。插件拥有业务配置解释、结果与图谱声明、计算节点和执行策略,宿主负责设备、通用存储、发布、安装加载及共享算法服务。

依赖与打包

Java21工程使用以下公开Maven材料,运行时均由宿主提供,设为provided:

坐标(版本2.5.0) 用途
com.opentest:opentest-plugin-api OpenTestBackendPlugin生命周期、BackendPluginRegistry登记
com.opentest:opentest-dashboard-api 配置/结果/单位/执行上下文、固定Pipeline与数据帧
com.opentest:opentest-algorithm-api 纯算法Service与独立会话合同
com.opentest:opentest-dashboard-standard-processors 可选过滤、计权、文件与图表等公共标准节点

不需要某项能力时可省略对应直接依赖。不要把这些公共类型、宿主Spring实现、algorithm runtime、旧crydaq-dashboard-sdk或DLL复制进插件JAR。第三方普通依赖由插件按包管理约束自行打包;公共接口类必须保持宿主和插件同一类型身份。

独立合同验收示例位于宿主仓库的 tools/fixtures/public-entry-plugin:它能在两个官方仓库之外仅用导出的四个 JAR 构建完整 .otplugin,包括后端入口、manifest、schema 和语言资源。public-algorithm-plugin 与 public-standard-plugin 展示更小的算法/标准节点合同。这些示例用于验证公开边界,不替代本仓库日常 Maven 依赖准备和业务界面。

实现OpenTestBackendPlugin并在register(BackendPluginRegistry)登记Provider、配置类型、运行参数类型及元数据。Provider身份属于插件命名空间;同名业务结果可以被其他插件复用。安装包、登记身份与清单应一致。调用包管理完成安装与匹配启动流程,不能只把JAR放在宿主classpath来证明插件加载成功。

当前 Provider 接口

登记时通过 MeasureProviderRegistration 提供配置类型、运行参数类型、元数据、支持的 ExecutionInputPurpose 和执行准入声明。初始配置与可选布局由 Provider 在创建仪表盘时生成,不放入注册信息。当前 DashboardProvider<C, R> 的作者入口如下:

入口 插件负责 宿主负责
initialize(DashboardInitializationContext) 返回新仪表盘的配置与可选布局 绑定项目与 Provider 身份、检查是否已存在、保存及事务
resolve(TableDefinitionQuery<C>) 根据配置、当前结果及引用、通道事实和 firstCreate 返回表定义 校验定义、绑定身份、保存及事务
editor() 提供 MeasurementEditor<C>,决定当前或历史编辑计划 校验并原子提交完整计划
describeResult(ResultDescriptionQuery<C>) 根据已绑定的结果事实补充结果描述及每个成员的单位组合 严格绑定配置、结果与查询作用域
describeResultFiles(ResultDescriptionQuery<C>) 默认声明 hash_resultCode;特殊多输出结果覆盖为实际保存的 key 在同次记录、通道及执行轮次内定位文件,区分保存单位和展示单位
resolveGraphicUnits(GraphicUnitQuery<C>) 使用完整已声明单位,默认返回 query.requireDeclaredUnits() 提供已绑定的结果、输入和单位事实
execute(ExecutionContext<C, R>) 编排准备、固定管线编译、就绪、执行和后处理 输入、资源、输出身份、持久化设施及完成边界

describeResult 返回的每个成员都应提供 declaredUnits(),历史和当前定义复用插件自身的单位规则。无量纲需要明确的空单位组合;缺少必要引用时可以返回显式的空候选菜单,不能省略单位声明或借用当前工程/Generator 配置。单位补齐必须保留保存的 hash、结果类型、参数和成员身份。

TableDefinition.algorithmCode() 是当前配置算法身份的唯一声明来源;宿主在创建、查询和编辑时消费同一正式定义,插件无需另行提供当前算法查询接口。切换测量模式时,Provider 应在完整定义中返回对应算法及有效结果。历史处理使用已保存结果的算法身份,不按当前配置重新推算。图谱通过仪表盘、视图与结果绑定确定读取范围,图谱自身的算法字段不能覆盖结果归属。

TableDefinitionQuery.currentResults() 是已保存结果及其参数、hash 和身份的事实,currentReferences() 提供当前引用。仅调整采集配置时,插件应复用仍有效的结果参数及身份;只有首次没有保存事实时才使用默认种子。默认图谱按 firstCreate 声明,不以重建默认图谱覆盖用户名称、颜色和显示通道。宿主 fixture 的 TracerPlugin.Provider.resolve(...) 示范了读取当前结果并复用其 hash 和参数。

定义和单位查询可能反复调用,不能占用执行句柄或写宿主数据库。结果定义中的通道单位必须完整、自洽;历史单位来自保存事实,不能用当前配置重算后覆盖。实际执行输出以编译时冻结的 ExecutionOutputs.results() 和 graphics() 为准。

结果内容:一份描述供当前、历史与导出使用

ResultSetDefinition.content() 是结果的数据内容描述,不是宿主流程开关。普通单曲线结果由原构造器自动提供 ResultContent.samples(resultCode);只有真实不同的数据形态需要 withContent(...):

result.withContent(ResultContent.curves(List.of(
    ResultContent.Curve.primary("response_y", "Response"),
    ResultContent.Curve.window("window_y", "Window")
)));
result.withContent(ResultContent.shared("Background", "Pa", ResultContent.Preview.THUMBNAIL));
result.withContent(ResultContent.image("measurement-surface/15"));
  • 曲线声明明确区分原生字段、已保存文件 token 和轴角色。它们不是显示别名;重复原生字段或文件 token 在构造时拒绝。普通结果不需要了解原生字段。
  • 共享数值数据给出实际文件单位及预览材料;宿主按现有精确身份读取文件,不由结果名猜单位。
  • 图片资源标识由插件选择并由插件的渲染器解释;宿主只传递 imageResource。图片不声明数值曲线或通道。
  • 同一数值结果按坐标单位保存独立文件时,用 content.withCoordinateFiles() 表达;切换坐标时精确读取对应单位的已有文件,不重写文件身份或数值。
  • 名称和成员继续用 i18nKey、channels;单位继续用成员的 GraphicUnitResolution 与 resolveGraphicUnits,可以用 GraphicUnitResolution.choices("Hz", "deg", "deg", "rad") 构造已求值的菜单。
  • 默认图谱使用 ResultSetDefinition.graphicDefaults() / withGraphicDefaults(...);ResultGraphicDefaults.Grouping 表达叠加、按通道或按单位组建卡。FFT 互谱使用 PER_UNIT_GROUP,不再写 memberSelection.ordinaryOverlayExcluded。后续编辑仍由 editor 提交增量计划,不覆盖用户已有图谱。
  • 当前视图的单位投影使用 GraphicUnitResolution.projectedCombination(),不改历史单位或保存的原始数值;例如振动 Crest Factor 只在当前视图投影为 dB。
  • resolve 和 describeResult 复用插件内部同一构造实现。历史传入当次配置、结果参数及通道事实;不序列化整份定义,也不查当前工程补历史。

Sweep 从解码原生结果的同一份目录构造曲线描述;声功率从自身配置选择共享背景数据和测面图片;FFT 互谱继续由插件解释参考/响应成员及单位。宿主图谱、曲线分组、文件导出和多记录读取消费描述,不添加这三种业务的分支。

8 个独立测量插件及宿主内置 Monitor 不再交付 dashboard-compatibility.json,宿主也不再加载独立的 dashboard-framework.json。算法与结果归属通过正式注册,当前配置、结果描述、录制和历史操作由所属 Provider 的正式接口解释。作者只需维护这些接口,不得另建兼容 JSON、隐藏 Map 键或宿主规则表来重复声明业务。确属旧无 Provider 格式、Sequence 或旧 envelope 的读取仍由其明确归属的正常边界处理,不参与 Provider 结果推断。

单位候选只经成员 GraphicUnitResolution 和 resolveGraphicUnits 提供。物理成员与 Math 成员分别查询;空候选表示当前不支持,不由宿主猜测补齐。历史查询仍须核对当次实际文件,理论候选不等于历史可用单位。Sweep 等特殊完成产物继续通过既有 describeResultFiles 返回精确保存键,多记录读取使用同一入口,不用结果 hash 猜时间窗文件身份。

仪表盘初始化

首次进入测量页面时,宿主按项目与 Provider 身份查找仪表盘;已有实例直接复用,不调用初始化或覆盖配置、布局。新实例由宿主调用一次 DashboardProvider.initialize(context),消费返回的 DashboardInitialState(configuration, layout),并在同一事务中保存配置、布局、结果集和默认图谱。失败回滚,后续重试会重新调用初始化。

DashboardInitializationContext 提供 projectId 和 providerId。插件只生成数据,不写数据库或打开设备。未覆盖 initialize 的 Provider 返回空配置与空布局;需要业务默认值的插件应显式实现:

@Override
public DashboardInitialState initialize(DashboardInitializationContext context) {
    return new DashboardInitialState(
        Map.of("probeConfig", Map.of("resolution", 2048)), "2,1");
}

layout == null 表示使用标准布局。配置必须是 JSON 对象,宿主运行时在初始化返回后递归校验、复制,保留显式 null,并隔离插件后续修改。结果与图谱仍通过 resolve 声明,初始化返回值不重复描述它们。注册阶段不调用 initialize。

升级到该接口时,删除 MeasureProviderRegistration 构造参数中的初始配置、布局,并把对应默认值迁入 Provider;宿主 SDK 与插件需要匹配编译。

配置与编辑

业务配置沿用登记的 configKey,例如 dashboardItemConfig.signalAnalysisConfig.probeConfig。采集配置仍在 dashboardItemConfig.collectConfig;宿主不要求第三方把业务子树改名为 fftConfig,也不需要新增第三方业务 DTO。Map、数组、数值、显式 null 和缺字段保留各自含义。提供者用稳定的 providerId 登记,不设置旧整数仪表盘映射。

通过 DashboardProvider.editor() 返回编辑器:

  • MeasurementEditor.editCurrent(...) 处理当前配置、参数或插件动作,返回 CurrentEditPlan。
  • MeasurementEditor.editSaved(...) 处理支持的已保存测量编辑,返回 SavedEditPlan。
  • actions() 声明插件可用动作;不支持的操作应明确拒绝。

编辑器读取宿主绑定的前后配置、结果、引用和图谱事实,声明受影响范围,由宿主统一校验和写入;不直接写数据库、执行算法或打开设备。参数、参考单位及图谱变化属于同一次编辑计划。仅修改某个字段时保留无关参数,不把“缺字段”当作“显式 null”。同名结果可以属于不同 Provider,不仅凭 resultCode 套用其他插件的参数类型。

FFT 的当前编辑入口见本仓库 plugins/fft-tools/backend/src/main/java/com/opentest/plugins/fft/measurement/FftEditor.java;宿主中完整公共定义位于 apps/backend/opentest-dashboard-api/.../measurement/editing/。旧 configurationEditPolicy、currentReferenceUnits 等方法不再是 DashboardProvider 作者入口;不要复制旧教程中的 Override。

执行与共享服务

一次执行通过 ExecutionContext 取得冻结配置、运行参数、输入用途和公开服务。宿主的 tools/fixtures/public-entry-plugin/plugin/TracerPlugin.java 使用以下结构;Config、Run 及 buildPipeline 为示例自身类型和方法:

@Override
public void execute(ExecutionContext<Config, Run> execution) throws Exception {
    AlgorithmService algorithms = execution.service(AlgorithmService.class);
    var prepared = execution.prepare();
    prepared.compile(outputs -> buildPipeline(outputs, algorithms));
    prepared.ready();
    prepared.run();
}

prepare() 依次验证输入、按默认采样准备输入并冻结事实。需要定制采样或运行期采集配置时,按公开顺序调用 selectCollectConfiguration、validateInputs、prepareInputs 和 finishPreparation,以 FFT 的 FftDashboardProvider.execute(...) 为参考。每个准备阶段只消费一次;compile(PipelinePlan) 的输出身份在发布前冻结,持有执行 ID 不等于记录已经保存。

需要响应手动停止时,通过 execution.onStopRequested(...) 登记处理,按业务边界调用 prepared.stopInput()。停止请求不等于取消或完成;prepared.run() 仍等待输入排空,必要后处理完成后才能返回。不要将 Sweep 等业务的整轮停止语义替换为立即截断。

Processor 在生命周期中通过 context().requireCapability(...) 获取公开运行能力。文件或展示能力在实际使用该分支的 onStart 中取得;不查宿主私有 Spring Bean,也不手工回灌能力。宿主负责原生库加载和共享算法服务,插件负责本次执行创建的会话。使用 execution.own(...) / prepared.own(...) 转交资源所有权,或在所属 Processor 的 close() 释放;部分初始化失败也必须清理。不要关闭其他实例的会话或共享服务,不在共享 Provider 中保留本次运行的可变状态。

固定Pipeline与数据所有权

使用ProcessorPipelineBuilder创建start/stop控制节点、业务Processor及所需标准sink,并在返回builder前连接完毕。运行中不增删节点或连接。通道、多轮和动态结果发布可以在固定节点内部处理,通过公开结果声明/发布能力完成,不回调宿主中的旧业务Handler。

输入frame由调度器管理;传递原frame须遵守retain/release合同,异步持有数组也必须明确所有权。优先复用标准持久化/图表sink,由宿主统一绑定文件、传输和结果身份。业务节点决定错误是否停止整个Pipeline;处理不了的异常保持默认失败,不能吞掉并上报成功。

持久化文件索引

文件块的任务时间、显示X轴、原始样本数和索引结束时间是不同事实。标准保存节点不应从y.length、显示步长或当前sourceEnd猜测索引。插件按原生产者合同声明每次实际保存所贡献的样本数;标准writer仅在成功写入后累计,并使用实际结果通道采样率。没有结果、单位转换失败或写入失败不能推进索引。纯显示和内存导出不应因此新增文件平台依赖。

ResultOutputMetadata.persistedIndexSampleCount声明实际累计样本数;persistedIndexEndTimeMs声明显式索引结束时间。二者互斥,默认都缺失,不由框架推断。persistedTaskRelativeTimeMs独立声明文件块时间。中间节点若重建frame、改变输出身份或单位,必须保留这些明确声明,不能只复制X/Y而丢失元数据。

既有仪表盘的计数不能统一套用:声功率简化法可能每秒只发布一个125ms窗口,但索引仍只计这个窗口;工程法原始频谱与加权频谱在44.1kHz下有不同计数。振动scalar、XYZ和Overall每次旧文件写入计1个样本,不能替换成帧任务结束时间。RT60动态结果的旧writer不声明索引,只有实际波形按输入样本数计数;不得因为动态结果有任务时间就补出索引。以上是迁移兼容事实,不是所有第三方算法必须采用的通用默认值。

已录制输入与历史重算边界

measureResultCatalogs 只登记 MeasurementResultCatalog 纯结果目录和历史解释声明,不提供独立离线任务。目录所需的配置、单位和产物解释仍属于测量,不能因删除旧任务实现而丢失。

ExecutionInputPurpose由宿主声明真实输入路径。实时采集、已录制流、导出补算和完整记录处理可以复用计算代码,但每次运行有独立节点和会话。只支持原业务已有的场景;不能因为存在统一枚举,就宣称所有仪表盘支持WAV或历史重算。

RECORDED_GRAPHIC_EXPORT不等于“必定写内存”。需要区分输出时读取公开RecordedResultOutput,按FILES/MEMORY及选择事实处理;实际结果、通道和轴必须服从冻结的ResultRequirement。不要依赖图谱集合的遍历顺序选择Hz/Bark等轴。

卸载或禁用插件并完整重启后,原始数据和配置保留,但结果查看、单位解释、导出及重算要求对应兼容插件已安装且就绪。重新安装或启用兼容插件并重启后恢复访问;数据保留不表示结果接口可以绕过插件可用性检查。

交付验证

至少证明:离开官方源码仓库仅用公开JAR可编译;安装/登记的真实ClassLoader共享公共类型且不暴露宿主私有类型;配置与单位查询可重复调用;多实例会话独立;正常、取消、失败均关闭资源;对应已录制路径沿用冻结身份、单位和原结果格式。

可以在两个官方仓库之外复现公开依赖边界。宿主维护者完成匹配后端构建后,在opentest根目录导出并复制示例:

node tools/export-plugin-dev-kit.mjs /absolute/outside/dev-kit --backend-only
cp -R tools/fixtures/public-entry-plugin /absolute/outside/fixture
node /absolute/outside/fixture/build-plugin.mjs /absolute/outside/dev-kit
node /absolute/outside/fixture/build-plugin.mjs /absolute/outside/dev-kit peer

执行该独立 fixture 验收只需复制出的示例与独立后端材料,不能据此省略日常插件工程的 Maven install。主包及 peer 必须分别构建,宿主验收时同时设置 opentest.independent.package 与 opentest.independent.peerPackage 指向实际 .otplugin。条件跳过不代表通过,记录本次实际执行数、包/JAR/SHA 及日志。--backend-only 必须指定独立输出目录,不能覆盖插件仓库的前端 dev-kit。

软件合同测试、真DLL离线数值与设备实测分别记录。若只是重新导出未改变算法实现,应先核对既有native受测源/类与最终产物身份,不把重跑所有数值用例当作默认步骤。编译成功或替身计算通过,都不等于真实设备验收。

名称和成员由已有结果定义提供,单位使用已有图形单位入口;不另设展示回调。职责及构建要求见算法结果展示。