AI 资讯 知识库 本体论本体构建平台详细架构设计:研发实施版(模块边界、建表 SQL 与接口契约)

本体构建平台详细架构设计:研发实施版(模块边界、建表 SQL 与接口契约)

01 设计范围与验收路径

研发评审稿 v1.1 · 2026-11-17 面向平台负责人、领域建模人员、数据工程师、应用开发与运维。目标是交付一套可供多个团队构建、验证、发布和使用本体的基础设施。以下服务边界、数据结构和接口是建议设计,容量与恢复指标是试点验收目标。

核心交付物是一组可复现的发布包。每个包固定概念、关系、公理、约束、映射、查询和测试的修订。每个环境再选择一个包及其相容的数据投影,对外承担读服务。同一环境中的一次请求必须始终使用同一组版本。

---
config:
  look: handDrawn
---
flowchart LR
 A["作者提交定义"] --> B["形成变更集"]
 B --> C["构建候选包"]
 C --> D["评审与批准"]
 D --> E["环境激活"]
 E --> F["应用查询"]
 C -. "差异与失败样本" .-> A

图 01 平台交付路径。 实线表示发布依赖,虚线将测试反馈交还给作者。发布包、批准记录和激活记录必须可以分别寻址。

设计问题 评审位置 首版通过条件
谁能改什么,多个作者怎样协作 02–04 同基线并发编辑能识别冲突,草稿只在工作区可见
本体怎样落库,如何接数与验证 05–08 同一组固定输入可复现模型和数据检查结果
应用怎样采用版本,失败怎样恢复 09–13 任一请求可追溯版本,切换中断后可判定结果
研发如何交付 14–21 通过接口、故障演练及第二个领域的接入验收

贯穿样例。 银行团队把“担保方”拆成两个角色。设备团队随后在同一平台建立维修模型,以此检验模块、权限、连接器和发布机制是否可复用。银行审批、贷款交易和设备调度由各自的业务系统执行。平台负责提供有版本的定义与证据。

02 系统上下文与责任边界

---
config:
  look: handDrawn
---
flowchart TB
 subgraph Users["平台使用者"]
 A["领域作者 / 数据工程师"]
 B["评审人 / 发布负责人"]
 C["业务应用 / Agent"]
 end
 A -->|"编辑、样本预览"| P["本体构建平台"]
 B -->|"批准产物、激活环境"| P
 C -->|"发现、查询、校验"| P
 P -->|"按范围读取"| S["数据仓库 / 业务 API / 文档库"]
 P -->|"校验主体、读取密钥引用"| I["身份与密钥服务"]
 P -->|"追加发布与访问事件"| L["审计归档"]

图 02 系统上下文。 上方是三个身份入口。向下的箭头是平台必须取得的外部能力。文档的原始访问范围必须随证据引用传递。

边界 平台负责 对接方负责
身份与租户 从已验证会话派生租户、用途及环境,检查每次资源访问 身份系统维护人员、组、服务账户及停用信息
模型与业务数据 管理定义、映射、出处、投影版本和数据新鲜度 来源系统维护交易真值、更新游标、删除语义和读取授权
应用与 Agent 提供稳定 ID、发布说明、具名查询和证据引用 应用登记所依赖接口,处理过期、缺失、无权和版本淘汰
运行边界 对动作提议给出语义检查报告和证据版本 动作服务在提交时重新授权,由权威系统维持业务不变量

部署假设。 首版按单组织、多团队、多个逻辑租户设计。租户之间禁止隐式引用。公共词表以显式导入、锁版本的方式复用。对外部身份、数据源或索引的调用设置超时和范围上限;权限判断无法完成时不返回业务数据。

03 组件划分与调用方向

---
config:
  look: handDrawn
---
flowchart TB
 W["工作台"] --> CP["控制面 API"]
 CP --> R["资产与变更模块"]
 CP --> D["审核与部署模块"]
 R --> DB[("元数据 PostgreSQL")]
 D --> DB
 DB -->|"构建任务与租约"| B["隔离构建进程"]
 B --> O[("内容寻址对象存储")]
 B -->|"结果与报告引用"| DB
 S["来源适配器"] --> F["事实与投影进程"]
 F --> IDX[("索引 / 图查询视图")]
 Q["运行 API"] -->|"读活动指针"| DB
 O --> Q
 IDX --> Q
 APP["应用 / Agent"] --> Q

图 03 逻辑组件与存储。 控制面处理写入,运行面按已激活版本服务读取。两个 API 可以共用一个代码库,但应独立限流、配置数据库角色和部署副本。

组件 拥有的数据或状态 不可跨越的写边界
资产与变更模块 术语身份、修订、分支基线、依赖边 编辑器不能直接改生产模型
构建进程 临时工作图、测试报告、候选包 只回写自己持有租约的任务结果
审核与部署模块 审核事件、部署指针、激活历史 构建成功不能自行获得发布权限
来源与投影进程 观察记录、同步游标、派生索引 构建使用固定样本,生产接数使用独立凭证
运行 API 单请求版本上下文和可重建缓存 不能修改发布物或写入来源系统

表的唯一写方、内部调用及对接条件见第 16 节。目录搜索与业务关系查询有不同的索引。前者帮助作者找术语,后者帮助应用找实例。两者都可从受控数据重建。首版可先用 PostgreSQL 实现目录和浅层关系查询,图查询负载超出目标时再替换运行面的查询适配器。

04 工作台与协同编辑协议

sequenceDiagram
 participant A as 作者甲
 participant W as 工作台
 participant R as 资产服务
 participant B as 作者乙
 A->>W: 打开变更集 C1,代次 7
 W->>R: 保存资产 A,预期 C1.g7
 R-->>W: 变更集代次升至 8
 B->>R: 基于 C1.g7 保存
 R-->>B: 412,返回当前头 C1.g8
 B->>R: 对比基线后提交合并,预期 C1.g8
 R-->>B: 变更集代次升至 9

图 04 同一工作区的并发编辑。 写接口对整个变更集使用强 ETag。术语有自己的不可变修订号。一次成功编辑推进变更集代次,具体命令见第 17 节。两个独立工作区的合并另需三方比较,即比较共同基线、目标头和传入变更。

工作台视图 用户输入 保存结果
模块目录、术语卡、关系图 找到概念,编辑定义、别名、例证、方向和取值范围 通过同一编辑 API 产生草稿修订
映射对照与预览 选择来源字段、目标术语、转换、空值与删除行为 映射草稿、可复现的样本预览引用
检查与差异视图 比较新增、废弃、语义变化及受影响查询 待修事项关联具体对象、条件和失败样本
审核视图 打开候选包,检查测试覆盖、依赖及迁移说明 记录审核人、决定、理由、包摘要

合并规则。 同一属性被两方修改、术语删除后仍有新增引用、基线发布已更新,都需要重新计算差异。独立属性可自动合并,合并后的变更集重新构建。AI 建议保留原文位置和候选状态,作者接受后才形成草稿修订。

05 持久化模型与关键约束

erDiagram
 MODULE ||--o{ ASSET : owns
 ASSET ||--|{ REVISION : versions
 CHANGESET ||--o{ CHANGE_ITEM : edits
 REVISION ||--o{ CHANGE_ITEM : selected
 CHANGESET ||--o{ BUILD : produces
 BUILD ||--o| RELEASE : materializes
 RELEASE ||--|{ MEMBER : pins
 REVISION ||--o{ MEMBER : included
 RELEASE ||--o{ APPROVAL : reviewed
 RELEASE ||--o{ DEPLOYMENT_EVENT : activated

图 05 控制面实体关系。 MEMBER 保存发布的完整成员清单,CHANGE_ITEM 保存相对基线的增删改。当前部署指针从已提交的激活事务读取,历史事件仅追加。

表 主键或唯一键,均带 tenant_id 关键字段
asset / revision asset_id / (asset_id, rev) module_id、kind、稳定 IRI;修订记录携带 blob_hash、parent_rev
changeset / change_item change_id / (change_id, asset_id) base_release、generation、op、selected_rev;删除项留墓碑
dependency (from_asset, from_rev, relation, to_asset) 依赖类型、目标版本范围;构建时固定具体目标修订
build / release / member build_id / release_id / (release_id, asset_id) input_hash、引擎版本、报告引用、manifest_hash、精确修订
approval / deployment approval_id / (module_id, env, channel) 批准人、摘要、决定;活动版本、投影号、generation
deployment_event / deployment_request (module_id, env, channel, generation) / deployment_id 指针历史与异步部署分别存储;构建任务由 build 自身承载

事务不变量。 外键包括 tenant_id;部署指针的外键包含 module_id。对已引用的修订、成员清单和报告撤销 UPDATE/DELETE 权限,修正通过新修订表达。先写并校验不可变对象,再提交引用元数据;数据库提交失败留下的无主对象在保留期后回收。反过来先写引用可能使应用读到不存在的包。

06 语义资产与依赖解析

---
config:
  look: handDrawn
---
flowchart LR
 M["字段映射 M"] -->|"产出"| T["术语 T"]
 H["约束 H"] -->|"检查"| T
 Q["具名查询 Q"] -->|"返回"| T
 A["应用 A"] -->|"订阅"| Q
 X["样本测试 X"] -->|"验证"| H
 Y["契约测试 Y"] -->|"验证"| Q
 T -->|"导入"| V["共享词表 V@3"]

图 06 依赖边与影响分析。 写入时记录箭头方向,构建时从改变的术语反向遍历。拆分 T 至少应重测映射、约束、具名查询及其订阅方。

元模型。 Class 描述类型;Property 声明关系或字面值及其解释;Axiom 保存公理;Shape 表达数据要求。Mapping、QueryContract、ActionContract、TestCase 是平台配套资产。每一类都有独立 kind 和版本化序列化格式。业务实例用独立的实例标识空间,由事实服务管理。

发布解析。 模块清单声明导出术语和依赖。构建器解析所有导入,生成含模块 ID、版本与摘要的锁文件。首版约定跨模块依赖为有向无环图,检测到环时报告完整依赖路径。同模块内的业务关系可以有环。动态查询或外部使用者未登记时,报告标明影响范围未知,由模块负责人决定迁移窗口。

兼容级别。 改显示标签可归为展示变化,但依赖标签的导出需回归。删除公共字段、收紧约束、改变单位或角色含义须列出迁移计划。示例中先增加两个新角色并保留旧查询,待使用方迁移后再移除旧字段。OWL 的本体与版本标识可作为交换格式基础;平台发布仍需固定映射和约束等配套资产。OWL 2 结构规范

07 来源接入、映射与数据投影

---
config:
  look: handDrawn
---
flowchart LR
 S["授权来源"] --> E["快照或增量事件"]
 E --> L[("观察账本")]
 L --> M["身份解析与映射"]
 M --> V["类型与质量检查"]
 V --> D["诊断视图"]
 V --> P["可用事实投影"]
 M --> U["歧义 / 待确认"]
 U -->|"追加确认或撤回"| L

图 07 从来源记录到应用可读视图。 账本先记录来源实际给出的值,检查结果决定可见标记和用途。新观察不合格时,应把旧值从“当前可用”视图失效,保留历史。

接入契约 必要输入与结果
读取快照 返回 snapshot_id、模式版本、读取范围、源端水位与完整性说明
读取增量 事件含来源、分区、记录键、源版本、事件 ID、操作类型和删除标记
应用映射 固定 mapping_rev 和模型版本;对象 ID 由租户、来源命名空间和稳定业务键解析
推进游标 账本追加与该分区的检查点在同一事务提交,重复事件按来源事件键去重
构造投影 以模型发布、映射摘要和来源水位标记投影。读取端可检查新鲜度与缺口

迟到事件按来源版本处理。来源无可比较版本时,重新读取该键的权威快照或进入核对队列。文档抽取带上版本、页段、原文和确认状态。R2RML 可承担关系数据到 RDF 的映射描述,采集游标、删除传播及授权属于适配器契约。W3C R2RML

时间查询。 对有历史要求的事实,保存业务有效区间和平台记录事件的提交时间。运行接口传入 validAt 与 knownAt,分别选择业务时点和当时可见的确认记录。历史查询仍须应用当前访问授权。

08 可复现构建与质量门禁

---
config:
  look: handDrawn
---
flowchart TB
 A["冻结变更集、依赖锁、样本与工具版本"] --> B["解析引用并编译模型"]
 B --> C["按原始数据检查形状与覆盖"]
 B --> D["按声明的推理配置执行能力问题"]
 B --> E["比较上版契约 / 运行订阅方测试"]
 C --> G{"全部必须项通过?"}
 D --> G
 E --> G
 G -->|"是"| P["封存清单、报告与模型文件"]
 G -->|"否"| F["返回定位到修订和样本的诊断"]

图 08 构建依赖图。 三条检查可以并发;任一必需检查超时、未执行或发现违规,都不能把候选包标记为可审核。

阶段 输入、判定与可复核证据
冻结输入 固定 base_release、修订列表、依赖锁、映射、样本摘要、工具镜像摘要、配置与策略版本;禁止构建时拉取 latest
完整性 解析每条引用,检查重复稳定 ID、导入环及未支持的公理;不支持的语义报错,禁止静默跳过
形状与覆盖 每条必检规则记录预期对象集、实际覆盖数和违规对象。样本清册预期 3 个担保关系却命中 0 个时,即便违规数为 0 也阻断
能力与兼容 用固定输入回答领域问题,校对期望集合;将候选与活动版的查询签名、单位、答案差异归档。预期变化须有批准的迁移说明
封包 清单逐项记录产物路径及 SHA-256。规范化顺序与序列化;运行时间、耗时与执行者写入运行记录,不参与可复现摘要

边界。 原始数据的缺字段检查在推理前执行;若产品允许用推导值回答查询,另存推导视图并标注规则集。语义推理中的未知不能直接转成数据违规。SHACL 定义形状验证;覆盖率、阈值和迁移准入是平台策略。W3C SHACL

09 生产发布、切换与回滚

sequenceDiagram
 participant O as 发布负责人
 participant C as 部署服务
 participant P as 投影进程
 participant D as 元数据主库
 O->>C: 请求激活 R12,预期代次 31
 C-->>O: 202 与部署资源地址
 C->>C: 校验包摘要、批准与依赖
 C->>P: 准备 P12 至水位 W
 P-->>C: 索引可读、校验和及影子查询报告
 C->>D: 比较代次并提交 R12/P12、事件、待发通知
 D-->>C: 已提交,代次 32
 O->>C: 轮询部署资源
 C-->>O: 返回部署记录与代次

图 09 以数据库提交为上线时刻。 影子查询只比较结果,不影响用户流量。数据库比较并交换(CAS)针对同一租户、模块、环境与发布通道,拒绝覆盖并发发布。

部署单元。 指针由 release_id、projection_id、generation 组成。投影有自己的数据更新水位;每个请求还需固定读快照。生产可设 stable、canary 两个通道,应用按受控名单选通道。每个通道独立执行同一协议;候选包不因进入灰度而自动成为正式版。

窗口 对用户可见的版本 操作员应做什么
新投影未就绪、影子检查失败 旧指针 保存差异,修正后再建;不得提前修改活动指针
提交成功、通知尚未到达 新请求从权威指针取新代次;已有请求保持原快照 后台重发通知。通知只做预热或失效提示
激活请求超时 提交状态未知 携原幂等键重发同体请求取回部署 ID;不得盲目再切换一次
需要回滚 回滚请求在新代次指向已验证旧组合 确认旧投影水位、保留期与当前权限,写入独立回滚事件

退役条件。 在回滚窗口内为旧投影持续追平增量;达不到新鲜度目标时先重放再切回。保持旧快照至在途查询结束。权限撤回和来源删除按现行策略执行,回退模型不得恢复已撤销的访问。

10 应用与 Agent 的运行契约

sequenceDiagram
 participant A as 应用或 Agent
 participant R as 运行 API
 participant I as 授权服务
 participant V as 版本与数据视图
 A->>R: 调用具名查询,传入类型化参数
 R->>I: 校验主体、租户、用途与范围
 I-->>R: 允许范围或拒绝
 R->>V: 固定环境代次与投影读快照
 R->>I: 按该版本契约细化字段和对象范围
 R->>V: 在授权范围执行计划,读取证据
 R-->>A: 值、证据引用、版本、水位、结果状态

图 10 一次请求只读一个版本组合。 模型告诉 Agent“对象是什么、关系指向谁”;查询契约规定“谁能查、输入是什么、返回什么”。模型发现和工具调用均经授权。客户端不能自行拼接无范围限制的关系查询。

返回状态 产生条件 客户端行为
answered 有权读取,匹配事实并符合声明的时效 展示值、时间与证据引用;证据打开时再次鉴权
empty 查询范围已声明完整,结果集为空 可报告“在此范围未找到”;不能扩大为全局否定
unknown / stale 来源范围不完整、身份歧义或水位落后 返回缺口或最后可信时间,禁止据此自动作否定判断
forbidden / unavailable 无权调用;或无法固定版本、检查权限、访问必需视图 返回结构化错误,不泄露受限对象是否存在

快照与分页。 首次请求固定 generation、可重复读取的 snapshot_id 和授权范围。游标绑定租户、主体、查询、参数摘要、快照及过期时间;每页重验当前授权。快照过期返回 410,要求重新查询。缓存键包含授权范围和策略版本;权限撤销后不得继续命中旧缓存。

动作扩展。 动作契约仅产出类型化提议和验证证据。若接入执行器,由业务系统在实际提交时核对权限、业务状态和幂等键;平台记录关联操作号。图 10 的“查到”本身没有执行权限。

11 租户、权限与证据信任边界

---
config:
  look: handDrawn
---
flowchart TB
 U["使用者 / 应用"] --> G["入口:验证身份,派生租户"]
 G --> C["控制面:角色与环境授权"]
 G --> R["运行面:查询与事实范围"]
 C --> M[("按租户分区的模型与发布")]
 R --> F[("带来源范围的事实与证据")]
 S["接入进程:独立服务身份"] --> F
 C --> L["审计:受保护的追加记录"]
 R --> L

图 11 身份贯穿所有数据路径。 服务不能相信客户端传入的租户号。模型目录、事实查询、对象下载和审计检索分别执行权限检查。

主体 允许 强制约束
作者 / 数据工程师 在所属模块编辑、读取授权样本 预览与报告沿用来源权限;生产凭证只由连接器身份使用
评审 / 发布负责人 对候选包作决定、激活指定环境 生产实行作者与批准人分离;批准绑定包摘要,内容改变须再审
应用 / Agent 发现导出术语、执行已授权契约 同时限制字段、对象、来源和用途;汇总与错误文本也须符合访问范围
平台运维 恢复、观测、管理服务身份 默认不读业务正文;应急访问有理由、期限和独立复核

存储隔离。 元数据全链路使用含租户的键与行级策略。对象存储按租户隔离前缀和密钥授权;下载通过鉴权服务颁发短时访问。证据来源受限时,派生事实默认继承限制;公开聚合需要单独登记和审核。

审计与清除。 记录主体、操作、租户、对象标识、授权决定、策略版本、请求号和时间;避免记录原文或完整查询参数。源端撤回时失效活动投影、缓存、下载令牌及历史入口;必要时清除可识别载荷,审计保留不含原文的处置凭据。跨租户目录、对象、分页和证据链接需分别做负向测试。

12 生产拓扑、容量与扩展条件

---
config:
  look: handDrawn
---
flowchart TB
 G["入口 / 负载均衡"] --> C["控制 API × 2,跨可用区"]
 G --> R["运行 API × 2,跨可用区"]
 C --> D[("元数据主库 + 跨区备用")]
 R --> D
 C --> J["任务表 / 调度器"]
 J --> B["隔离的构建与投影进程池"]
 B --> O[("带版本与保留策略的对象存储")]
 B --> P[("活动 / 候选投影视图")]
 R --> P
 D --> K["独立恢复域:基础备份与事务日志"]
 O --> K

图 12 最小生产部署。 方框是可独立扩缩的进程组,圆柱是持久数据。投影可重建;数据库、观察账本、原始快照与不可变包进入备份范围。若观察账本独立落库,也要有对应的日志归档。

试点负载假设 暂定目标 验证方法
10 个团队,合计 10 万修订;每次变更 100 项、固定样本 1 万条 普通构建 P95 ≤ 5 分钟;排队另计 冷启动与增量各测 30 次;记录引擎、规则规模与图密度
100 万条有效事实;峰值 100 查询/秒 具名浅查询 P95 ≤ 300 ms,错误率 < 0.1% 读 30 分钟,含冷缓存、跨区读与发布期间流量;另测慢查询隔离
日增 100 万观察,每条编码后假设 0.8 KB 30 天约 24 GB 原始载荷 另计索引、副本、历史投影与备份;按线上样本实测放大系数

容量决策。 若平均服务时间为 120 ms,100 次/秒约对应 12 个平均在途查询;不能拿 P95 替代均值,也不能据此直接指定核数。以实际计划、连接池等待与 CPU 曲线定副本。优先限制跳数、扇出和返回量,再比较关系存储与专用图索引。

隔离与发布。 单租户构建并发和内存分别设上限;运行 API 使用独立连接池。数据库变更先加兼容字段、双读验证,再退役旧字段。应用回滚窗口内保持旧读路径可用。

13 故障处理、可观测性与恢复

stateDiagram-v2
 [*] --> Queued
 Queued --> Leased: 领取任务与代次
 Leased --> Succeeded: 本代次提交成功
 Leased --> Queued: 可重试错误或租约到期
 Leased --> Blocked: 超限或确定性错误
 Blocked --> Queued: 经修复后重放
 Succeeded --> [*]

图 13 异步工作进程的状态机。 领取任务时递增租约代次;写入任务终态须比较该代次。即便旧进程恢复,也无法覆盖新的成功结果。数据检查未通过属于有效报告,不应当成网络错误无限重试。

观测信号 告警或判断 恢复与可接受结果
队列最老任务、租约超时、重试数 最老普通任务等待超过 5 分钟触发试点告警 检查租户积压;按键重试;确定性失败归还作者
按来源分区的水位、事件缺口 连续 2 个采集周期不前进且源端有新数据 标记视图过期,按缺口补拉;不伪造已追平水位
投影摘要、发布指针、通知积压 指针引用不存在或摘要不符立即告警 停止该范围查询;核对元数据,重建或激活经验证的保留版本
数据库或区域不可用 试点目标:控制数据 RPO ≤ 5 分钟,关键读恢复 RTO ≤ 60 分钟 在备用域恢复同一时点数据库和账本,按清单验包,追平投影后再开放流量

恢复顺序。 暂停新写入与调度 → 恢复控制库和事实账本 → 校验活动指针、包与快照完整性 → 比较各分区水位 → 重放缺口、抽查具名查询 → 重启读流量和写入。任一来源欠账时仅开放满足新鲜度契约的查询。

演练证据。 每次演练留存故障时刻、最后可恢复提交、恢复首个成功请求、丢失窗口、抽检结果和操作者。请求号串起 API、任务、投影与审计。备份存在不能证明达到恢复目标,须以跨域恢复计时验收。

14 接口清单、错误与幂等

---
config:
  look: handDrawn
---
flowchart LR
 A["创建变更集"] --> B["更新草稿头"]
 B --> C["提交构建"]
 C --> D["获取候选发布"]
 D --> E["提交批准与激活"]
 E --> F["调用具名查询"]

图 14 首版 API 调用链。 所有路径以 /v1 为前缀。写入请求绑定已验证主体、租户与权限范围。环境部署指针和草稿头采用不同的代次空间。

方法与路径 输入、响应与冲突
POST /changesets module、baseRelease;201 返回 changeId、草稿 ETag
PATCH /changesets/{id} If-Match 和单项编辑命令,返回变更集新 ETag。过期返回 412
POST /builds;GET /builds/{id} changeId、changeGeneration、sampleHash;202 返回 buildId;轮询得到报告和候选 releaseId 或阻断原因
POST /releases/{id}/approvals manifestHash、decision、reason;201 返回不可变批准记录;审核失效不得部署
POST /deployments;GET /deployments/{id} 目标环境、通道、候选与 expectedGeneration;202;终态含新代次或并发冲突
POST /queries/{name}:run 类型化参数、模块与环境;200 返回结果状态、水位与证据。资源不可用返回 503

激活请求与终态示例。 POST 带 Idempotency-Key;查询部署状态时使用返回的部署 ID。下例分两行示意请求体和成功终态。

{"module":"credit","env":"prod","channel":"stable","releaseId":"R12","expectedGeneration":31}
{"id":"D82","status":"active","generation":32,"releaseId":"R12","projectionId":"P12"}

错误协议。 错误包包含 code、requestId、retryable 及脱敏 details。幂等键按租户、主体和操作隔离;同键同体返回原记录,同键异体返回 409。同步校验输入不合法返回 422;异步构建失败从任务终态读取。权限不足返回 403;对不应暴露存在性的资源统一 404。异步部署的比较失败写入终态 conflict,调用者刷新指针后发起新请求。

15 技术取舍、交付顺序与验收

---
config:
  look: handDrawn
---
flowchart TB
 A["M1:能编辑和追溯"] --> B["M2:能构建、拒绝坏包"]
 B --> C["M3:能接数、上线、回滚"]
 C --> D["M4:第二领域独立接入"]
 C --> E["M4:故障恢复与隔离演练"]
 D --> F["平台验收"]
 E --> F

图 15 交付依赖。 先跑通一个最小发布,再用第二个领域检验可复用性。进入下一阶段所需的是可复核的产物与测试记录。

里程碑 / 责任方 交付物 退出测试
M1 · 建模与平台组 术语、关系、约束编辑器;修订库、工作区与审计 两人基于同一修订编辑,旧写入被拒;任一发布成员能追溯作者和定义
M2 · 构建组、领域评审人 锁文件、编译器、样本、覆盖报告、兼容差异 刻意删除必填映射、清空约束目标、移除公共字段;三类问题都被定位
M3 · 数据与运行组 一个可重放连接器、一条具名查询、审批与环境切换 切换中持续读;每条结果仅引用一个版本组合;中断通知、重复激活不会切两次
M4 · 第二领域团队、运维 设备维修模块、接入记录、负载与恢复演练报告 独立建立“设备—工单”关系,无核心代码改动;跨租户访问被拒;恢复目标经计时验证

关键架构决定。 ① 首版用模块化控制服务加独立工作进程,避免一次编辑跨服务事务;拆分依据是隔离与吞吐证据。② 定义、事实和索引分开存放,失去索引必须可重建。③ 首版采用具名查询和有限推理配置,复杂路径或新推理规则须以能力问题和负载测试支撑。④ 对外语义通过开放格式交换,平台专有审批、快照、授权用独立契约表达。

开工前待定。 平台负责人确定租户与部署边界;领域负责人签署首批能力问题;数据负责人确认快照、删除与水位语义;运维确定回滚保留期、RPO/RTO 和演练预算。未取得真实规模与来源样本前,第 12、13 节指标均为设计目标。

16 模块写权限与事务归属

评审发现 · P0。 图 03 中“都能连元数据库”不足以分配开发责任。例如投影进程写好新索引后就改活动版本,会绕过审核与激活事务。首版在同一 PostgreSQL 库中以模块接口和数据库角色控制写入。跨模块的读操作通过版本化的查询视图或下表的内部接口提供。

---
config:
  look: handDrawn
---
flowchart LR
 B["构建模块"] -->|"freeze 读取成员"| A["建模模块"]
 B -->|"候选包与报告"| D["部署模块"]
 F["事实接入"] -->|"分区水位"| P["投影模块"]
 P -->|"就绪凭据"| D
 R["运行 API"] -->|"取活动指针"| D
 R -->|"打开固定快照"| P

图 16 模块之间传递的最小信息。 箭头标注数据依赖。freeze 的调用方向从构建指向建模。构建和投影分别交付候选包与就绪凭据,只有部署模块能改变活动指针。

唯一写方 拥有的表 给调用者的接口与失败结果
建模 module、asset、revision、dependency、changeset、change_item、edit_event freeze(changeId, generation) 在调用方事务内锁定变更集,返回基线、成员、依赖与贡献者。代次变化返回 CHANGESET_MOVED
构建 build、release、member submit 在 freeze 所在事务写入构建。工作进程持租约完成封包,返回 buildId、报告与候选发布。不可用输入返回报告或 FAILED
接入 / 投影 接入独占 observation、checkpoint。投影独占 projection、read_snapshot 和派生存储 prepare(release, watermarks) 可重入。成功给出同一发布的投影、快照、映射摘要及水位。期间查询仍使用旧指针
审核与部署 approval、deployment_request、deployment、deployment_event、outbox requestActivation 登记请求。commitActivation 持锁复核后切换。并发失败写入请求终态
运行 只读投影与活动指针 resolveReadContext 在主库以一个一致性读快照选取版本。数据适配器按返回的视图引用读,过期报 SNAPSHOT_EXPIRED

幂等中间件代各命令在业务事务中写 idempotency。通知进程仅获更新 outbox 的 sent_at、attempts 权限。按表授权给非所有者角色,在每个事务设置经认证的租户上下文 app.tenant_id,租户标识从服务身份或用户会话派生。迁移角色与应用角色分开。每个跨模块调用传递租户、主体、请求号和固定资源 ID。

17 建模表、修订与草稿保存

---
config:
  look: handDrawn
---
flowchart LR
 A["C1 基线成员"] --> V["草稿有效成员"]
 B["change_item 覆盖或墓碑"] --> V
 V --> P["保存一个资产"]
 P --> R["追加 revision 与依赖"]
 P --> E["更新覆盖项、代次与编辑记录"]

图 17 一个工作区对应一个变更集。 编辑器先 GET /changesets/C1 获取变更集 ETag,再按资产 ID 读取有效定义。新增、编辑、删除都向变更集资源发 PATCH。首版接受同一工作区不同资产之间的写冲突,换取明确的整组构建基线。

物理表 关键字段与约束 对应访问路径
asset、revision 资产主键含租户、模块、资产 ID。同租户 IRI 唯一。rev 为数据库分配的 bigint,parent_rev 复合外键指向同一资产 按完整键查修订。两个工作区各自产生子修订,编号允许跳号
changeset、change_item generation 从 0 起。每个变更集每个资产一行。put 必须引用本资产真实修订,delete 的 selected_rev 为空 读时用覆盖行替换基线成员,墓碑移除成员。首版 base_release 允许为空
dependency、edit_event 依赖起点绑定修订,终点绑定租户内资产。编辑记录按变更集和新代次唯一,保存主体及操作 按目标模块、资产反查影响范围。删除操作也能还原贡献者

一次保存。 客户端发送 If-Match 与 Idempotency-Key。服务端鉴权并处理重放后锁 changeset,检查 ETag。put 提交完整定义,按 kind 选择定义模式。已有资产的 kind、IRI 固定,新身份需同时提供两者。对象存储先按内容摘要幂等写入,再在一个数据库事务追加修订、替换覆盖项、记录依赖与编辑事件、代次加一及保存幂等响应。delete 写墓碑,重复删除已缺席资产返回 422。首次创建模块时建空基线,平台管理员同时初始化环境通道。

PATCH /v1/changesets/C1
If-Match: "C1.g7"
Idempotency-Key: edit-0008
Content-Type: application/json

{"op":"put","assetId":"A1","kind":"Class","iri":"urn:example:Party","definition":{"label":"参与方"}}

成功返回 200、ETag "C1.g8" 及 changeId、module、baseRelease、generation。缺少前置条件返回 428。代次落后返回 412 和 currentGeneration,编辑器重新读头与资产,比较基线后使用新键提交。

18 冻结构建输入与投影读快照

---
config:
  look: handDrawn
---
flowchart TB
 C["变更集 + 固定样本"] --> B["build.input_manifest"]
 B --> R["release + member"]
 L["observation + checkpoint"] --> P["projection"]
 R --> P
 P --> S["read_snapshot:不可变视图与分区水位"]

图 18 构建快照与运行快照各有用途。 第一个快照保证作者继续改稿时,已提交的构建仍可复现。第二个快照使分页查询在接入新事实后仍能读到同一批数据。

持久化对象 写入时必须固定什么 失败 / 重试处理
build change_generation、input_manifest、input_hash。清单含完整本模块成员、导入发布摘要、样本、工具与策略摘要,以及 edit_event 推导的贡献者 POST 在事务中比较请求代次,写入 queued 后返回。工作进程只读取清单中的对象
release、member 每次成功构建最多一个 release。member 以发布和资产为键,同模块复合外键指向精确修订。跨模块成员经清单中的导入锁定位 事务内校验当前租约、置 passed、写 release 与所有 member。报告未通过置 blocked 并写 report_hash
observation、checkpoint 去重键为租户、来源、分区、事件 ID。检查点保存适配器定义的游标 锁分区检查点,校验批次起点,再追加观察并推进游标。重复 ID 内容变化进入核对流程
projection、read_snapshot projection 的键同时包含发布与投影。read_snapshot 保存分区水位、不可变视图位置、提交和保留时间 完成视图写入并核验后再提交快照行。运行读取已提交快照,清理需避开有效游标与回滚窗口

工作进程协议。 同一租户下使用行锁认领排队或租约已过期的记录,递增 lease_epoch。完成时以状态、epoch 和数据库当前时间仍早于 lease_until 为条件更新。更新影响零行则整个终态事务回滚。构建状态由 build 自身承载,部署状态由 deployment_request 承载,各自的 ID 直接用于轮询。

首版快照实现。 投影可用按 snapshot_id 分区的不可变关系表或不可变文件。运行面从主库一次选取活动指针和该投影最新已提交快照,排序键为 committed_at、snapshot_id。快照固定时还要检查新鲜度与来源覆盖。跨页使用逻辑快照 ID,无需为客户端跨请求保留数据库事务。

19 部署持久化与并发裁决

sequenceDiagram
 participant A as 请求 D82
 participant B as 请求 D83
 participant D as 部署事务
 A->>D: 预期 31,候选 R12
 B->>D: 预期 31,候选 R13
 D-->>A: 写指针 32、事件、通知、active
 D-->>B: 当前已是 32,仅写 conflict

图 19 两次不同的部署请求竞争同一通道。 两个 POST 都可以返回 202。谁取得通道行锁并满足校验条件,谁生效。另一方轮询得到 200 和业务终态 conflict。

表 身份与约束 实现要点
approval 发布、摘要、环境、审核人、决定。摘要复合外键指向 release approve / revoke 都追加。按环境取最大 approval_id 的决定。审核与激活均先锁同一 release 行
deployment 主键为租户、模块、环境、通道。代次 0 表示空通道。活动组合复合外键必须命中 projection 的同一发布行 只在环境初始化创建空行。首发 expectedGeneration 为 0,回滚同样推进代次
deployment_request 保存 expected_generation、租约、状态和已应用的代次。部署 ID 在租户内唯一 GET 读此表,保留每个请求自己的结果。后续发布不会覆盖旧请求终态
deployment_event、outbox 历史按通道与新代次唯一,一个部署 ID 最多一个激活事件及一条待发通知 投递失败保留待发记录,订阅者按租户、部署 ID 去重。后台可重发

激活事务。 工作进程在事务外准备投影。事务内按固定顺序锁请求、候选 release、通道和投影。检查租约与 expectedGeneration,重新验证批准、贡献者分离、环境、摘要、投影就绪及新鲜度。投影退役操作也要锁投影并检查活动引用。通过后以当前代次为条件更新指针,保存旧值和新值,追加事件、outbox,并将请求置 active,一次提交。不同代次只提交 conflict。批准撤回或就绪校验失败只提交 failed 和错误码。

首次发布与回滚。 空通道读指针返回 generation=0 及两个 null。选择回滚版本时提交旧 releaseId、当前代次和新的幂等键。部署服务选该发布满足水位的就绪投影,多个候选按快照提交时间、快照 ID、投影 ID 依次取最新。若无可用投影,留在 preparing 并重建,到作业期限写 failed。

20 HTTP 契约与客户端恢复路径

---
config:
  look: handDrawn
---
flowchart LR
 A["命令已鉴权"] --> D{"同作用域的幂等键?"}
 D -->|"同键同指纹"| R["返回原始受理结果"]
 D -->|"同键不同指纹"| X["409"]
 D -->|"首次出现"| C["同事务写业务记录与响应"]
 C --> G["GET 轮询资源"]

图 20 命令去重与异步受理。 幂等行唯一键含租户、主体、操作、键。操作包含方法和带实际资源 ID 的路径。指纹覆盖规范化请求体和 If-Match。响应快照包含 HTTP 状态、响应体与 Location,ETag 从响应中的资源 ID 和代次重建。

操作 客户端发送 正常结果与分支
建变更集 / 查草稿 POST /changesets 传 module、baseRelease。GET /changesets/{id} 取头,GET 其 /assets/{asset} 取有效定义 201 带 Location、ETag。资产缺席返回 404
建构建 / 查结果 POST /builds 传 changeId、changeGeneration、sampleHash 202 返回 buildId、state=queued 和 Location。GET 可能为 running、passed、blocked、failed。passed 返回 releaseId、manifestHash。GET /builds/{id}/report 读取脱敏报告,未生成返回 409
审核 / 部署 POST /releases/{id}/approvals 传 env、manifestHash、decision、reason。GET /channels/active 带 module、env、channel 取当前代次 批准返回 201。POST /deployments 受理返回 202 和部署 Location。GET 读取 queued、preparing、active、conflict、failed
查契约 / 执行查询 GET /queries/{name} 带同一组范围参数,取 inputSchema、rowSchema。POST 其 :run,发 module、env、channel、params 可携 expectedRelease 固定发现时的契约,版本已切换返回 409。answered/empty/unknown/stale 都返回 200。GET /evidence/{id} 按现行权限读取片段
续页 再次 POST 同一 :run,仅发送 cursor。默认页长 50,上限 200 检查签名、主体、权限、查询名与快照期限。权限变化作废旧游标,返回 403。过期返回 410,客户端重新发起第一页

重试约定。 每个写命令要求 Idempotency-Key,保留窗口首版 24 小时。数据库使用唯一插入占位与业务写入同事务提交,竞争者等待第一笔事务完成再读取。重放前重新鉴权,同指纹优先返回首次响应,包括原 ETag。已成功保存但回包丢失的请求因此可恢复。未受理的校验失败回滚占位。超窗后先按已知资源 ID 对账,无法判断时提示人工核对。错误体固定含 code、requestId、retryable 和 details。参数错误返回 422。拒绝读取他人资源统一 404。

21 跨模块联调与验收样例

---
config:
  look: handDrawn
---
flowchart LR
 A["编辑 C1"] --> B["冻结 B8"]
 B --> R["审核 R12"]
 R --> D["激活 D82"]
 D --> Q["读取第 1 页"]
 Q --> P["切版后取第 2 页"]

图 21 验收数据贯穿整个请求链。 用同一租户准备两个发布、一条具名查询和至少两条有权查看的事实。客户端应能从结果查回构建、输入清单、术语修订及来源水位。

注入的情况 接口可见结果 数据库断言
两次不同编辑均携 C1.g7;首个成功后重发同键同体 首个 200,另一个 412,重放仍得到原 200 与 g8 generation 只增一次,新增一个 edit_event
冻结 B8 后继续编辑;故意让旧工作进程晚到 B8 报告始终对应冻结清单,旧租约提交无效 B8 只关联一个 release,成员及 input_hash 与 g8 一致
为 R12 指定 R13 的投影,或指定其他租户的成员 部署终态 failed 或写入被拒 复合外键拒绝配错,原指针、历史与 outbox 保持一致
相同预期代次并发上线;提交后断开响应 重放同键返回原 202,轮询一个 active、一个 conflict 一个新代次、一条成功事件和一条待发记录
切版后续页;分别撤权和使快照到期 正常续页仍读旧版,撤权 403,过期 410 页内所有行来自同一快照,当前授权覆盖全部证据
样本集为空、来源不完整或来源过期 必检规则零命中阻断构建。查询缺口为 unknown,过期为 stale blocked 构建有报告。仅覆盖完整且无匹配才返回 empty

具名查询示例。 调用 /v1/queries/partyById:run。参数模式要求 partyId 为非空字符串,结果行模式声明 label 为字符串。服务端随发布固定这两个 JSON Schema,客户端可通过契约发现接口读取。

{"module":"credit","env":"prod","channel":"stable","params":{"partyId":"P9"},"pageSize":1}
{"status":"answered","generation":32,"releaseId":"R12","projectionId":"P12","snapshotId":"S51","watermarks":{"crm/0":"41"},"rows":[{"values":{"label":"甲企业"},"evidenceRefs":["E41"]}],"nextCursor":null}

建表基线与完整 HTTP 模式分别见 文末的 core.sql 和 文末的 openapi.yaml。在空库先运行 core.sql,再以测试管理员执行 文末的 verify.sql 检查约束与租户隔离。验证脚本在事务中回滚测试数据。本节列出研发集成测试条件,容量及故障恢复按第 12–13 节在候选部署环境实测。

研发附件

以下三个代码块可分别保存为同名文件。

core.sql

-- v1.1 | PostgreSQL | run once against a new database.
-- Application roles are provisioned by the operator; use non-owner, non-BYPASSRLS roles.
BEGIN;
CREATE SCHEMA ontology;
SET LOCAL search_path = ontology, pg_catalog;
CREATE DOMAIN digest256 AS text CHECK (VALUE ~ '^[0-9a-f]{64}$');
CREATE TABLE module (
  tenant_id text NOT NULL, module_id text NOT NULL,
  PRIMARY KEY (tenant_id, module_id)
);
CREATE TABLE asset (
  tenant_id text NOT NULL, module_id text NOT NULL, asset_id text NOT NULL,
  kind text NOT NULL CHECK(kind IN ('Class','Property','Axiom','Shape','Mapping','QueryContract','ActionContract','TestCase')),
  iri text NOT NULL,
  PRIMARY KEY (tenant_id,module_id,asset_id), UNIQUE (tenant_id,iri),
  FOREIGN KEY (tenant_id,module_id) REFERENCES module
);
CREATE TABLE revision (
  tenant_id text NOT NULL, module_id text NOT NULL, asset_id text NOT NULL,
  rev bigint GENERATED ALWAYS AS IDENTITY, parent_rev bigint,
  blob_hash digest256 NOT NULL, author_id text NOT NULL, created_at timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (tenant_id,module_id,asset_id,rev),
  FOREIGN KEY (tenant_id,module_id,asset_id) REFERENCES asset,
  FOREIGN KEY (tenant_id,module_id,asset_id,parent_rev) REFERENCES revision
);
CREATE TABLE dependency (
  tenant_id text NOT NULL, module_id text NOT NULL, asset_id text NOT NULL, rev bigint NOT NULL,
  relation text NOT NULL, target_module text NOT NULL, target_asset text NOT NULL, target_range text NOT NULL,
  PRIMARY KEY (tenant_id,module_id,asset_id,rev,relation,target_module,target_asset),
  FOREIGN KEY (tenant_id,module_id,asset_id,rev) REFERENCES revision,
  FOREIGN KEY (tenant_id,target_module,target_asset) REFERENCES asset
);
CREATE INDEX reverse_dependencies ON dependency(tenant_id,target_module,target_asset);
CREATE TABLE changeset (
  tenant_id text NOT NULL, module_id text NOT NULL, change_id text NOT NULL,
  base_release text, generation bigint NOT NULL DEFAULT 0 CHECK(generation >= 0),
  PRIMARY KEY (tenant_id,module_id,change_id), UNIQUE(tenant_id,change_id),
  FOREIGN KEY (tenant_id,module_id) REFERENCES module
);
CREATE TABLE change_item (
  tenant_id text NOT NULL, module_id text NOT NULL, change_id text NOT NULL,
  asset_id text NOT NULL, op text NOT NULL CHECK(op IN ('put','delete')), selected_rev bigint,
  PRIMARY KEY (tenant_id,module_id,change_id,asset_id),
  CHECK ((op='put')=(selected_rev IS NOT NULL)),
  FOREIGN KEY (tenant_id,module_id,change_id) REFERENCES changeset,
  FOREIGN KEY (tenant_id,module_id,asset_id) REFERENCES asset,
  FOREIGN KEY (tenant_id,module_id,asset_id,selected_rev) REFERENCES revision
);
CREATE TABLE edit_event (
  tenant_id text NOT NULL, module_id text NOT NULL, change_id text NOT NULL, generation bigint NOT NULL CHECK(generation>0),
  actor_id text NOT NULL, asset_id text NOT NULL, op text NOT NULL CHECK(op IN ('put','delete')),
  selected_rev bigint, created_at timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY(tenant_id,module_id,change_id,generation),
  FOREIGN KEY(tenant_id,module_id,change_id) REFERENCES changeset,
  FOREIGN KEY(tenant_id,module_id,asset_id) REFERENCES asset,
  FOREIGN KEY(tenant_id,module_id,asset_id,selected_rev) REFERENCES revision,
  CHECK((op='put')=(selected_rev IS NOT NULL))
);
CREATE TABLE build (
  tenant_id text NOT NULL, module_id text NOT NULL, build_id text NOT NULL, change_id text NOT NULL,
  change_generation bigint NOT NULL CHECK(change_generation >= 0),
  input_hash digest256 NOT NULL, input_manifest jsonb NOT NULL, report_hash digest256,
  state text NOT NULL CHECK(state IN ('queued','running','passed','blocked','failed')),
  lease_epoch bigint NOT NULL DEFAULT 0, lease_until timestamptz,
  PRIMARY KEY (tenant_id,module_id,build_id), UNIQUE(tenant_id,build_id),
  FOREIGN KEY (tenant_id,module_id,change_id) REFERENCES changeset,
  CHECK ((state='running')=(lease_until IS NOT NULL)),
  CHECK (state NOT IN ('passed','blocked') OR report_hash IS NOT NULL)
);
CREATE INDEX build_queue ON build (state, lease_until) WHERE state IN ('queued','running');
CREATE TABLE release (
  tenant_id text NOT NULL, module_id text NOT NULL, release_id text NOT NULL,
  build_id text NOT NULL, manifest_hash digest256 NOT NULL,
  PRIMARY KEY(tenant_id,module_id,release_id), UNIQUE(tenant_id,release_id),
  UNIQUE(tenant_id,module_id,build_id), UNIQUE(tenant_id,module_id,release_id,manifest_hash),
  FOREIGN KEY(tenant_id,module_id,build_id) REFERENCES build
);
ALTER TABLE changeset ADD FOREIGN KEY(tenant_id,module_id,base_release) REFERENCES release;
CREATE TABLE member (
  tenant_id text NOT NULL, module_id text NOT NULL, release_id text NOT NULL, asset_id text NOT NULL, rev bigint NOT NULL,
  PRIMARY KEY(tenant_id,module_id,release_id,asset_id),
  FOREIGN KEY(tenant_id,module_id,release_id) REFERENCES release,
  FOREIGN KEY(tenant_id,module_id,asset_id,rev) REFERENCES revision
);
CREATE TABLE approval (
  tenant_id text NOT NULL, module_id text NOT NULL, approval_id bigint GENERATED ALWAYS AS IDENTITY,
  release_id text NOT NULL, manifest_hash digest256 NOT NULL, env text NOT NULL, reviewer text NOT NULL,
  decision text NOT NULL CHECK(decision IN ('approve','revoke')), reason text NOT NULL, created_at timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY(tenant_id,approval_id),
  FOREIGN KEY(tenant_id,module_id,release_id,manifest_hash) REFERENCES release(tenant_id,module_id,release_id,manifest_hash)
);
CREATE INDEX approval_latest ON approval(tenant_id,module_id,release_id,env,approval_id DESC);
CREATE TABLE observation (
  tenant_id text NOT NULL, source_id text NOT NULL, partition_id text NOT NULL, event_id text NOT NULL,
  record_key text NOT NULL, source_version text NOT NULL, op text NOT NULL CHECK(op IN ('put','delete')),
  payload_ref text, valid_from timestamptz NOT NULL, valid_to timestamptz, recorded_at timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY(tenant_id,source_id,partition_id,event_id),
  CHECK(valid_to IS NULL OR valid_to>valid_from), CHECK(op='delete' OR payload_ref IS NOT NULL)
);
CREATE TABLE checkpoint (
  tenant_id text NOT NULL, source_id text NOT NULL, partition_id text NOT NULL, cursor_value text NOT NULL,
  PRIMARY KEY(tenant_id,source_id,partition_id)
);
CREATE TABLE projection (
  tenant_id text NOT NULL, module_id text NOT NULL, release_id text NOT NULL, projection_id text NOT NULL,
  state text NOT NULL CHECK(state IN ('preparing','ready','retired')), mapping_hash digest256 NOT NULL,
  PRIMARY KEY(tenant_id,module_id,release_id,projection_id),
  FOREIGN KEY(tenant_id,module_id,release_id) REFERENCES release
);
CREATE TABLE read_snapshot (
  tenant_id text NOT NULL, module_id text NOT NULL, release_id text NOT NULL, projection_id text NOT NULL,
  snapshot_id text NOT NULL, watermarks jsonb NOT NULL, immutable_view_ref text NOT NULL,
  committed_at timestamptz NOT NULL DEFAULT now(), retain_until timestamptz NOT NULL,
  PRIMARY KEY(tenant_id,module_id,release_id,projection_id,snapshot_id),
  FOREIGN KEY(tenant_id,module_id,release_id,projection_id) REFERENCES projection,
  CHECK(retain_until > committed_at)
);
CREATE INDEX snapshots_by_time ON read_snapshot(tenant_id,module_id,release_id,projection_id,committed_at DESC,snapshot_id DESC);
CREATE TABLE deployment (
  tenant_id text NOT NULL, module_id text NOT NULL, env text NOT NULL, channel text NOT NULL,
  generation bigint NOT NULL DEFAULT 0, release_id text, projection_id text,
  PRIMARY KEY(tenant_id,module_id,env,channel), FOREIGN KEY(tenant_id,module_id) REFERENCES module,
  FOREIGN KEY(tenant_id,module_id,release_id,projection_id) REFERENCES projection,
  CHECK ((generation=0 AND release_id IS NULL AND projection_id IS NULL)
      OR (generation>0 AND release_id IS NOT NULL AND projection_id IS NOT NULL))
);
CREATE TABLE deployment_request (
  tenant_id text NOT NULL, module_id text NOT NULL, deployment_id text NOT NULL, env text NOT NULL, channel text NOT NULL,
  release_id text NOT NULL, expected_generation bigint NOT NULL CHECK(expected_generation >= 0),
  state text NOT NULL CHECK(state IN ('queued','preparing','active','conflict','failed')),
  applied_generation bigint, projection_id text, error_code text,
  lease_epoch bigint NOT NULL DEFAULT 0, lease_until timestamptz,
  PRIMARY KEY(tenant_id,deployment_id), UNIQUE(tenant_id,module_id,env,channel,deployment_id),
  FOREIGN KEY(tenant_id,module_id,env,channel) REFERENCES deployment,
  FOREIGN KEY(tenant_id,module_id,release_id) REFERENCES release,
  FOREIGN KEY(tenant_id,module_id,release_id,projection_id) REFERENCES projection,
  CHECK ((state='active')=(applied_generation IS NOT NULL)),
  CHECK(state<>'active' OR (applied_generation=expected_generation+1 AND projection_id IS NOT NULL)),
  CHECK((state='preparing')=(lease_until IS NOT NULL))
);
CREATE TABLE deployment_event (
  tenant_id text NOT NULL, module_id text NOT NULL, env text NOT NULL, channel text NOT NULL,
  generation bigint NOT NULL CHECK(generation>0), deployment_id text NOT NULL, before_ptr jsonb NOT NULL, after_ptr jsonb NOT NULL,
  PRIMARY KEY(tenant_id,module_id,env,channel,generation), UNIQUE(tenant_id,deployment_id),
  FOREIGN KEY(tenant_id,module_id,env,channel,deployment_id) REFERENCES deployment_request(tenant_id,module_id,env,channel,deployment_id)
);
CREATE TABLE outbox (
  tenant_id text NOT NULL, deployment_id text NOT NULL, event_type text NOT NULL, payload jsonb NOT NULL,
  created_at timestamptz NOT NULL DEFAULT now(), sent_at timestamptz, attempts int NOT NULL DEFAULT 0,
  PRIMARY KEY(tenant_id,deployment_id), FOREIGN KEY(tenant_id,deployment_id) REFERENCES deployment_event(tenant_id,deployment_id)
);
CREATE INDEX pending_outbox ON outbox(created_at) WHERE sent_at IS NULL;
CREATE TABLE idempotency (
  tenant_id text NOT NULL, principal_id text NOT NULL, operation text NOT NULL, key text NOT NULL,
  body_hash digest256 NOT NULL, http_status int NOT NULL, response_body jsonb NOT NULL, location text,
  expires_at timestamptz NOT NULL, PRIMARY KEY(tenant_id,principal_id,operation,key)
);
-- A pool must SET LOCAL app.tenant_id on each transaction after authenticating the caller.
DO $policies$
DECLARE owned_table text;
BEGIN
  FOR owned_table IN SELECT tablename FROM pg_tables WHERE schemaname='ontology' LOOP
    EXECUTE format('ALTER TABLE ontology.%I ENABLE ROW LEVEL SECURITY',owned_table);
    EXECUTE format('ALTER TABLE ontology.%I FORCE ROW LEVEL SECURITY',owned_table);
    EXECUTE format('CREATE POLICY tenant_scope ON ontology.%I USING (tenant_id=current_setting(''app.tenant_id'', true)) WITH CHECK (tenant_id=current_setting(''app.tenant_id'', true))',owned_table);
  END LOOP;
END $policies$;
COMMIT;

verify.sql

-- Execute after core.sql in a disposable test database with a schema-owner account.
-- All fixtures and the temporary probe role are rolled back.
\set ON_ERROR_STOP on
BEGIN;
SET LOCAL search_path = ontology, pg_catalog;
SET LOCAL app.tenant_id = 'review-tenant';
INSERT INTO module VALUES ('review-tenant','M'), ('other-review-tenant','M');
INSERT INTO asset VALUES ('review-tenant','M','A','Class','urn:review:A');
INSERT INTO changeset(tenant_id,module_id,change_id) VALUES ('review-tenant','M','C');
INSERT INTO revision(tenant_id,module_id,asset_id,blob_hash,author_id)
  VALUES ('review-tenant','M','A',repeat('a',64),'author') RETURNING rev \gset
INSERT INTO change_item VALUES ('review-tenant','M','C','A','put',:rev);
INSERT INTO build(tenant_id,module_id,build_id,change_id,change_generation,input_hash,input_manifest,report_hash,state)
  SELECT 'review-tenant','M',b,'C',0,repeat('b',64),'{}'::jsonb,repeat('c',64),'passed'
  FROM unnest(ARRAY['B1','B2']) b;
INSERT INTO release VALUES ('review-tenant','M','R1','B1',repeat('d',64)),('review-tenant','M','R2','B2',repeat('e',64));
INSERT INTO member VALUES ('review-tenant','M','R1','A',:rev);
INSERT INTO projection VALUES ('review-tenant','M','R2','P2','ready',repeat('f',64));
INSERT INTO deployment(tenant_id,module_id,env,channel) VALUES ('review-tenant','M','prod','stable');
DO $test$
DECLARE n int;
BEGIN
  BEGIN
    UPDATE deployment SET generation=1,release_id='R1',projection_id='P2' WHERE tenant_id='review-tenant';
    RAISE EXCEPTION 'cross-release projection was accepted';
  EXCEPTION WHEN foreign_key_violation THEN NULL; END;
  BEGIN
    INSERT INTO member VALUES ('other-review-tenant','M','R1','A',1);
    RAISE EXCEPTION 'cross-tenant member was accepted';
  EXCEPTION WHEN foreign_key_violation THEN NULL; END;
  BEGIN
    UPDATE change_item SET op='delete' WHERE tenant_id='review-tenant';
    RAISE EXCEPTION 'invalid tombstone was accepted';
  EXCEPTION WHEN check_violation THEN NULL; END;
  BEGIN
    INSERT INTO approval(tenant_id,module_id,release_id,manifest_hash,env,reviewer,decision,reason)
      VALUES ('review-tenant','M','R1',repeat('0',64),'prod','reviewer','approve','test');
    RAISE EXCEPTION 'wrong approval digest was accepted';
  EXCEPTION WHEN foreign_key_violation THEN NULL; END;
  UPDATE deployment SET generation=1,release_id='R2',projection_id='P2' WHERE tenant_id='review-tenant' AND generation=0;
  GET DIAGNOSTICS n=ROW_COUNT; IF n<>1 THEN RAISE EXCEPTION 'first CAS failed'; END IF;
  UPDATE deployment SET generation=generation+1 WHERE tenant_id='review-tenant' AND generation=0;
  GET DIAGNOSTICS n=ROW_COUNT; IF n<>0 THEN RAISE EXCEPTION 'obsolete CAS succeeded'; END IF;
  INSERT INTO idempotency VALUES ('review-tenant','actor','POST /builds','key',repeat('a',64),202,'{}','/v1/builds/B1',now()+interval '1 day');
  BEGIN
    INSERT INTO idempotency SELECT * FROM idempotency WHERE tenant_id='review-tenant';
    RAISE EXCEPTION 'duplicate command was accepted';
  EXCEPTION WHEN unique_violation THEN NULL; END;
END $test$;
CREATE ROLE ontology_review_reader NOLOGIN;
GRANT USAGE ON SCHEMA ontology TO ontology_review_reader;
GRANT SELECT ON module TO ontology_review_reader;
SET LOCAL ROLE ontology_review_reader;
DO $test$
BEGIN
  IF (SELECT count(*) FROM module WHERE module_id='M') <> 1 OR
     EXISTS (SELECT FROM module WHERE tenant_id<>'review-tenant')
  THEN RAISE EXCEPTION 'tenant visibility leaked'; END IF;
END $test$;
RESET ROLE;
ROLLBACK;

openapi.yaml

openapi: 3.1.0
info:
  title: 本体构建平台核心接口
  version: 1.1.0
  description: 租户取自验证后的身份。所有变更命令需 Idempotency-Key。错误体固定为 Error。
servers:
- url: /v1
security:
- bearer: []
paths:
  /changesets:
    post:
      operationId: createChange
      summary: 建立变更集
      responses:
        '201':
          description: 建立变更集
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Change'
          headers:
            ETag:
              description: 变更集强校验符,例如 "C1.g7"
              schema:
                type: string
                minLength: 1
            Location:
              description: 新建资源的可轮询路径
              schema:
                type: string
                format: uri-reference
        '400':
          description: 请求或游标格式不正确
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 操作未获授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 资源不可见
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 资源状态或幂等内容冲突
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 字段或领域约束未通过
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 必需服务不可用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 128
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewChange'
  /changesets/{id}:
    get:
      operationId: getChange
      summary: 读取变更集头
      responses:
        '200':
          description: 读取变更集头
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Change'
          headers:
            ETag:
              description: 变更集强校验符,例如 "C1.g7"
              schema:
                type: string
                minLength: 1
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 操作未获授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 资源不可见
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 必需服务不可用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
    patch:
      operationId: editChange
      summary: 在同一变更集写入一个资产的完整定义或墓碑
      responses:
        '200':
          description: 在同一变更集写入一个资产的完整定义或墓碑
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Change'
          headers:
            ETag:
              description: 变更集强校验符,例如 "C1.g7"
              schema:
                type: string
                minLength: 1
        '400':
          description: 请求或游标格式不正确
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 操作未获授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 资源不可见
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 资源状态或幂等内容冲突
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '412':
          description: 草稿代次过期
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 字段或领域约束未通过
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '428':
          description: 缺少 If-Match
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 必需服务不可用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 128
      - name: If-Match
        in: header
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Edit'
  /changesets/{id}/assets/{asset}:
    get:
      operationId: readDraftAsset
      summary: 读取覆盖基线后的资产定义
      responses:
        '200':
          description: 读取覆盖基线后的资产定义
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 操作未获授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 资源不可见
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 必需服务不可用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: asset
        in: path
        required: true
        schema:
          type: string
          minLength: 1
  /builds:
    post:
      operationId: startBuild
      summary: 冻结当前输入并提交构建
      responses:
        '202':
          description: 冻结当前输入并提交构建
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildAccepted'
          headers:
            Location:
              description: 新建资源的可轮询路径
              schema:
                type: string
                format: uri-reference
        '400':
          description: 请求或游标格式不正确
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 操作未获授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 资源不可见
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 资源状态或幂等内容冲突
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 字段或领域约束未通过
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 必需服务不可用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 128
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildInput'
  /builds/{id}:
    get:
      operationId: getBuild
      summary: 读取构建状态与报告引用
      responses:
        '200':
          description: 读取构建状态与报告引用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Build'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 操作未获授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 资源不可见
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 必需服务不可用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
  /releases/{id}/approvals:
    post:
      operationId: reviewRelease
      summary: 追加环境批准或撤回
      responses:
        '201':
          description: 追加环境批准或撤回
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Approval'
        '400':
          description: 请求或游标格式不正确
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 操作未获授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 资源不可见
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 资源状态或幂等内容冲突
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 字段或领域约束未通过
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 必需服务不可用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 128
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApprovalInput'
  /deployments:
    post:
      operationId: startDeployment
      summary: 提交指定通道的部署请求
      responses:
        '202':
          description: 提交指定通道的部署请求
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentAccepted'
          headers:
            Location:
              description: 新建资源的可轮询路径
              schema:
                type: string
                format: uri-reference
        '400':
          description: 请求或游标格式不正确
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 操作未获授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 资源不可见
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 资源状态或幂等内容冲突
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 字段或领域约束未通过
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 必需服务不可用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 128
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeployInput'
  /deployments/{id}:
    get:
      operationId: getDeployment
      summary: 读取部署请求及最终结果
      responses:
        '200':
          description: 读取部署请求及最终结果
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 操作未获授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 资源不可见
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 必需服务不可用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
  /channels/active:
    get:
      operationId: getActive
      summary: 读取通道当前指针及代次
      responses:
        '200':
          description: 读取通道当前指针及代次
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pointer'
        '400':
          description: 请求或游标格式不正确
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 操作未获授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 资源不可见
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 必需服务不可用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: module
        in: query
        required: true
        schema:
          type: string
          minLength: 1
      - name: env
        in: query
        required: true
        schema:
          type: string
          minLength: 1
      - name: channel
        in: query
        required: true
        schema:
          type: string
          minLength: 1
  /queries/{name}:
    get:
      operationId: describeQuery
      summary: 读取活动版本查询的 JSON Schema
      responses:
        '200':
          description: 读取活动版本查询的 JSON Schema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryContract'
        '400':
          description: 请求或游标格式不正确
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 操作未获授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 资源不可见
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 必需服务不可用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: module
        in: query
        required: true
        schema:
          type: string
          minLength: 1
      - name: env
        in: query
        required: true
        schema:
          type: string
          minLength: 1
      - name: channel
        in: query
        required: true
        schema:
          type: string
          minLength: 1
  /queries/{name}:run:
    post:
      operationId: runQuery
      summary: 按固定视图执行查询或续页
      responses:
        '200':
          description: 按固定视图执行查询或续页
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
        '400':
          description: 请求或游标格式不正确
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 操作未获授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 资源不可见
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 资源状态或幂等内容冲突
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '410':
          description: 读快照或游标已过期
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 字段或领域约束未通过
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 必需服务不可用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryInput'
  /builds/{id}/report:
    get:
      operationId: readReport
      summary: 按当前权限读取构建报告与样本引用
      responses:
        '200':
          description: 按当前权限读取构建报告与样本引用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildReport'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 操作未获授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 资源不可见
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 资源状态或幂等内容冲突
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 必需服务不可用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
  /evidence/{id}:
    get:
      operationId: readEvidence
      summary: 按当前来源授权读取证据片段
      responses:
        '200':
          description: 按当前来源授权读取证据片段
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Evidence'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 操作未获授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 资源不可见
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '410':
          description: 读快照或游标已过期
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 必需服务不可用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
  schemas:
    Error:
      type: object
      additionalProperties: false
      properties:
        code:
          type: string
          minLength: 1
        requestId:
          type: string
          minLength: 1
        retryable:
          type: boolean
        details:
          type: object
          additionalProperties: true
      required:
      - code
      - requestId
      - retryable
      - details
    NewChange:
      type: object
      additionalProperties: false
      properties:
        module:
          type: string
          minLength: 1
        baseRelease:
          type:
          - string
          - 'null'
      required:
      - module
      - baseRelease
    Change:
      type: object
      additionalProperties: false
      properties:
        changeId:
          type: string
          minLength: 1
        module:
          type: string
          minLength: 1
        baseRelease:
          type:
          - string
          - 'null'
        generation:
          type: integer
          minimum: 0
      required:
      - changeId
      - module
      - baseRelease
      - generation
    Edit:
      oneOf:
      - type: object
        additionalProperties: false
        properties:
          op:
            type: string
            enum:
            - put
          assetId:
            type: string
            minLength: 1
          kind:
            type: string
            enum:
            - Class
          iri:
            type: string
            format: uri
          definition:
            $ref: '#/components/schemas/ClassDefinition'
        required:
        - op
        - assetId
        - kind
        - iri
        - definition
      - type: object
        additionalProperties: false
        properties:
          op:
            type: string
            enum:
            - put
          assetId:
            type: string
            minLength: 1
          kind:
            type: string
            enum:
            - Property
          iri:
            type: string
            format: uri
          definition:
            $ref: '#/components/schemas/PropertyDefinition'
        required:
        - op
        - assetId
        - kind
        - iri
        - definition
      - type: object
        additionalProperties: false
        properties:
          op:
            type: string
            enum:
            - put
          assetId:
            type: string
            minLength: 1
          kind:
            type: string
            enum:
            - Axiom
          iri:
            type: string
            format: uri
          definition:
            $ref: '#/components/schemas/AxiomDefinition'
        required:
        - op
        - assetId
        - kind
        - iri
        - definition
      - type: object
        additionalProperties: false
        properties:
          op:
            type: string
            enum:
            - put
          assetId:
            type: string
            minLength: 1
          kind:
            type: string
            enum:
            - Shape
          iri:
            type: string
            format: uri
          definition:
            $ref: '#/components/schemas/ShapeDefinition'
        required:
        - op
        - assetId
        - kind
        - iri
        - definition
      - type: object
        additionalProperties: false
        properties:
          op:
            type: string
            enum:
            - put
          assetId:
            type: string
            minLength: 1
          kind:
            type: string
            enum:
            - Mapping
          iri:
            type: string
            format: uri
          definition:
            $ref: '#/components/schemas/MappingDefinition'
        required:
        - op
        - assetId
        - kind
        - iri
        - definition
      - type: object
        additionalProperties: false
        properties:
          op:
            type: string
            enum:
            - put
          assetId:
            type: string
            minLength: 1
          kind:
            type: string
            enum:
            - QueryContract
          iri:
            type: string
            format: uri
          definition:
            $ref: '#/components/schemas/QueryContractDefinition'
        required:
        - op
        - assetId
        - kind
        - iri
        - definition
      - type: object
        additionalProperties: false
        properties:
          op:
            type: string
            enum:
            - put
          assetId:
            type: string
            minLength: 1
          kind:
            type: string
            enum:
            - ActionContract
          iri:
            type: string
            format: uri
          definition:
            $ref: '#/components/schemas/ActionContractDefinition'
        required:
        - op
        - assetId
        - kind
        - iri
        - definition
      - type: object
        additionalProperties: false
        properties:
          op:
            type: string
            enum:
            - put
          assetId:
            type: string
            minLength: 1
          kind:
            type: string
            enum:
            - TestCase
          iri:
            type: string
            format: uri
          definition:
            $ref: '#/components/schemas/TestCaseDefinition'
        required:
        - op
        - assetId
        - kind
        - iri
        - definition
      - type: object
        additionalProperties: false
        properties:
          op:
            type: string
            enum:
            - delete
          assetId:
            type: string
            minLength: 1
        required:
        - op
        - assetId
    ClassDefinition:
      type: object
      additionalProperties: false
      properties:
        label:
          type: string
          minLength: 1
        aliases:
          type: array
          items:
            type: string
            minLength: 1
        description:
          type: string
          minLength: 1
        examples:
          type: array
          items:
            type: string
            minLength: 1
      required:
      - label
    PropertyDefinition:
      type: object
      additionalProperties: false
      properties:
        label:
          type: string
          minLength: 1
        domainIri:
          type: string
          minLength: 1
        rangeIri:
          type: string
          minLength: 1
        aliases:
          type: array
          items:
            type: string
            minLength: 1
        description:
          type: string
          minLength: 1
        examples:
          type: array
          items:
            type: string
            minLength: 1
      required:
      - label
      - domainIri
      - rangeIri
    AxiomDefinition:
      type: object
      additionalProperties: false
      properties:
        label:
          type: string
          minLength: 1
        expression:
          type: string
          minLength: 1
        aliases:
          type: array
          items:
            type: string
            minLength: 1
        description:
          type: string
          minLength: 1
        examples:
          type: array
          items:
            type: string
            minLength: 1
      required:
      - label
      - expression
    ShapeDefinition:
      type: object
      additionalProperties: false
      properties:
        label:
          type: string
          minLength: 1
        shaclTurtle:
          type: string
          minLength: 1
        aliases:
          type: array
          items:
            type: string
            minLength: 1
        description:
          type: string
          minLength: 1
        examples:
          type: array
          items:
            type: string
            minLength: 1
      required:
      - label
      - shaclTurtle
    MappingDefinition:
      type: object
      additionalProperties: false
      properties:
        label:
          type: string
          minLength: 1
        sourceId:
          type: string
          minLength: 1
        mappingRef:
          type: string
          minLength: 1
        aliases:
          type: array
          items:
            type: string
            minLength: 1
        description:
          type: string
          minLength: 1
        examples:
          type: array
          items:
            type: string
            minLength: 1
      required:
      - label
      - sourceId
      - mappingRef
    QueryContractDefinition:
      type: object
      additionalProperties: false
      properties:
        label:
          type: string
          minLength: 1
        inputSchema:
          type: object
          additionalProperties: true
        rowSchema:
          type: object
          additionalProperties: true
        planRef:
          type: string
          minLength: 1
        aliases:
          type: array
          items:
            type: string
            minLength: 1
        description:
          type: string
          minLength: 1
        examples:
          type: array
          items:
            type: string
            minLength: 1
      required:
      - label
      - inputSchema
      - rowSchema
      - planRef
    ActionContractDefinition:
      type: object
      additionalProperties: false
      properties:
        label:
          type: string
          minLength: 1
        inputSchema:
          type: object
          additionalProperties: true
        adapterRef:
          type: string
          minLength: 1
        aliases:
          type: array
          items:
            type: string
            minLength: 1
        description:
          type: string
          minLength: 1
        examples:
          type: array
          items:
            type: string
            minLength: 1
      required:
      - label
      - inputSchema
      - adapterRef
    TestCaseDefinition:
      type: object
      additionalProperties: false
      properties:
        label:
          type: string
          minLength: 1
        targetIri:
          type: string
          minLength: 1
        fixtureRef:
          type: string
          minLength: 1
        expected:
          type: object
          additionalProperties: true
        aliases:
          type: array
          items:
            type: string
            minLength: 1
        description:
          type: string
          minLength: 1
        examples:
          type: array
          items:
            type: string
            minLength: 1
      required:
      - label
      - targetIri
      - fixtureRef
      - expected
    Asset:
      type: object
      additionalProperties: false
      properties:
        assetId:
          type: string
          minLength: 1
        kind:
          type: string
          enum:
          - Class
          - Property
          - Axiom
          - Shape
          - Mapping
          - QueryContract
          - ActionContract
          - TestCase
        iri:
          type: string
          minLength: 1
        rev:
          type: integer
          minimum: 0
        definition:
          type: object
          additionalProperties: true
      required:
      - assetId
      - kind
      - iri
      - rev
      - definition
    BuildInput:
      type: object
      additionalProperties: false
      properties:
        changeId:
          type: string
          minLength: 1
        changeGeneration:
          type: integer
          minimum: 0
        sampleHash:
          type: string
          pattern: ^[a-f0-9]{64}$
      required:
      - changeId
      - changeGeneration
      - sampleHash
    Build:
      oneOf:
      - type: object
        additionalProperties: false
        properties:
          buildId:
            type: string
            minLength: 1
          state:
            type: string
            enum:
            - queued
            - running
        required:
        - buildId
        - state
      - type: object
        additionalProperties: false
        properties:
          buildId:
            type: string
            minLength: 1
          state:
            type: string
            enum:
            - passed
          releaseId:
            type: string
            minLength: 1
          manifestHash:
            type: string
            pattern: ^[a-f0-9]{64}$
          reportHash:
            type: string
            pattern: ^[a-f0-9]{64}$
        required:
        - buildId
        - state
        - releaseId
        - manifestHash
        - reportHash
      - type: object
        additionalProperties: false
        properties:
          buildId:
            type: string
            minLength: 1
          state:
            type: string
            enum:
            - blocked
          reportHash:
            type: string
            pattern: ^[a-f0-9]{64}$
        required:
        - buildId
        - state
        - reportHash
      - type: object
        additionalProperties: false
        properties:
          buildId:
            type: string
            minLength: 1
          state:
            type: string
            enum:
            - failed
          error:
            $ref: '#/components/schemas/Error'
        required:
        - buildId
        - state
        - error
    ApprovalInput:
      type: object
      additionalProperties: false
      properties:
        env:
          type: string
          minLength: 1
        manifestHash:
          type: string
          pattern: ^[a-f0-9]{64}$
        decision:
          type: string
          enum:
          - approve
          - revoke
        reason:
          type: string
          minLength: 1
      required:
      - env
      - manifestHash
      - decision
      - reason
    Approval:
      type: object
      additionalProperties: false
      properties:
        approvalId:
          type: integer
          minimum: 0
        releaseId:
          type: string
          minLength: 1
        decision:
          type: string
          enum:
          - approve
          - revoke
      required:
      - approvalId
      - releaseId
      - decision
    DeployInput:
      type: object
      additionalProperties: false
      properties:
        module:
          type: string
          minLength: 1
        env:
          type: string
          minLength: 1
        channel:
          type: string
          minLength: 1
        releaseId:
          type: string
          minLength: 1
        expectedGeneration:
          type: integer
          minimum: 0
      required:
      - module
      - env
      - channel
      - releaseId
      - expectedGeneration
    Deployment:
      oneOf:
      - type: object
        additionalProperties: false
        properties:
          id:
            type: string
            minLength: 1
          status:
            type: string
            enum:
            - queued
            - preparing
        required:
        - id
        - status
      - type: object
        additionalProperties: false
        properties:
          id:
            type: string
            minLength: 1
          status:
            type: string
            enum:
            - active
          generation:
            type: integer
            minimum: 0
          releaseId:
            type: string
            minLength: 1
          projectionId:
            type: string
            minLength: 1
        required:
        - id
        - status
        - generation
        - releaseId
        - projectionId
      - type: object
        additionalProperties: false
        properties:
          id:
            type: string
            minLength: 1
          status:
            type: string
            enum:
            - conflict
            - failed
          error:
            $ref: '#/components/schemas/Error'
        required:
        - id
        - status
        - error
    QueryContract:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
        releaseId:
          type: string
          minLength: 1
        inputSchema:
          type: object
          additionalProperties: true
        rowSchema:
          type: object
          additionalProperties: true
        requiredScopes:
          type: array
          items:
            type: string
            minLength: 1
      required:
      - name
      - releaseId
      - inputSchema
      - rowSchema
      - requiredScopes
    QueryInput:
      oneOf:
      - type: object
        additionalProperties: false
        properties:
          module:
            type: string
            minLength: 1
          env:
            type: string
            minLength: 1
          channel:
            type: string
            minLength: 1
          params:
            type: object
            additionalProperties: true
          pageSize:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
          validAt:
            type: string
            format: date-time
          knownAt:
            type: string
            format: date-time
          expectedRelease:
            type: string
            minLength: 1
        required:
        - module
        - env
        - channel
        - params
      - type: object
        additionalProperties: false
        properties:
          cursor:
            type: string
            minLength: 1
        required:
        - cursor
    Result:
      oneOf:
      - type: object
        additionalProperties: false
        properties:
          status:
            type: string
            enum:
            - answered
          rows:
            type: array
            items:
              type: object
              additionalProperties: false
              properties:
                values:
                  type: object
                  additionalProperties: true
                evidenceRefs:
                  type: array
                  items:
                    type: string
                    minLength: 1
              required:
              - values
              - evidenceRefs
            minItems: 1
          nextCursor:
            type:
            - string
            - 'null'
          releaseId:
            type: string
            minLength: 1
          projectionId:
            type: string
            minLength: 1
          generation:
            type: integer
            minimum: 0
          snapshotId:
            type: string
            minLength: 1
          watermarks:
            type: object
            additionalProperties:
              type: string
        required:
        - status
        - rows
        - nextCursor
        - releaseId
        - projectionId
        - generation
        - snapshotId
        - watermarks
      - type: object
        additionalProperties: false
        properties:
          status:
            type: string
            enum:
            - empty
          rows:
            type: array
            maxItems: 0
          nextCursor:
            type: 'null'
          releaseId:
            type: string
            minLength: 1
          projectionId:
            type: string
            minLength: 1
          generation:
            type: integer
            minimum: 0
          snapshotId:
            type: string
            minLength: 1
          watermarks:
            type: object
            additionalProperties:
              type: string
        required:
        - status
        - rows
        - nextCursor
        - releaseId
        - projectionId
        - generation
        - snapshotId
        - watermarks
      - type: object
        additionalProperties: false
        properties:
          status:
            type: string
            enum:
            - unknown
            - stale
          reasonCode:
            type: string
            minLength: 1
          rows:
            type: array
            maxItems: 0
          nextCursor:
            type: 'null'
          releaseId:
            type: string
            minLength: 1
          projectionId:
            type: string
            minLength: 1
          generation:
            type: integer
            minimum: 0
          snapshotId:
            type: string
            minLength: 1
          watermarks:
            type: object
            additionalProperties:
              type: string
        required:
        - status
        - reasonCode
        - rows
        - nextCursor
        - releaseId
        - projectionId
        - generation
        - snapshotId
        - watermarks
    Pointer:
      type: object
      additionalProperties: false
      properties:
        module:
          type: string
          minLength: 1
        env:
          type: string
          minLength: 1
        channel:
          type: string
          minLength: 1
        generation:
          type: integer
          minimum: 0
        releaseId:
          type:
          - string
          - 'null'
        projectionId:
          type:
          - string
          - 'null'
      required:
      - module
      - env
      - channel
      - generation
      - releaseId
      - projectionId
    BuildReport:
      type: object
      additionalProperties: false
      properties:
        buildId:
          type: string
          minLength: 1
        reportHash:
          type: string
          pattern: ^[a-f0-9]{64}$
        summary:
          type: object
          additionalProperties: true
        findings:
          type: array
          items:
            type: object
            additionalProperties: false
            properties:
              ruleId:
                type: string
                minLength: 1
              severity:
                type: string
                enum:
                - error
                - warning
                - info
              assetId:
                type:
                - string
                - 'null'
              message:
                type: string
                minLength: 1
              evidenceRefs:
                type: array
                items:
                  type: string
                  minLength: 1
            required:
            - ruleId
            - severity
            - assetId
            - message
            - evidenceRefs
      required:
      - buildId
      - reportHash
      - summary
      - findings
    Evidence:
      type: object
      additionalProperties: false
      properties:
        evidenceId:
          type: string
          minLength: 1
        sourceId:
          type: string
          minLength: 1
        recordKey:
          type: string
          minLength: 1
        observedAt:
          type: string
          format: date-time
        excerpt:
          type: string
          minLength: 1
      required:
      - evidenceId
      - sourceId
      - recordKey
      - observedAt
      - excerpt
    BuildAccepted:
      type: object
      additionalProperties: false
      properties:
        buildId:
          type: string
          minLength: 1
        state:
          type: string
          enum:
          - queued
      required:
      - buildId
      - state
    DeploymentAccepted:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          minLength: 1
        status:
          type: string
          enum:
          - queued
      required:
      - id
      - status

读者留言

COMMENTS 暂无
仅本站原创文章开放留言 · 请勿留下手机号、邮箱等个人信息

还没有留言,来说第一句?