DATA_CONTRACT.md 2.0 KB

Fake 数据合同与已知缺口

新版只提供 fake 数据,但顶层字段不使用自创命名。backend/app/contracts.py 逐项镜像以下当前源码合同:

  • Host:ScriptBuildInputSnapshotV1MissionBindingMissionOwnerToken、全部 Phase 1/2/3 Artifact、PublicationPublicationResult、HTTP command journal、旧 script_build_record
  • Agent wire:TaskViewTaskSpecViewOperationViewAttemptViewValidationViewPlannerDecisionView
  • 枚举:Build / Task / Attempt / Validation / Artifact / Publication 状态,以及全部 ScriptTaskKind

每个画布节点的 record.model_name 指向其中一个合同,record.payload 必须与合同完全同键。后端测试同时拒绝缺键和额外键。

不能由当前源码进一步约束的字段

以下字段在业务源码中本身就是开放的 dict[str, Any] / JSON,没有更窄的稳定 schema,因此 fake 数据只能保持顶层字段精确,不能声称其嵌套键是产品合同:

  • topicaccountpersona_pointssection_patternsstrategies
  • prompt_manifestdatasource_manifestmodel_manifest
  • querysource_lineagechange_manifest
  • Agent payload、ArtifactRef metadata、HTTP response_json
  • Paragraph 的 content_range 与各类 *_elements
  • Element 的 commonality_analysistopic_supportweight_scoresupport_elements

接真实数据前仍缺少

  1. Host 面向可视化的只读聚合 API;当前没有一个接口能直接返回 Phase 1→3 的完整闭包和连接关系。
  2. TraceStore 中消息父链、policy migration、owner acquire/release/fence、publication attempt/rollback/commit/readback 的统一脱敏投影。
  3. Candidate Artifact / Validation / Decision 的批量分页读取接口,避免前端逐节点请求。
  4. 对上述开放 JSON 字段的版本化 strict schema。没有这些 schema 时,任何“嵌套字段一模一样”的承诺都不可验证。