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 暂无还没有留言,来说第一句?