REST API 集成场景

以下为组合已有 API 的实施方法，不表示系统自带同名自动化流程。接入前先完成认证与请求约定，确认实际部署版本、对象范围和业务责任人。

场景一：企业数据门户与数据字典

目标：业务人员能通过企业门户查到“这张表是什么、来自哪里、由谁维护、适用什么标准”。

1. 通过 /base/modelCategory/getModelCategories 定位应用系统。
2. 使用 /metadata/models/fromre/page 和 /metadata/entities/searchMetadata 分页查找对象。
3. 使用对象详情 /metadata/entities/{objectId}/get 与字段 /columns 组织数据字典。
4. 需要资产责任及分类信息时，追加资产详情，保留目录和底层对象的映射。
5. 将页面展示结果与 DAM 实际对象抽样核对，再启用定期同步。

验收：名称、Schema、描述、字段和标准关联一致；权限收回后，外部门户也能及时撤回对应缓存。元数据可见不代表业务数据可下载。

场景二：开发与建模平台统一标准

目标：开发人员使用统一的字段定义和码值，能追踪标准变化。

1. 按目录读取已发布标准，使用 domainId 获取定义。
2. 使用关联代码获取码值和版本；不要把代码列表当成码值列表。
3. 将业务定义、数据类型、长度/精度和值域展示给设计者。
4. 通过字段详情核对标准关联，形成“标准—字段—外部模型”的映射。
5. 定期比对修改时间、版本、状态和生效范围，生成待评估差异。

验收：标准内容与生效版本一致，变更有人确认；同步成功不表示模型已修改，也不表示数据库数据已满足标准。详细接口见标准与指标。

场景三：质量看板和工单协作

目标：将某业务域的检核结果转化为可追踪的问题，避免重复建单。

1. 查询技术规则和检核任务，建立规则及业务对象映射。
2. 通过任务执行结果和事件判断具体实例的运行状态。
3. 查询问题清单，保存 taskId、ruleId、jobResultId、批次和核验状态。
4. 默认向工单同步摘要、负责人和 DAM 回查入口；确需明细时经授权分页获取。
5. 工单系统更新后回查 DAM 实际整改与核验，不用外部工单关闭代替质量核验。

验收：同一异常有稳定关联键、运行状态与数据结果分开统计、业务明细不会泄露给无权用户。接口和状态口径见质量与任务。

场景四：变更上线前的血缘影响分析

目标：源表字段或指标定义变化前，明确可能受影响的下游对象。

1. 从 DAM 确定源对象，再核对其 SQLink 节点标识。
2. 使用 /sqlink/lineageGraph/query 查询限定深度的下游子图。
3. 使用 /sqlink/lineageGraph/getTransform 核对转换表达式。
4. 使用 /sqlink/lineageGraph/getImpact 得到影响清单，结合实际链路和业务责任人确认。
5. 上线后重新采集、解析并对关键下游做回归。

验收：节点映射正确、解析时间有效、查询过滤范围明确；未查到血缘不会被解释为没有影响。参数示例见血缘与图谱。

场景五：资产安全提示与合规使用

目标：使用方在申请数据前了解责任归属及安全要求。

1. 按当前集成身份浏览资产目录和已发布资产。
2. 查询资产详情中的管家、权属、安全分类及等级。
3. 必要时查询已发布安全资产及安全分类详情，区分识别建议与评审结论。
4. 引导使用者进入正式申请流程，按获批用途完成实际数据交付。

验收：资产展示不越权、安全信息来源明确、没有把分类结果当成网关策略已执行的证据。接口见资产与安全。

场景六：为智能应用提供可信上下文

目标：AI 应用能够解释业务资产和关系，并给出可核对的依据。

1. 若目标环境支持统一资产访问，使用 /graph/asset-access/v1/discovery/search 查找候选对象。
2. 使用返回的完整 assetKey 调用 /graph/asset-access/v1/context/resolve，逐项检查结果和可用性。
3. 使用图谱或 SQLink 查询补充对象关系及业务来源，保留更新时间、范围和截断标记。
4. 需要将治理规范、对象和知识组织为长期业务上下文时，按 DIG 的端到端治理创建空间、验收并发布 MCP。
5. 验证同名对象、缺少依据、无权对象和过期文档等边界问题。

验收：回答能追溯到授权对象与有效资料，缺少依据时明确说明。REST API 调用与空间 MCP 发布分别实施，不能互相代替。

上线交接清单

项目	应交付的内容
契约	方法、完整路径、参数位置、版本及响应 Schema
身份	认证方式、对象范围、有效期、轮换与撤销责任人
对象	来源系统、各服务 ID 的映射及禁止混用的标识
同步	全量/增量方式、分页终止、状态和版本处理、缓存失效
运行	请求上限、退避重试、超时、实例跟踪及异常告警
验收	已知样本、无权样本、异常分支及页面/API 对照记录
升级	接口差异、依赖适配和典型场景回归结果

本指南不预设统一限流数值、幂等头、分页上限或对外 SLA，这些需由部署与服务责任方明确。写入、审批和调度扩展必须先确认业务流程和契约，再纳入集成范围。