1590 lines
51 KiB
YAML
1590 lines
51 KiB
YAML
openapi: 3.0.3
|
||
info:
|
||
title: Muse MetaSchema / Governance API
|
||
version: 2.0.0
|
||
license:
|
||
name: Proprietary
|
||
description: |
|
||
MetaSchema 与治理模块全量接口，涵盖：
|
||
- MetaSchema 列表、详情、版本、草稿、校验、影响预览、发布、激活、回滚、废弃、灰度
|
||
- 保护节点注册表和详情
|
||
- 系统功能链路、影响预览和版本激活
|
||
|
||
设计文档 owner：后端-05-统一API契约-v1.md Section 3.1
|
||
|
||
servers:
|
||
- url: /
|
||
description: 同源 API 网关
|
||
|
||
paths:
|
||
# ============================================================
|
||
# MetaSchema 列表与详情
|
||
# ============================================================
|
||
/admin-api/muse/governance/meta-schemas:
|
||
get:
|
||
tags: [Governance / MetaSchema]
|
||
summary: MetaSchema 列表和版本摘要
|
||
operationId: listMetaSchemas
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageNo'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageSize'
|
||
- name: scope
|
||
in: query
|
||
description: 按作用域筛选
|
||
schema:
|
||
type: string
|
||
enum: [global, tenant, user, work]
|
||
- name: targetType
|
||
in: query
|
||
description: 按目标类型筛选（work / chapter / block / agent / knowledge_base）
|
||
schema:
|
||
type: string
|
||
- name: keyword
|
||
in: query
|
||
description: 按 schemaKey 或 displayName 模糊搜索
|
||
schema:
|
||
type: string
|
||
responses:
|
||
'200':
|
||
description: MetaSchema 分页列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
|
||
- type: object
|
||
properties:
|
||
list:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/MetaSchemaSummary'
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/governance/meta-schemas/{schemaKey}:
|
||
get:
|
||
tags: [Governance / MetaSchema]
|
||
summary: Schema 详情、当前 active 版本、灰度版本、字段继承和影响摘要
|
||
operationId: getMetaSchema
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '#/components/parameters/schemaKey'
|
||
responses:
|
||
'200':
|
||
description: MetaSchema 详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/MetaSchemaDetail'
|
||
'404':
|
||
$ref: '../openapi-base.yaml#/components/responses/NotFound'
|
||
|
||
# ============================================================
|
||
# MetaSchema 版本详情
|
||
# ============================================================
|
||
/admin-api/muse/governance/meta-schemas/{schemaKey}/versions/{version}:
|
||
get:
|
||
tags: [Governance / MetaSchema]
|
||
summary: 指定版本详情、字段、校验规则、可见性策略和发布记录
|
||
operationId: getMetaSchemaVersion
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '#/components/parameters/schemaKey'
|
||
- $ref: '#/components/parameters/version'
|
||
responses:
|
||
'200':
|
||
description: 版本详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/MetaSchemaVersionDetail'
|
||
'404':
|
||
$ref: '../openapi-base.yaml#/components/responses/NotFound'
|
||
|
||
# ============================================================
|
||
# MetaSchema 草稿
|
||
# ============================================================
|
||
/admin-api/muse/governance/meta-schemas/{schemaKey}/drafts:
|
||
post:
|
||
tags: [Governance / MetaSchema]
|
||
summary: 保存 MetaSchema 草稿，返回 draftVersion 和校验摘要
|
||
operationId: saveMetaSchemaDraft
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '#/components/parameters/schemaKey'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/MetaSchemaDraftRequest'
|
||
responses:
|
||
'200':
|
||
description: 草稿保存成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/MetaSchemaDraftResponse'
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'404':
|
||
$ref: '../openapi-base.yaml#/components/responses/NotFound'
|
||
|
||
# ============================================================
|
||
# 草稿校验
|
||
# ============================================================
|
||
/admin-api/muse/governance/meta-schemas/{schemaKey}/drafts/{draftVersion}/validate:
|
||
post:
|
||
tags: [Governance / MetaSchema]
|
||
summary: 校验字段类型、必填、枚举、引用、兼容性和保护节点边界
|
||
operationId: validateMetaSchemaDraft
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '#/components/parameters/schemaKey'
|
||
- $ref: '#/components/parameters/draftVersion'
|
||
responses:
|
||
'200':
|
||
description: 校验结果
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/ValidationResult'
|
||
'404':
|
||
$ref: '../openapi-base.yaml#/components/responses/NotFound'
|
||
|
||
# ============================================================
|
||
# 草稿影响预览
|
||
# ============================================================
|
||
/admin-api/muse/governance/meta-schemas/{schemaKey}/drafts/{draftVersion}/impact-preview:
|
||
post:
|
||
tags: [Governance / MetaSchema]
|
||
summary: 影响预览，返回作品、规划、知识投影、AI 上下文和导出影响
|
||
operationId: previewMetaSchemaDraftImpact
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '#/components/parameters/schemaKey'
|
||
- $ref: '#/components/parameters/draftVersion'
|
||
responses:
|
||
'200':
|
||
description: 影响预览结果
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/MetaSchemaImpactPreview'
|
||
'404':
|
||
$ref: '../openapi-base.yaml#/components/responses/NotFound'
|
||
|
||
# ============================================================
|
||
# 草稿发布
|
||
# ============================================================
|
||
/admin-api/muse/governance/meta-schemas/{schemaKey}/drafts/{draftVersion}/publish:
|
||
post:
|
||
tags: [Governance / MetaSchema]
|
||
summary: 发布版本，必须带 commandId、理由、校验结果和影响预览引用
|
||
operationId: publishMetaSchemaDraft
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '#/components/parameters/schemaKey'
|
||
- $ref: '#/components/parameters/draftVersion'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/MetaSchemaPublishRequest'
|
||
responses:
|
||
'200':
|
||
description: 发布成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/MetaSchemaPublishResponse'
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'409':
|
||
$ref: '../openapi-base.yaml#/components/responses/Conflict'
|
||
|
||
# ============================================================
|
||
# 版本激活
|
||
# ============================================================
|
||
/admin-api/muse/governance/meta-schemas/{schemaKey}/versions/{version}/activate:
|
||
post:
|
||
tags: [Governance / MetaSchema]
|
||
summary: 激活 MetaSchema 版本，支持全量或灰度范围
|
||
operationId: activateMetaSchemaVersion
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '#/components/parameters/schemaKey'
|
||
- $ref: '#/components/parameters/version'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/MetaSchemaActivateRequest'
|
||
responses:
|
||
'200':
|
||
description: 激活成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/MetaSchemaActivateResponse'
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'409':
|
||
$ref: '../openapi-base.yaml#/components/responses/Conflict'
|
||
|
||
# ============================================================
|
||
# 版本回滚
|
||
# ============================================================
|
||
/admin-api/muse/governance/meta-schemas/{schemaKey}/versions/{version}/rollback:
|
||
post:
|
||
tags: [Governance / MetaSchema]
|
||
summary: 回滚到指定已发布版本，触发投影失效或重建任务
|
||
operationId: rollbackMetaSchemaVersion
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '#/components/parameters/schemaKey'
|
||
- $ref: '#/components/parameters/version'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/MetaSchemaRollbackRequest'
|
||
responses:
|
||
'200':
|
||
description: 回滚成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/MetaSchemaRollbackResponse'
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'409':
|
||
$ref: '../openapi-base.yaml#/components/responses/Conflict'
|
||
|
||
# ============================================================
|
||
# 版本废弃
|
||
# ============================================================
|
||
/admin-api/muse/governance/meta-schemas/{schemaKey}/versions/{version}/deprecate:
|
||
post:
|
||
tags: [Governance / MetaSchema]
|
||
summary: 废弃版本或字段，必须给出替代字段、保留期和迁移提示
|
||
operationId: deprecateMetaSchemaVersion
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '#/components/parameters/schemaKey'
|
||
- $ref: '#/components/parameters/version'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/MetaSchemaDeprecateRequest'
|
||
responses:
|
||
'200':
|
||
description: 废弃成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/MetaSchemaDeprecateResponse'
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'409':
|
||
$ref: '../openapi-base.yaml#/components/responses/Conflict'
|
||
|
||
# ============================================================
|
||
# 灰度规则
|
||
# ============================================================
|
||
/admin-api/muse/governance/meta-schemas/{schemaKey}/versions/{version}/gray-rules:
|
||
post:
|
||
tags: [Governance / MetaSchema]
|
||
summary: 设置或调整灰度规则，返回灰度范围和回滚入口
|
||
operationId: setMetaSchemaGrayRules
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '#/components/parameters/schemaKey'
|
||
- $ref: '#/components/parameters/version'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/MetaSchemaGrayRulesRequest'
|
||
responses:
|
||
'200':
|
||
description: 灰度规则设置成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/MetaSchemaGrayRulesResponse'
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'409':
|
||
$ref: '../openapi-base.yaml#/components/responses/Conflict'
|
||
|
||
# ============================================================
|
||
# 保护节点注册表
|
||
# ============================================================
|
||
/admin-api/muse/governance/protection-nodes:
|
||
get:
|
||
tags: [Governance / ProtectionNode]
|
||
summary: 保护节点注册表、权限点、不可替换原因和审计摘要
|
||
operationId: listProtectionNodes
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageNo'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageSize'
|
||
- name: chainKey
|
||
in: query
|
||
description: 按所属功能链路筛选
|
||
schema:
|
||
type: string
|
||
responses:
|
||
'200':
|
||
description: 保护节点注册表分页列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
|
||
- type: object
|
||
properties:
|
||
list:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ProtectionNodeSummary'
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/governance/protection-nodes/{nodeKey}:
|
||
get:
|
||
tags: [Governance / ProtectionNode]
|
||
summary: 保护节点详情、所属链路、Shadow→Canonical 边界和可观测指标
|
||
operationId: getProtectionNode
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '#/components/parameters/nodeKey'
|
||
responses:
|
||
'200':
|
||
description: 保护节点详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/ProtectionNodeDetail'
|
||
'404':
|
||
$ref: '../openapi-base.yaml#/components/responses/NotFound'
|
||
|
||
# ============================================================
|
||
# 系统功能链路
|
||
# ============================================================
|
||
/admin-api/muse/governance/function-chains:
|
||
get:
|
||
tags: [Governance / FunctionChain]
|
||
summary: 系统功能链路和开放槽位
|
||
description: 系统保护节点只读展示，不得被降级为用户可替换槽位；开放槽位只表示可替换的非保护节点。
|
||
operationId: listFunctionChains
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageNo'
|
||
- $ref: '../openapi-base.yaml#/components/parameters/pageSize'
|
||
responses:
|
||
'200':
|
||
description: 系统功能链路分页列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
|
||
- type: object
|
||
properties:
|
||
list:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/FunctionChainSummary'
|
||
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'401':
|
||
$ref: '../openapi-base.yaml#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '../openapi-base.yaml#/components/responses/Forbidden'
|
||
/admin-api/muse/governance/function-chains/{chainKey}/impact-preview:
|
||
post:
|
||
tags: [Governance / FunctionChain]
|
||
summary: 发布前影响预览
|
||
operationId: previewFunctionChainImpact
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '#/components/parameters/chainKey'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/FunctionChainImpactPreviewRequest'
|
||
responses:
|
||
'200':
|
||
description: 功能链路影响预览结果
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/FunctionChainImpactPreview'
|
||
'404':
|
||
$ref: '../openapi-base.yaml#/components/responses/NotFound'
|
||
|
||
/admin-api/muse/governance/function-chains/{chainKey}/versions/{version}/activate:
|
||
post:
|
||
tags: [Governance / FunctionChain]
|
||
summary: 激活功能链路版本
|
||
operationId: activateFunctionChainVersion
|
||
security:
|
||
- adminBearerAuth: []
|
||
parameters:
|
||
- $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
|
||
- $ref: '#/components/parameters/chainKey'
|
||
- $ref: '#/components/parameters/version'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/FunctionChainActivateRequest'
|
||
responses:
|
||
'200':
|
||
description: 激活成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
|
||
- type: object
|
||
properties:
|
||
data:
|
||
$ref: '#/components/schemas/FunctionChainActivateResponse'
|
||
'400':
|
||
$ref: '../openapi-base.yaml#/components/responses/BadRequest'
|
||
'409':
|
||
$ref: '../openapi-base.yaml#/components/responses/Conflict'
|
||
|
||
# ============================================================
|
||
# Components
|
||
# ============================================================
|
||
components:
|
||
securitySchemes:
|
||
adminBearerAuth:
|
||
type: http
|
||
scheme: bearer
|
||
bearerFormat: JWT
|
||
description: 管理后台认证 scheme，仅用于 /admin-api/** 接口，admin-api token 与 app-api token 不互通。
|
||
appBearerAuth:
|
||
type: http
|
||
scheme: bearer
|
||
bearerFormat: JWT
|
||
description: 用户端认证 scheme，仅用于 /app-api/** 接口，app-api token 与 admin-api token 不互通。
|
||
# ---------- 公共路径参数 ----------
|
||
parameters:
|
||
schemaKey:
|
||
name: schemaKey
|
||
in: path
|
||
required: true
|
||
description: MetaSchema 业务标识
|
||
schema:
|
||
type: string
|
||
|
||
version:
|
||
name: version
|
||
in: path
|
||
required: true
|
||
description: 版本号
|
||
schema:
|
||
type: integer
|
||
|
||
draftVersion:
|
||
name: draftVersion
|
||
in: path
|
||
required: true
|
||
description: 草稿版本号
|
||
schema:
|
||
type: integer
|
||
|
||
nodeKey:
|
||
name: nodeKey
|
||
in: path
|
||
required: true
|
||
description: 保护节点业务标识
|
||
schema:
|
||
type: string
|
||
|
||
chainKey:
|
||
name: chainKey
|
||
in: path
|
||
required: true
|
||
description: 系统功能链路业务标识
|
||
schema:
|
||
type: string
|
||
|
||
# ---------- 数据模型 ----------
|
||
schemas:
|
||
# ---- MetaField 可见性 ----
|
||
MetaFieldVisibility:
|
||
type: object
|
||
description: |
|
||
MetaField 可见性策略。
|
||
uiVisible=false 不代表不能进入 AI 上下文；aiContext=true 不代表用户可见；
|
||
exportable=true 仍必须受 owner、授权、来源状态和导出许可约束。
|
||
properties:
|
||
uiVisible:
|
||
type: boolean
|
||
description: 是否进入用户可见投影
|
||
default: true
|
||
aiContext:
|
||
type: boolean
|
||
description: 是否允许进入 AI 上下文组装
|
||
default: true
|
||
userEditable:
|
||
type: boolean
|
||
description: 用户端是否允许保存该动态字段
|
||
default: false
|
||
userSearchable:
|
||
type: boolean
|
||
description: 是否允许用户搜索或筛选
|
||
default: false
|
||
exportable:
|
||
type: boolean
|
||
description: 是否可被导出预检纳入
|
||
default: false
|
||
|
||
# ---- MetaField 定义 ----
|
||
MetaField:
|
||
type: object
|
||
required: [fieldKey, displayName, fieldType]
|
||
properties:
|
||
fieldKey:
|
||
type: string
|
||
description: 字段业务标识（英文）
|
||
displayName:
|
||
type: string
|
||
description: 显示名称
|
||
fieldType:
|
||
type: string
|
||
enum: [string, text, number, boolean, date, enum, relation, json]
|
||
description: 字段类型
|
||
scope:
|
||
type: string
|
||
enum: [global, tenant, user, work]
|
||
description: 作用域
|
||
defaultValue:
|
||
description: 默认值
|
||
required:
|
||
type: boolean
|
||
default: false
|
||
description: 是否必填
|
||
enumValues:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: fieldType=enum 时的可选值
|
||
validationRules:
|
||
type: object
|
||
description: 校验规则（min/max/pattern 等）
|
||
visibility:
|
||
$ref: '#/components/schemas/MetaFieldVisibility'
|
||
deprecated:
|
||
type: boolean
|
||
default: false
|
||
description: 字段是否已废弃
|
||
deprecatedInfo:
|
||
$ref: '#/components/schemas/FieldDeprecationInfo'
|
||
inheritedFrom:
|
||
type: string
|
||
description: 字段继承来源 schemaKey（若为继承字段）
|
||
protectionNodeBound:
|
||
type: boolean
|
||
default: false
|
||
description: 该字段是否绑定保护节点边界
|
||
|
||
FieldDeprecationInfo:
|
||
type: object
|
||
description: 字段废弃信息
|
||
properties:
|
||
replacementFieldKey:
|
||
type: string
|
||
description: 替代字段标识
|
||
retentionPeriod:
|
||
type: string
|
||
description: 保留期（如 6m / 1y）
|
||
migrationHint:
|
||
type: string
|
||
description: 迁移提示
|
||
|
||
# ---- MetaSchema 列表摘要 ----
|
||
MetaSchemaSummary:
|
||
type: object
|
||
required: [schemaKey, displayName, scope, activeVersion]
|
||
properties:
|
||
schemaKey:
|
||
type: string
|
||
description: Schema 业务标识
|
||
displayName:
|
||
type: string
|
||
description: 显示名称
|
||
scope:
|
||
type: string
|
||
enum: [global, tenant, user, work]
|
||
targetType:
|
||
type: string
|
||
description: 目标类型（work / chapter / block / agent / knowledge_base）
|
||
activeVersion:
|
||
type: integer
|
||
description: 当前激活版本号
|
||
grayVersion:
|
||
type: integer
|
||
description: 当前灰度版本号（若有）
|
||
draftVersion:
|
||
type: integer
|
||
description: 最新草稿版本号（若有）
|
||
fieldCount:
|
||
type: integer
|
||
description: 字段数量
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
# ---- MetaSchema 详情 ----
|
||
MetaSchemaDetail:
|
||
type: object
|
||
required: [schemaKey, displayName, scope, activeVersion]
|
||
properties:
|
||
schemaKey:
|
||
type: string
|
||
displayName:
|
||
type: string
|
||
description:
|
||
type: string
|
||
scope:
|
||
type: string
|
||
enum: [global, tenant, user, work]
|
||
targetType:
|
||
type: string
|
||
activeVersion:
|
||
type: integer
|
||
activeVersionPublishedAt:
|
||
type: string
|
||
format: date-time
|
||
grayVersion:
|
||
type: integer
|
||
grayVersionPublishedAt:
|
||
type: string
|
||
format: date-time
|
||
grayRules:
|
||
$ref: '#/components/schemas/GrayRulesSummary'
|
||
fields:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/MetaField'
|
||
description: 当前 active 版本字段列表
|
||
inheritedSchemas:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
schemaKey:
|
||
type: string
|
||
inheritedFieldCount:
|
||
type: integer
|
||
description: 字段继承关系
|
||
impactSummary:
|
||
$ref: '#/components/schemas/MetaSchemaImpactSummary'
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
GrayRulesSummary:
|
||
type: object
|
||
description: 灰度规则摘要
|
||
properties:
|
||
strategy:
|
||
type: string
|
||
enum: [tenant_whitelist, percentage, user_whitelist]
|
||
description: 灰度策略
|
||
scope:
|
||
type: string
|
||
description: 灰度范围描述
|
||
rollbackEntry:
|
||
type: string
|
||
description: 回滚入口说明
|
||
|
||
MetaSchemaImpactSummary:
|
||
type: object
|
||
description: 影响摘要（列表级别轻量信息）
|
||
properties:
|
||
affectedWorkCount:
|
||
type: integer
|
||
description: 受影响作品数
|
||
affectedProjectionCount:
|
||
type: integer
|
||
description: 受影响投影数
|
||
affectedAIContextCount:
|
||
type: integer
|
||
description: 受影响 AI 上下文引用数
|
||
|
||
# ---- MetaSchema 版本详情 ----
|
||
MetaSchemaVersionDetail:
|
||
type: object
|
||
required: [schemaKey, version, status]
|
||
properties:
|
||
schemaKey:
|
||
type: string
|
||
version:
|
||
type: integer
|
||
status:
|
||
type: string
|
||
enum: [draft, published, active, deprecated, archived]
|
||
fields:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/MetaField'
|
||
fieldDiff:
|
||
$ref: '#/components/schemas/MetaSchemaVersionDiff'
|
||
publishRecord:
|
||
$ref: '#/components/schemas/MetaSchemaPublishRecord'
|
||
publishedAt:
|
||
type: string
|
||
format: date-time
|
||
publishedBy:
|
||
type: string
|
||
description: 发布操作者
|
||
activatedAt:
|
||
type: string
|
||
format: date-time
|
||
deprecatedAt:
|
||
type: string
|
||
format: date-time
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
MetaSchemaVersionDiff:
|
||
type: object
|
||
description: 与前一版本的字段差异
|
||
properties:
|
||
addedFields:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: 新增字段 fieldKey 列表
|
||
removedFields:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: 删除字段 fieldKey 列表
|
||
modifiedFields:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: 变更字段 fieldKey 列表
|
||
deprecatedFields:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: 废弃字段 fieldKey 列表
|
||
|
||
MetaSchemaPublishRecord:
|
||
type: object
|
||
description: 发布审计记录
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
reason:
|
||
type: string
|
||
validationResultId:
|
||
type: string
|
||
description: 关联校验结果 ID
|
||
impactPreviewId:
|
||
type: string
|
||
description: 关联影响预览 ID
|
||
expectedVersion:
|
||
type: integer
|
||
description: 发布时期望的当前版本
|
||
|
||
# ---- 草稿保存 ----
|
||
MetaSchemaDraftRequest:
|
||
type: object
|
||
required: [commandId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
expectedVersion:
|
||
type: integer
|
||
description: 期望当前 active 版本，用于乐观锁
|
||
displayName:
|
||
type: string
|
||
description: 显示名称
|
||
description:
|
||
type: string
|
||
fields:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/MetaField'
|
||
description: 完整字段定义（全量替换）
|
||
|
||
MetaSchemaDraftResponse:
|
||
type: object
|
||
properties:
|
||
draftVersion:
|
||
type: integer
|
||
description: 分配的草稿版本号
|
||
validationSummary:
|
||
$ref: '#/components/schemas/ValidationResult'
|
||
currentActiveVersion:
|
||
type: integer
|
||
description: 当前激活版本号
|
||
|
||
# ---- 校验结果 ----
|
||
ValidationResult:
|
||
type: object
|
||
properties:
|
||
validationResultId:
|
||
type: string
|
||
description: 校验结果引用 ID；发布、激活等治理命令必须引用同一草稿或目标版本的校验结果。
|
||
valid:
|
||
type: boolean
|
||
description: 是否校验通过
|
||
errors:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ValidationError'
|
||
description: 校验错误列表
|
||
warnings:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ValidationWarning'
|
||
description: 校验警告列表
|
||
compatibilityResult:
|
||
$ref: '#/components/schemas/CompatibilityResult'
|
||
|
||
ValidationError:
|
||
type: object
|
||
required: [code, message]
|
||
properties:
|
||
code:
|
||
type: string
|
||
description: 错误码（如 FIELD_TYPE_INVALID / REQUIRED_FIELD_MISSING / ENUM_VALUE_EMPTY / REFERENCE_NOT_FOUND / PROTECTION_NODE_BOUNDARY_VIOLATION）
|
||
message:
|
||
type: string
|
||
fieldKey:
|
||
type: string
|
||
description: 关联字段标识
|
||
detail:
|
||
type: string
|
||
|
||
ValidationWarning:
|
||
type: object
|
||
required: [code, message]
|
||
properties:
|
||
code:
|
||
type: string
|
||
description: 警告码（如 FIELD_DEPRECATED_STILL_USED / BREAKING_CHANGE_DETECTED）
|
||
message:
|
||
type: string
|
||
fieldKey:
|
||
type: string
|
||
detail:
|
||
type: string
|
||
|
||
CompatibilityResult:
|
||
type: object
|
||
description: 与前一版本兼容性分析
|
||
properties:
|
||
compatible:
|
||
type: boolean
|
||
breakingChanges:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
fieldKey:
|
||
type: string
|
||
changeType:
|
||
type: string
|
||
enum: [type_changed, required_added, enum_removed, reference_changed, visibility_restricted]
|
||
description:
|
||
type: string
|
||
protectionNodeBoundaryViolations:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
fieldKey:
|
||
type: string
|
||
nodeKey:
|
||
type: string
|
||
violation:
|
||
type: string
|
||
|
||
# ---- 影响预览 ----
|
||
MetaSchemaImpactPreview:
|
||
type: object
|
||
properties:
|
||
impactPreviewId:
|
||
type: string
|
||
description: 影响预览记录 ID，供发布时引用
|
||
schemaKey:
|
||
type: string
|
||
draftVersion:
|
||
type: integer
|
||
workImpact:
|
||
$ref: '#/components/schemas/WorkImpactSummary'
|
||
planningImpact:
|
||
$ref: '#/components/schemas/PlanningImpactSummary'
|
||
knowledgeProjectionImpact:
|
||
$ref: '#/components/schemas/KnowledgeProjectionImpactSummary'
|
||
aiContextImpact:
|
||
$ref: '#/components/schemas/AIContextImpactSummary'
|
||
exportImpact:
|
||
$ref: '#/components/schemas/ExportImpactSummary'
|
||
totalAffectedProjectionCount:
|
||
type: integer
|
||
description: 受影响投影总数
|
||
|
||
WorkImpactSummary:
|
||
type: object
|
||
properties:
|
||
affectedWorkCount:
|
||
type: integer
|
||
affectedDynamicFieldWorkCount:
|
||
type: integer
|
||
worksWithDeprecatedFields:
|
||
type: integer
|
||
|
||
PlanningImpactSummary:
|
||
type: object
|
||
properties:
|
||
affectedPlanningSections:
|
||
type: integer
|
||
planningUsingDeprecatedFields:
|
||
type: integer
|
||
|
||
KnowledgeProjectionImpactSummary:
|
||
type: object
|
||
properties:
|
||
affectedProjections:
|
||
type: integer
|
||
projectionsNeedingRebuild:
|
||
type: integer
|
||
projectionsWithVisibilityChange:
|
||
type: integer
|
||
|
||
AIContextImpactSummary:
|
||
type: object
|
||
properties:
|
||
affectedAIContexts:
|
||
type: integer
|
||
contextsWithFieldRemoved:
|
||
type: integer
|
||
contextsWithVisibilityChange:
|
||
type: integer
|
||
|
||
ExportImpactSummary:
|
||
type: object
|
||
properties:
|
||
affectedExportPolicies:
|
||
type: integer
|
||
exportsWithFieldRemoved:
|
||
type: integer
|
||
exportsWithVisibilityChange:
|
||
type: integer
|
||
|
||
# ---- 发布请求 ----
|
||
MetaSchemaPublishRequest:
|
||
type: object
|
||
required: [commandId, reason, expectedVersion, validationResultId, impactPreviewId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
reason:
|
||
type: string
|
||
description: 发布理由
|
||
expectedVersion:
|
||
type: integer
|
||
description: 期望当前版本，乐观锁
|
||
validationResultId:
|
||
type: string
|
||
description: 校验结果引用 ID
|
||
impactPreviewId:
|
||
type: string
|
||
description: 影响预览引用 ID
|
||
autoActivate:
|
||
type: boolean
|
||
default: false
|
||
description: 固定为 false；发布不得隐式激活，必须单独调用 activate 并携带 expectedActiveVersion、validationResultId 和 impactPreviewId。
|
||
|
||
MetaSchemaPublishResponse:
|
||
type: object
|
||
properties:
|
||
publishedVersion:
|
||
type: integer
|
||
description: 发布后的版本号
|
||
status:
|
||
type: string
|
||
enum: [published]
|
||
description: 发布后状态
|
||
currentActiveVersion:
|
||
type: integer
|
||
affectedProjectionCount:
|
||
type: integer
|
||
description: 受影响投影数
|
||
nextActions:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
action:
|
||
type: string
|
||
enum: [activate, gray_release, impact_review]
|
||
description:
|
||
type: string
|
||
|
||
# ---- 激活请求 ----
|
||
MetaSchemaActivateRequest:
|
||
type: object
|
||
required: [commandId, reason, expectedActiveVersion, validationResultId, impactPreviewId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
reason:
|
||
type: string
|
||
description: 激活理由
|
||
activateMode:
|
||
type: string
|
||
enum: [full, gray]
|
||
default: full
|
||
description: 激活模式：全量或灰度
|
||
grayRules:
|
||
$ref: '#/components/schemas/GrayRulesConfig'
|
||
expectedActiveVersion:
|
||
type: integer
|
||
description: 期望当前激活版本，乐观锁
|
||
validationResultId:
|
||
type: string
|
||
description: 激活前校验结果引用 ID
|
||
impactPreviewId:
|
||
type: string
|
||
description: 激活影响预览引用 ID
|
||
|
||
GrayRulesConfig:
|
||
type: object
|
||
description: 灰度规则配置
|
||
properties:
|
||
strategy:
|
||
type: string
|
||
enum: [tenant_whitelist, percentage, user_whitelist]
|
||
description: 灰度策略
|
||
tenantWhitelist:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: strategy=tenant_whitelist 时生效
|
||
percentage:
|
||
type: integer
|
||
minimum: 0
|
||
maximum: 100
|
||
description: strategy=percentage 时生效
|
||
userWhitelist:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: strategy=user_whitelist 时生效
|
||
|
||
MetaSchemaActivateResponse:
|
||
type: object
|
||
properties:
|
||
schemaKey:
|
||
type: string
|
||
activatedVersion:
|
||
type: integer
|
||
activateMode:
|
||
type: string
|
||
enum: [full, gray]
|
||
previousActiveVersion:
|
||
type: integer
|
||
affectedProjectionCount:
|
||
type: integer
|
||
projectionRebuildJobId:
|
||
type: string
|
||
description: 投影重建任务 ID（若有）
|
||
|
||
# ---- 回滚请求 ----
|
||
MetaSchemaRollbackRequest:
|
||
type: object
|
||
required: [commandId, reason, expectedActiveVersion, validationResultId, impactPreviewId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
reason:
|
||
type: string
|
||
description: 回滚理由
|
||
expectedActiveVersion:
|
||
type: integer
|
||
description: 期望当前激活版本，乐观锁
|
||
validationResultId:
|
||
type: string
|
||
description: 回滚前校验结果引用 ID
|
||
impactPreviewId:
|
||
type: string
|
||
description: 回滚影响预览引用 ID
|
||
|
||
MetaSchemaRollbackResponse:
|
||
type: object
|
||
properties:
|
||
schemaKey:
|
||
type: string
|
||
rolledBackToVersion:
|
||
type: integer
|
||
previousActiveVersion:
|
||
type: integer
|
||
affectedProjectionCount:
|
||
type: integer
|
||
projectionRebuildJobId:
|
||
type: string
|
||
description: 投影重建任务 ID
|
||
projectionInvalidateJobId:
|
||
type: string
|
||
description: 投影失效任务 ID
|
||
|
||
# ---- 废弃请求 ----
|
||
MetaSchemaDeprecateRequest:
|
||
type: object
|
||
required: [commandId, reason, expectedVersion, validationResultId, impactPreviewId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
reason:
|
||
type: string
|
||
description: 废弃理由
|
||
expectedVersion:
|
||
type: integer
|
||
description: 期望被废弃版本，乐观锁
|
||
validationResultId:
|
||
type: string
|
||
description: 废弃前校验结果引用 ID
|
||
impactPreviewId:
|
||
type: string
|
||
description: 废弃影响预览引用 ID
|
||
deprecateFields:
|
||
type: array
|
||
items:
|
||
type: object
|
||
required: [fieldKey]
|
||
properties:
|
||
fieldKey:
|
||
type: string
|
||
replacementFieldKey:
|
||
type: string
|
||
description: 替代字段标识
|
||
retentionPeriod:
|
||
type: string
|
||
description: 保留期（如 6m / 1y）
|
||
migrationHint:
|
||
type: string
|
||
description: 迁移提示
|
||
deprecateEntireVersion:
|
||
type: boolean
|
||
default: false
|
||
description: 是否废弃整个版本
|
||
replacementVersion:
|
||
type: integer
|
||
description: 替代版本号（废弃整个版本时必填）
|
||
|
||
MetaSchemaDeprecateResponse:
|
||
type: object
|
||
properties:
|
||
schemaKey:
|
||
type: string
|
||
version:
|
||
type: integer
|
||
deprecatedFields:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: 已废弃字段列表
|
||
entireVersionDeprecated:
|
||
type: boolean
|
||
affectedProjectionCount:
|
||
type: integer
|
||
nextActions:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
action:
|
||
type: string
|
||
enum: [migrate_data, activate_replacement, review_impact]
|
||
description:
|
||
type: string
|
||
|
||
# ---- 灰度规则请求 ----
|
||
MetaSchemaGrayRulesRequest:
|
||
type: object
|
||
required: [commandId, reason]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
reason:
|
||
type: string
|
||
description: 调整理由
|
||
action:
|
||
type: string
|
||
enum: [set, adjust, remove]
|
||
default: set
|
||
description: 操作类型：设置、调整或移除灰度规则
|
||
grayRules:
|
||
$ref: '#/components/schemas/GrayRulesConfig'
|
||
|
||
MetaSchemaGrayRulesResponse:
|
||
type: object
|
||
properties:
|
||
schemaKey:
|
||
type: string
|
||
version:
|
||
type: integer
|
||
grayRules:
|
||
$ref: '#/components/schemas/GrayRulesConfig'
|
||
affectedScope:
|
||
type: string
|
||
description: 当前灰度影响范围描述
|
||
rollbackEntry:
|
||
type: string
|
||
description: 回滚入口
|
||
|
||
# ---- 保护节点摘要 ----
|
||
ProtectionNodeSummary:
|
||
type: object
|
||
required: [nodeKey, displayName, nodeType, irreplaceable]
|
||
properties:
|
||
nodeKey:
|
||
type: string
|
||
description: 保护节点业务标识
|
||
displayName:
|
||
type: string
|
||
nodeType:
|
||
type: string
|
||
enum: [input_output_compliance, chunking, rag_indexing, semantic_safety, static_check, quality_gate]
|
||
description: 保护节点类型
|
||
irreplaceable:
|
||
type: boolean
|
||
description: 是否不可替换。保护节点不可被用户替换、覆盖或降级为开放槽位。
|
||
irreplaceableReason:
|
||
type: string
|
||
description: 不可替换原因
|
||
chainKey:
|
||
type: string
|
||
description: 所属功能链路标识
|
||
auditSummary:
|
||
type: string
|
||
description: 审计摘要
|
||
|
||
# ---- 保护节点详情 ----
|
||
ProtectionNodeDetail:
|
||
type: object
|
||
required: [nodeKey, displayName, nodeType, irreplaceable]
|
||
properties:
|
||
nodeKey:
|
||
type: string
|
||
displayName:
|
||
type: string
|
||
description:
|
||
type: string
|
||
nodeType:
|
||
type: string
|
||
enum: [input_output_compliance, chunking, rag_indexing, semantic_safety, static_check, quality_gate]
|
||
irreplaceable:
|
||
type: boolean
|
||
description: 是否不可替换。服务端必须拒绝把保护节点降级为用户可替换槽位的草稿、发布或激活命令。
|
||
irreplaceableReason:
|
||
type: string
|
||
permissionRequirement:
|
||
type: string
|
||
description: 权限要求
|
||
auditRequirement:
|
||
type: string
|
||
description: 审计要求
|
||
shadowToCanonicalBoundary:
|
||
type: string
|
||
description: Shadow→Canonical 边界说明
|
||
chainKey:
|
||
type: string
|
||
description: 所属功能链路标识
|
||
chainDisplayName:
|
||
type: string
|
||
observabilityMetrics:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
metricName:
|
||
type: string
|
||
metricValue:
|
||
type: string
|
||
description:
|
||
type: string
|
||
description: 可观测指标
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
# ---- 功能链路摘要 ----
|
||
FunctionChainSummary:
|
||
type: object
|
||
required: [chainKey, displayName, activeVersion]
|
||
properties:
|
||
chainKey:
|
||
type: string
|
||
description: 功能链路业务标识
|
||
displayName:
|
||
type: string
|
||
description:
|
||
type: string
|
||
activeVersion:
|
||
type: integer
|
||
openSlotCount:
|
||
type: integer
|
||
description: 开放槽位数
|
||
protectionNodeCount:
|
||
type: integer
|
||
description: 保护节点数
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
# ---- 功能链路影响预览请求 ----
|
||
FunctionChainImpactPreviewRequest:
|
||
type: object
|
||
required: [commandId]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
targetVersion:
|
||
type: integer
|
||
description: 预发布的目标版本号
|
||
expectedCurrentVersion:
|
||
type: integer
|
||
description: 期望当前激活版本，乐观锁
|
||
|
||
FunctionChainImpactPreview:
|
||
type: object
|
||
properties:
|
||
impactPreviewId:
|
||
type: string
|
||
validationResultId:
|
||
type: string
|
||
description: 功能链路激活前校验结果引用 ID；必须与 impactPreviewId、chainKey、targetVersion 同源。
|
||
chainKey:
|
||
type: string
|
||
targetVersion:
|
||
type: integer
|
||
affectedAgentSlotBindings:
|
||
type: integer
|
||
description: 受影响的智能体槽位绑定数
|
||
affectedAIRuntimeTasks:
|
||
type: integer
|
||
description: 受影响的 AI 运行时任务数
|
||
affectedProtectionNodeChanges:
|
||
type: integer
|
||
description: 保护节点变更数
|
||
protectionNodeImpactDetails:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
nodeKey:
|
||
type: string
|
||
changeType:
|
||
type: string
|
||
enum: [added, removed, modified]
|
||
impactDescription:
|
||
type: string
|
||
slotChanges:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
slotKey:
|
||
type: string
|
||
changeType:
|
||
type: string
|
||
enum: [added, removed, protection_upgraded, protection_boundary_violation]
|
||
description: protection_boundary_violation 表示草稿试图把保护节点降级为开放槽位，激活时必须阻断。
|
||
impactDescription:
|
||
type: string
|
||
|
||
# ---- 功能链路激活请求 ----
|
||
FunctionChainActivateRequest:
|
||
type: object
|
||
description: 激活功能链路版本。必须引用通过校验和影响预览的结果；若预览包含保护节点降级为开放槽位的边界违规，服务端必须拒绝激活。
|
||
required: [commandId, reason, validationResultId, impactPreviewId, expectedActiveVersion]
|
||
properties:
|
||
commandId:
|
||
type: string
|
||
description: 幂等键
|
||
reason:
|
||
type: string
|
||
description: 激活理由
|
||
impactPreviewId:
|
||
type: string
|
||
description: 影响预览引用 ID
|
||
validationResultId:
|
||
type: string
|
||
description: 激活前校验结果引用 ID
|
||
expectedActiveVersion:
|
||
type: integer
|
||
description: 期望当前激活版本，乐观锁
|
||
|
||
FunctionChainActivateResponse:
|
||
type: object
|
||
properties:
|
||
chainKey:
|
||
type: string
|
||
activatedVersion:
|
||
type: integer
|
||
previousActiveVersion:
|
||
type: integer
|
||
affectedSlotBindings:
|
||
type: integer
|
||
affectedRuntimeTasks:
|
||
type: integer
|
||
|
||
tags:
|
||
- name: Governance / MetaSchema
|
||
description: MetaSchema 定义、版本、草稿、校验、影响预览、发布、激活、回滚、废弃、灰度
|
||
- name: Governance / ProtectionNode
|
||
description: 保护节点注册表、详情和 Shadow→Canonical 边界
|
||
- name: Governance / FunctionChain
|
||
description: 系统功能链路、影响预览和版本激活
|