标准化预览 / 回放（平台超管）

POST /api/v1/research/normalize/preview · previewResearchNormalize

标准化预览 / 回放：输入一条原始记录（不入库），返回标准化结果 + 命中的质量问题。确定性（同输入同输出），供字典 / 本体变更后回放验证影响。标准化记录带完整 lineage （raw→normalized：原始记录 id + 连接器版本 + 字典版本 + 本体版本）。仅平台超管可访问。

本接口要求浏览器会话。Bearer API Token 无法调用——Token 的生命周期管理必须在网页端完成。

请求体

raw（必填）: object
raw.source（必填）: string —— 来源标识（与 connector.Name 对齐）
raw.sourceId（必填）: string
raw.sourceUrl: string
raw.observedAt: string
raw.region: string
raw.language: string
raw.sourceVersion: string
raw.nativeJson（必填）: object —— 来源原生 JSON（任意结构）
raw.contentHash（必填）: string —— 清洗后内容的 SHA-256 摘要

响应字段 · 200

record（必填）: ResearchNormalizedRecord
record.id（必填）: string
record.source（必填）: string
record.sourceId（必填）: string
record.gameKey: string —— 跨平台归一 key；null = 尚未归一（不强行合并）
record.name（必填）: string
record.fields（必填）: object —— 标准化字段（形状由各来源 normalizer 定）
record.ontologyTags（必填）: object —— 本体标签映射 {kind: [{code, confidence, source}]}
record.estimated（必填）: boolean —— 兼容字段；V2 由 metricClass=estimate 派生，禁止仅凭字段名或缺失值推断
record.lineage（必填）: ResearchNormalizedLineage
record.lineage.rawSnapshotId（必填）: string —— 原始记录 id（血缘锚点）
record.lineage.connectorVersion（必填）: string —— 连接器版本（来源版本）
record.lineage.metricVersions（必填）: object —— 标准化时引用的字典版本快照 {metric_key: version}
record.lineage.ontologyVersions（必填）: object —— 标准化时引用的本体版本快照 {kind: version}
record.normalizedAt（必填）: string
record.contentHash（必填）: string —— 标准化记录内容的 SHA-256（确定性校验）
issues（必填）: ResearchQualityIssue[] —— 命中的质量问题（不入审核队列，仅预览）
issues[].id: string
issues[].kind（必填）: enum；取值：missing_required / out_of_range / temporal_anomaly / spike / duplicate / definition_conflict / low_confidence
issues[].severity（必填）: enum；取值：warning / blocking
issues[].normalizedRecordId: string
issues[].source: string
issues[].message（必填）: string
issues[].detail（必填）: object
issues[].status: enum；取值：pending / resolved / rejected

错误

401：Problem 错误响应
403：Problem 错误响应

请求示例（curl）

curl -X POST "https://你的项目.workflow.games/api/v1/research/normalize/preview" \
  -H "Authorization: Bearer wfp_…" \
  -H "content-type: application/json" \
  --data '{"raw":{"source":"示例文本","sourceId":"018f3c2e-0000-7000-8000-000000000000","nativeJson":{},"contentHash":"示例文本"}}'

响应示例

HTTP/1.1 200
{
  "record": {
    "id": "018f3c2e-0000-7000-8000-000000000000",
    "source": "示例文本",
    "sourceId": "018f3c2e-0000-7000-8000-000000000000",
    "name": "示例标题",
    "fields": {},
    "ontologyTags": {},
    "estimated": true,
    "lineage": {
      "rawSnapshotId": "018f3c2e-0000-7000-8000-000000000000",
      "connectorVersion": "示例文本",
      "metricVersions": {},
      "ontologyVersions": {}
    },
    "normalizedAt": "示例文本",
    "contentHash": "示例文本"
  },
  "issues": [
    {
      "kind": "missing_required",
      "severity": "warning",
      "message": "示例文本",
      "detail": {}
    }
  ]
}

合同真值：OpenAPI 3.1（0.1.0）。

相关：Agent 接入指南 · 使用指南 · API 参考索引