massive-cloud/alg/00_算法交付与输出规范/README.md

算法交付与测量结果输出规范

版本：1.0.0 状态：自 2026-08-13 起，新交付算法必须遵循；存量算法逐步迁移。 适用范围：alg/ 下所有向宏量点云处理平台输出测量结果的算法。

1. 目的

本规范统一算法 result.json 中正式测量结果的表达，解决以下问题：

• 任务号被写在名称字符串里，例如 任务46_车体横断面对角线差值；
• 同一任务的多个测量位置无法分组，例如任务 5 的左梁和右梁；
• 头车、中车使用不同任务号，但结果中没有检测对象上下文；
• dx_y、dx_z 等计算中间量混入正式测量结果；
• 前端只能解析中文名称，无法稳定排序、筛选、统计和生成报告。

平台进程、进度事件、产物文件等接入方式仍参考 docs/algorithm-integration-spec.md。涉及测量结果字段时，以本规范为准。

2. 基本原则

1. 任务号结构化：正式测量项必须提供 taskNo，不得只写进 name。
2. 名称不编码：name 只写项目名称，不包含 任务XX_、左右位置或车型前缀。
3. 指标编码稳定：每项结果必须有稳定的 metricCode，程序关联以它为准，不能依赖中文名称。
4. 一个测量值一条记录：同一任务存在左/右、前/后等多个结果时，保留多条记录并使用 position 区分，taskNo 相同。
5. 正式结果与中间量隔离：只有可交付、可判定、可进入报告的值才能进入 measurements；中间量放入 extra.intermediateMetrics。
6. 不猜任务号：任务号必须来自经确认的业务任务清单。无法确定时应阻止正式交付并请求确认，不能按数组序号或名称相似度推断。
7. 值和单位分离：value 必须是 JSON 数值或 null；禁止输出 "0.073/700mm" 这样的混合字符串。
8. JSON 必须标准合法：禁止 NaN、Infinity；失败且无有效值时使用 null。

3. 职责边界

3.1 业务/产品负责人

• 提供并确认正式任务清单：taskNo、项目名称、适用检测对象、理论值、公差、单位；
• 审批任务号变更，算法工程师不得自行重新编号。

3.2 平台/集成人员

• 在算法输入或适配层提供 inspectionObject，例如 head（头车）、middle（中车）；
• 将经确认的业务任务清单配置为映射表；
• 校验最终 result.json，不让缺少任务号的正式结果进入业务表格。

3.3 算法工程师

• 为算法指标定义稳定的 metricCode 和准确的 name；
• 输出 position 等算法能够确定的测量位置；
• 在已获得检测对象和任务映射时输出正确的 taskNo；
• 只把最终可交付结果放进 measurements，中间量放进 extra.intermediateMetrics；
• 交付前运行本目录的校验脚本。

最终写入平台的 result.json 必须满足本规范。若算法核心包不负责业务任务号，平台薄适配层必须在写出 result.json 前补齐，不能交给前端猜测。

4. 顶层结构

{
  "schemaVersion": 1,
  "measurementContractVersion": "1.0",
  "status": "completed",
  "message": "测量完成",
  "context": {
    "inspectionObject": "head",
    "inspectionObjectName": "头车"
  },
  "measurements": [],
  "extra": {
    "intermediateMetrics": []
  }
}

字段说明：

字段	必填	说明
schemaVersion	是	平台插件结果版本；当前平台存量插件仍使用 1
measurementContractVersion	是	本测量结果规范版本，当前固定为 "1.0"
status	是	completed 或 error
message	否	面向用户的简短说明
context	有对象差异时必填	本次测量的业务上下文
measurements	完成时必填	正式测量结果；允许空数组，不允许混入调试指标
extra	否	算法报告、质量信息、中间量等非正式结果

schemaVersion 与 measurementContractVersion 含义不同，不得互相替代。

5. 正式测量项 measurements[]

推荐完整结构：

{
  "taskNo": "5",
  "metricCode": "underframe.longitudinal_beam.vertical_deflection",
  "name": "纵向梁到直线的垂直偏差（挠度）",
  "position": "左梁",
  "value": 0.265,
  "unit": "mm",
  "tolerance": 7.0,
  "toleranceLabel": "±7 mm",
  "status": "pass"
}

字段	必填	类型/取值	说明
taskNo	是	字符串	正式业务任务号；即使全是数字也必须用字符串
metricCode	是	字符串	稳定指标编码，建议 <域>.<部件>.<指标>，仅用小写字母、数字、点、下划线和短横线
name	是	字符串	纯项目名称，不带 任务XX_ 和位置前缀
position	多位置时必填	字符串	如 左梁、右梁、一位端；不适用时省略
value	是	数值或 null	测量值；无有效结果时为 null
unit	有量纲时必填	字符串	如 mm、°、%；无量纲使用 "1"
theoreticalValue	否	数值	理论值，与 unit 相同
baseline	斜率形式时必填	正数	基准长度，单位为 mm
tolerance	简单对称公差时使用	非负数	±tolerance，与 unit 相同；斜率形式表示分子公差
toleranceLower	非对称公差时使用	数值	相对理论值的下偏差
toleranceUpper	非对称公差时使用	数值	相对理论值的上偏差
toleranceLabel	复杂公差时使用	字符串	报告展示原文，例如 +8.5/-3 mm
status	是	pass / warning / fail	正式结果不得使用 info
qualityFlags	否	字符串数组	质量告警代码，不替代 status

约束：

• 同一 taskNo + metricCode + position 在一次结果中必须唯一；
• name 不得匹配 ^任务\s*\d+；
• status=pass|warning|fail 必须基于已确认的公差规则；
• value=null 时不得判为 pass；
• 若尚未获得正式任务号，该项不得进入最终 measurements。

6. 检测对象与任务号映射

当同一指标在不同检测对象上对应不同任务号时，必须先根据 context.inspectionObject 选择任务号。

本次已确认的映射如下：

检测对象	指标	taskNo
任意	纵向梁到直线的垂直偏差（左、右挠度）	5
头车 head	车钩面板到参考面的右偏转角	8
中车 middle	车钩面板到参考面的右偏转角	9
头车 head	车钩面板到纵向中心的右偏转角	10
中车 middle	车钩面板到纵向中心的右偏转角	12

任务 5 的左右梁应输出两条记录：两条的 taskNo 和 metricCode 相同，position 分别为 左梁、右梁。

如果输入中没有头车/中车信息，车钩算法不得自行默认成头车；应报契约错误，或由平台适配层在具备检测对象信息后完成映射。

7. 斜率形式与角度值

车钩“右偏转角”目前存在两种可能的交付口径，必须由业务任务清单明确：

7.1 以角度交付

{
  "value": 0.0063,
  "unit": "°",
  "tolerance": 0.08
}

7.2 以偏差值/基准长度交付

{
  "value": 0.073,
  "unit": "mm",
  "baseline": 700,
  "tolerance": 1.0,
  "toleranceLabel": "1/700 mm"
}

禁止把 value 写成字符串 "0.073/700mm"。角度值和换算后的偏差值不能共用同一个 metricCode；如两者都需保留，一个作为正式结果，另一个放入中间量并使用不同编码。

8. 中间数据与诊断数据

以下数据通常不属于正式测量项：拟合系数、法向量、点数、残差、dx_y、dx_z、D_y、D_z、ICP fitness、RMSE 等。

统一放入：

{
  "extra": {
    "intermediateMetrics": [
      {
        "metricCode": "coupler.panel.dx_y_max",
        "name": "Y 方向计算用最大 X 偏差",
        "value": 0.0101,
        "unit": "mm"
      }
    ]
  }
}

中间量：

• 不需要 taskNo；
• 不设置业务 status 和公差；
• 不进入“算法结果”项数、合格率和正式报告；
• 可用于日志、排障和算法复核。

9. 禁止的旧写法

{
  "measurements": [
    { "name": "任务46_车体横断面对角线差值", "value": 0.592 },
    { "name": "左梁 · 纵向梁到直线的垂直偏差（挠度）", "value": 0.265 },
    { "name": "最大 x 偏差 dx_y", "value": 0.010, "status": "pass" }
  ]
}

问题分别是：任务号嵌入名称、位置嵌入名称、中间量冒充正式结果。

正确写法见 examples/head-car-coupler-and-deflection.result.json。

10. 兼容与迁移

• 本规范是目标输出契约。当前平台前端尚未使用所有新增字段时，也必须保留这些字段，不能因此退回名称拼接方案；
• 存量 任务46_xxx 等结果允许历史回放，但算法下一版本应拆为 taskNo="46" 和纯 name；
• 平台适配层可以暂时从经确认的旧配置中迁移任务号，但不得长期正则解析中文名称；
• 修改任务号、单位、换算口径、公差或 metricCode 均属于接口变更，必须在算法版本说明中记录；
• 核心计算方法未变、只调整输出结构时，也应至少提升算法补丁版本并注明“输出契约迁移”。

11. 交付检查清单

算法工程师提交前逐项确认：

• result.json 是 UTF-8 标准 JSON，无 NaN/Infinity
• 顶层包含 measurementContractVersion: "1.0"
• 每个正式测量项都有 taskNo、metricCode、纯 name、value、status
• 多位置结果使用相同任务号并通过 position 区分
• 头车/中车任务号来自 context.inspectionObject，没有默认猜测
• measurements 中没有 info 状态和算法中间量
• 单位、公差、理论值和换算口径与正式任务清单一致
• extra.intermediateMetrics 中的指标不参与合格判定
• 已执行：python3 validate_result.py result.json
• 版本说明记录了输出字段变化

12. 校验方式

本目录提供两种校验：

# 零第三方依赖，执行本规范的关键业务规则校验
python3 validate_result.py /path/to/result.json

# 如本机安装了 jsonschema，可进行完整 JSON Schema 校验
python3 -m jsonschema -i /path/to/result.json result.schema.json

示例自检：

python3 validate_result.py examples/head-car-coupler-and-deflection.result.json