193 lines
6.8 KiB
TypeScript
193 lines
6.8 KiB
TypeScript
/**
|
||
* 算法插件（Route B）通用契约
|
||
* ------------------------------------------------------------
|
||
* 设计目标：
|
||
* - 算法引擎层和 UI 层完全解耦：新增算法只需添加一个 JSON manifest +
|
||
* 一个 Python 适配器，前端无需任何改动。
|
||
* - 输入是 JSON、输出是统一 `result.json`（误差统计 / 测量值 / 图片 /
|
||
* 3D 叠加层），前端按 manifest 渲染表单、按 result.json 渲染结果。
|
||
* - 进度通过子进程 stdout 行 JSON `{"type":"progress","percent":...}`
|
||
* 上报，由 runner 解析后写入 DB，前端 3s 一次轮询拿到。
|
||
*/
|
||
|
||
/** 表单字段类型——前端 AlgorithmRunPanel 据此动态渲染表单 */
|
||
export type PluginInputType =
|
||
| 'number'
|
||
| 'integer'
|
||
| 'string'
|
||
| 'boolean'
|
||
| 'select'
|
||
| 'pointcloud' // 平台自动注入：任务下的点云路径数组
|
||
| 'cad'; // 平台自动注入：该任务所属车型的 CAD 文件
|
||
|
||
export interface PluginInputField {
|
||
/** 参数名（写入 input.json `inputs.config[name]`） */
|
||
name: string;
|
||
/** UI 显示标签 */
|
||
label: string;
|
||
type: PluginInputType;
|
||
/** 默认值 */
|
||
default?: unknown;
|
||
/** number/integer 范围 */
|
||
min?: number;
|
||
max?: number;
|
||
step?: number;
|
||
/** select 选项 */
|
||
options?: { value: string; label: string }[];
|
||
/** 是否必填（默认 false——使用 default 兜底） */
|
||
required?: boolean;
|
||
/** 辅助说明，渲染在表单字段下方 */
|
||
description?: string;
|
||
}
|
||
|
||
/** 子进程运行时——真实算法 */
|
||
export interface PluginRuntimeProcess {
|
||
kind: 'process';
|
||
/** 子进程命令模板，支持占位符：
|
||
* {pythonBin} → process.env.PYTHON3_PATH || 'python3'
|
||
* {inputJson} → runner 写到 workDir/input.json 的绝对路径
|
||
* {workDir} → workDir 绝对路径
|
||
* {adapterDir} → server/plugins/adapters 的绝对路径
|
||
* {algRoot} → 算法源码根目录（用户工作区下的 alg/）
|
||
*/
|
||
cmd: string[];
|
||
/** 额外环境变量；同样支持上面的占位符 */
|
||
envExtra?: Record<string, string>;
|
||
/** 超时（毫秒），默认 20 分钟 —— 工信部要求 20 分钟内出结果 */
|
||
timeoutMs?: number;
|
||
}
|
||
|
||
/** Mock 运行时——返回预设 fixture，用于未就绪算法保证系统完整运行 */
|
||
export interface PluginRuntimeMock {
|
||
kind: 'mock';
|
||
/** 相对 server/plugins/fixtures/ 的 JSON 文件名 */
|
||
fixture: string;
|
||
/** 模拟耗时（毫秒），用于演示进度条 */
|
||
simulateMs?: number;
|
||
}
|
||
|
||
export type PluginRuntime = PluginRuntimeProcess | PluginRuntimeMock;
|
||
|
||
/** 插件 manifest（写在 server/plugins/manifests/*.json） */
|
||
export interface PluginManifest {
|
||
/** 全局唯一 ID（kebab-case，例如 coupler-panel） */
|
||
id: string;
|
||
/** 中文名，UI 显示 */
|
||
name: string;
|
||
/** 英文短名，日志 / 调试 */
|
||
shortName?: string;
|
||
description: string;
|
||
/** 算法版本，由算法团队维护 */
|
||
version: string;
|
||
/** 结果 schema 版本，写入 task_analysis_results.schemaVersion */
|
||
schemaVersion: number;
|
||
/** UI 分组标签（可选） */
|
||
category?: string;
|
||
/** 表单字段（不含点云/CAD，这两类由平台自动注入） */
|
||
inputs?: PluginInputField[];
|
||
/** 是否需要 CAD 文件（true 时若车型下无 CAD 立即报错） */
|
||
requiresCad?: boolean;
|
||
/** 是否需要点云（默认 true） */
|
||
requiresPointCloud?: boolean;
|
||
runtime: PluginRuntime;
|
||
}
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// 子进程 ↔ runner 消息协议
|
||
// ---------------------------------------------------------------------------
|
||
|
||
export interface PluginProgressEvent {
|
||
type: 'progress';
|
||
/** [0, 100] —— 我们对外用整数百分比；适配器允许 0~1 浮点，runner 自动转换 */
|
||
percent: number;
|
||
message?: string;
|
||
}
|
||
|
||
/** 测量项（GenericResultView 渲染） */
|
||
export interface PluginMeasurement {
|
||
name: string;
|
||
/** 失败任务没有有效测量值时为 null，前端显示破折号。 */
|
||
value: number | null;
|
||
unit?: string;
|
||
tolerance?: number;
|
||
/** 无法安全数值化的原始公差表达式。 */
|
||
toleranceLabel?: string;
|
||
/** pass / warning / fail / info */
|
||
status?: 'pass' | 'warning' | 'fail' | 'info';
|
||
passLabel?: string;
|
||
warningLabel?: string;
|
||
failLabel?: string;
|
||
}
|
||
|
||
/** 误差统计卡片（与原 task_analysis_results.errorStats 兼容） */
|
||
export interface PluginErrorStats {
|
||
min: number;
|
||
max: number;
|
||
mean: number;
|
||
stdDev: number;
|
||
totalPoints?: number;
|
||
withinTolerance?: number;
|
||
outOfTolerance?: number;
|
||
}
|
||
|
||
/** 3D 叠加层——交给 PointCloudViewer.pluginOverlay 消费 */
|
||
export type PluginOverlay3D =
|
||
| { kind: 'none' }
|
||
| {
|
||
/** 顶点色 Float32Array bin（与 smooth_heatmap 同格式）；
|
||
* file 是相对 outDir 的相对路径，前端通过
|
||
* /api/files/read/analysis/:taskId/:resultId/:file 拉取 */
|
||
kind: 'vertexColors';
|
||
file: string;
|
||
vertexCount: number;
|
||
dispMin: number;
|
||
dispMax: number;
|
||
}
|
||
| {
|
||
/** 着色 PLY 叠加文件（同样相对 outDir） */
|
||
kind: 'ply';
|
||
file: string;
|
||
/** 批量结果可包含多个 PLY 叠加文件 */
|
||
files?: string[];
|
||
};
|
||
|
||
/** 算法写出的 result.json（与 INTEGRATION.md 描述对齐） */
|
||
export interface PluginResult {
|
||
schemaVersion: number;
|
||
status: 'completed' | 'error';
|
||
message?: string;
|
||
measurements?: PluginMeasurement[];
|
||
errorStats?: PluginErrorStats;
|
||
overlay3d?: PluginOverlay3D;
|
||
/** 相对 outDir 的图片文件名（如 plot.png 或 images/foo.png）。
|
||
* 前端通过 /api/files/read/analysis/:taskId/:resultId/:filename 读取 */
|
||
images?: string[];
|
||
/** 相对 outDir 的可下载产物（如 report.xlsx）。
|
||
* 前端在结果面板展示下载入口。 */
|
||
files?: string[];
|
||
/** 配准算法专用：产出的衍生点云，runner 自动回写为任务点云记录。
|
||
* file 相对 outDir；name 是在任务点云列表中显示的名称。 */
|
||
derivedPointClouds?: { file: string; name: string }[];
|
||
/** 算法专属字段；前端折叠在「原始字段」里展示 */
|
||
extra?: Record<string, unknown>;
|
||
}
|
||
|
||
/** 写入数据库 task_analysis_results.resultData 的运行时元数据。
|
||
* 与原有 smooth_heatmap/assembly 沿用同一字段，方便复用前端进度条渲染。 */
|
||
export interface PluginResultData extends Partial<PluginResult> {
|
||
kind: 'plugin';
|
||
pluginId: string;
|
||
/** 0–1 实数，子进程上报后由 runner 转写 */
|
||
progress?: number;
|
||
/** 当前阶段，UI 显示 */
|
||
stage?: string;
|
||
/** 失败时的错误信息 */
|
||
error?: string;
|
||
/** 子进程已结束时的退出码 */
|
||
exitCode?: number | null;
|
||
/** 本次算法运行实际使用的任务点云文件 ID，用于前端叠加层匹配校验 */
|
||
inputPointCloudFileIds?: number[];
|
||
/** 本次算法运行前端选择的任务 CAD 文件 ID，用于后续匹配/追溯 */
|
||
inputCadFileIds?: number[];
|
||
}
|