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

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

## 1. 目的

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

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

平台进程、进度事件、产物文件等接入方式仍参考
[`docs/algorithm-integration-spec.md`](../../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. 顶层结构

```json
{
  "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[]`

推荐完整结构：

```json
{
  "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 以角度交付

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

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

```json
{
  "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 等。

统一放入：

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

中间量：

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

## 9. 禁止的旧写法

```json
{
  "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`](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. 校验方式

本目录提供两种校验：

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

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

示例自检：

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