feat: initial commit - massive-cloud point cloud processing system
This commit is contained in:
174
server/plugins/types.ts
Normal file
174
server/plugins/types.ts
Normal file
@@ -0,0 +1,174 @@
|
||||
/**
|
||||
* 算法插件（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;
|
||||
value: number;
|
||||
unit?: string;
|
||||
tolerance?: number;
|
||||
/** pass / warning / fail / info */
|
||||
status?: 'pass' | 'warning' | 'fail' | 'info';
|
||||
}
|
||||
|
||||
/** 误差统计卡片（与原 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;
|
||||
};
|
||||
|
||||
/** 算法写出的 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[];
|
||||
/** 算法专属字段；前端折叠在「原始字段」里展示 */
|
||||
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;
|
||||
}
|
||||
Reference in New Issue
Block a user