Bundle API

BundleCommandController、DefinitionCommandController、DefinitionQueryController、DefinitionWorkspaceController、AggregateCommandController、AggregateQueryController 提供定义资源的写入、查询与聚合操作入口，路径前缀均为 /api/v1/definitions。包编辑/安装接口由 PackageCommandController、PackageEditController 提供，前缀为 /api/v1/packages。

Bundle 规格字段

DefinitionBundleSpec 除 metadata / options 外，还承载以下资源集合：

字段	类型	说明
`objectTypes`	List<ObjectTypeSpecDTO>	对象类型定义列表
`objectTypeProperties`	List<ObjectTypePropertiesSpecDTO>	属性定义列表，按对象聚合
`links`	List<LinkTypeSpecDTO>	关联类型定义列表
`metrics`	List<MetricSpecDTO>	指标定义列表
`actions`	List<ActionSpecDTO>	动作定义列表
`policies`	List<AccessPolicySpecDTO>	访问策略定义列表
`pageViews`	List<PageViewSpecDTO>	页面视图定义列表
`apps`	List<AppSpecDTO>	应用壳定义列表
`datasources`	List<DataSourceSpecDTO>	数据源定义列表
`datasets`	List<DatasetSpecDTO>	数据集定义列表
`pipelines`	List<PipelineSpecDTO>	管道定义列表
`workflows`	List<WorkflowSpecDTO>	工作流定义列表
`analysisPlans`	List<AnalysisPlanSpecDTO>	分析计划定义列表
`collectorScripts`	List<CollectorScriptSpecDTO>	采集脚本列表（import 阶段安装）
`collectorTasks`	List<CollectorTaskSpecDTO>	采集任务列表（finalize 阶段安装）
`seedData`	List<SeedDataEntryDTO>	样本数据列表（finalize 阶段导入）
`workspaceConfig`	WorkspaceConfigSpecDTO	Workspace 配置（至多一份）
`installPlan`	List<InstallStepDTO>	安装执行计划（编译期生成，随 validate/import 响应返回）

请求/响应 DTO

BundleApplyReqDTO / BundleDryRunReqDTO

字段	类型	说明
`bundle`	DefinitionBundleSpec	统一 Definition Bundle 规格

DefinitionBundleOptions

字段	类型	说明
`dryRun`	boolean	是否仅试运行
`continueOnError`	boolean	出错时是否继续
`skipExisting`	boolean	是否跳过已存在资源
`defaultPublishOnInstall`	boolean	bundle 级默认发布策略；ObjectType 未显式声明 `publishOnInstall` 时继承该默认值
`materializeAfterApply`	boolean	bundle apply 后是否自动物化 ObjectType
`syncMode`	DefinitionBundleSyncModeEnum	同步模式：`UPSERT` 或 `REPLACE`
`pruneMissingResources`	boolean	显式删除本包管理但当前未声明的资源；`true` 等效于 `REPLACE`
`workspaceStrategy`	string	workspace 定位策略：`CURRENT`（默认）/ `ENSURE_NAMED`
`forceDefaultStorage`	boolean	为 true 时强制覆盖 workspace 已有默认存储

Bundle 附属资源 DTO

CollectorScriptSpecDTO

字段	类型	说明
`name`	string	脚本名（workspace 内自然键）
`displayName`	string	显示名
`description`	string	描述
`targetUrl`	string	目标站点 URL
`trace`	Map<String, Object>	TraceV3 动作树（`version=3`）
`extractors`	List<Map<String, Object>>	提取器定义（`ExtractorSpec[]`）
`transformBindings`	Map<String, String>	转换绑定（extractor 名 → workflow naturalKey）
`debugEvidence`	Map<String, Object>	调试证据
`status`	string	生命周期状态

CollectorTaskSpecDTO

字段	类型	说明
`name`	string	任务名（workspace 内自然键）
`displayName`	string	显示名
`scriptRef`	string	引用的采集脚本名（`CollectorScript.name`）
`device`	string	设备 label；未配对时任务延期安装
`paramBindings`	Map<String, Object>	参数绑定
`timeoutSeconds`	integer	单次运行超时（秒）
`captureDebug`	boolean	是否采集调试证据
`screenshot`	boolean	是否截图
`retentionRuns`	integer	原始请求留存份数
`alertHook`	Map<String, Object>	告警钩子配置
`status`	string	任务状态
`cronExpression`	string	定时调度 cron 表达式（5/6 段均支持）
`scheduleEnabled`	boolean	是否启用定时调度

SeedDataEntryDTO

字段	类型	说明
`objectName`	string	对象 API 名称
`primaryKeyProperty`	string	对象主键属性 API 名称；缺省回落对象 `spec.primaryKey`
`records`	List<Map<String, Object>>	记录列表（属性 API 名 → 值）

WorkspaceConfigSpecDTO

字段	类型	说明
`description`	string	工作空间描述（仅现值为空时回填）
`defaultStorage`	DefaultStorageSpec	默认存储绑定意图
`models`	List<LlmModelTemplateDTO>	LLM 模型模板（按 id upsert）
`agentHarness`	AgentHarnessConfigDTO	Agent Harness 定制
`semanticAskSuggestions`	List<String>	提问建议（append + 去重）

DefaultStorageSpec：adopt（安装后是否绑定默认存储）、dataSourceRef（目标数据源名）。

LlmModelTemplateDTO：id、model、provider、displayName、baseUrl、apiKey（仅允许 ${ENV:VAR} 占位符或空）、temperature、timeoutSeconds、supportsJsonSchema、contextLength。

AgentHarnessConfigDTO：promptSuffix、customProfiles（List<Map<String, Object>>）、profileOverrides（List<Map<String, Object>>）。

InstallStepDTO

字段	类型	说明
`id`	string	步骤 id（计划内唯一）
`action`	string	动作：`import` / `runPipelines` / `finalize`
`pipelines`	List<String>	`action=runPipelines` 时本批运行的管道名
`phase`	string	phase 标签：`AFTER_IMPORT` / `AFTER_ONTOLOGY`

BundleApplyRespDTO

字段	类型	说明
`applied`	boolean	是否已应用（dry-run 为 false）
`results`	List<MutationResultDTO>	各资源变更结果
`message`	string	汇总消息
`createCount`	integer	创建数量
`updateCount`	integer	更新数量
`unchangedCount`	integer	无变化数量
`deleteCount`	integer	删除数量
`blockedCount`	integer	被阻止数量

MutationResultDTO

所有 Definition API 写入操作（save / sync / bundle apply / dry-run）均返回此结构，作为 CLI install、FE authoring 与模块内部写入服务的统一反馈契约。

字段	类型	说明
`resourceType`	string	资源类型，例如 ObjectType / Property / LinkType / Metric / Action / AccessPolicy
`naturalKey`	string	自然键，资源在定义域内的稳定标识，例如对象名、属性 apiName
`resourceId`	string	平台分配的资源 ID
`action`	MutationActionEnum	变更动作：CREATED / UPDATED / UNCHANGED / DELETED / RESTORED / BLOCKED
`status`	MutationResultStatusEnum	阶段状态：APPLIED / STAGED / MATERIALIZED / PUBLISHED / SKIPPED_NOT_MATERIALIZED / FAILED
`changedFields`	List<string>	发生变化的字段列表
`warnings`	List<string>	变更警告，例如字段降级、引用未来得及解析
`message`	string	变更说明或错误信息
`version`	long	写入后的定义版本号
`definitionDeleted`	boolean	PR-071：定义层是否会被删除
`runtimeDeletes`	List<string>	PR-071：运行态将被删除的资源标识列表（resourceType:naturalKey）
`schemaDeletedColumns`	List<string>	PR-071：schema 层面将被 soft drop 的列名列表
`hardDropEnabled`	boolean	PR-071：是否启用了物理删列（hard drop）

DefinitionSaveReqDTO

字段	类型	说明
`spec`	object	资源 spec，结构由 resourceType 决定

PropertySyncReqDTO

Property 删除可通过 mode = REPLACE 或 /object-types/{objectName}/properties/{propertyApiName}:remove 完成。

字段	类型	说明
`mode`	PropertySyncMode	同步模式：`MERGE` 合并，`REPLACE` 全量替换
`properties`	List<PropertySpecDTO>	属性规格列表

DefinitionPublishReqDTO

字段	类型	说明
`version`	long	要发布的版本号，留空表示发布最新草稿版本
`dryRun`	boolean	是否仅预演，不实际发布到运行态

说明：发布 API 只暴露统一 lifecycle contract。bundle 路径若需要在安装后推进运行态，只通过 DefinitionBundleOptions.defaultPublishOnInstall 与 ObjectType 级 publishOnInstall 做默认策略补齐，不再对外暴露独立的 bundle/materialize 编排开关。

DefinitionSaveVersionReqDTO

将当前草稿显式固化为一个新的不可变草稿版本，不影响 runtime。

字段	类型	说明
`reason`	string	保存原因
`changeSummary`	string	变更摘要

DefinitionRollbackReqDTO

字段	类型	说明
`targetVersion`	long	目标版本号（必填）
`reason`	string	回滚原因
`dryRun`	boolean	是否仅预演，不实际回滚

DefinitionRestoreDraftReqDTO

将某个历史版本的 spec 恢复为新的当前草稿，不影响 runtime。

字段	类型	说明
`targetVersion`	long	目标版本号（必填）
`reason`	string	恢复原因
`dryRun`	boolean	是否仅预演，不实际恢复

DefinitionRollbackPublishedReqDTO

将某个已发布历史版本重新发布到 runtime，影响运行态。

字段	类型	说明
`releaseSnapshotId`	string	目标 Release Snapshot ID（优先使用）
`targetVersion`	long	目标版本号（兼容字段，未提供 releaseSnapshotId 时使用）
`reason`	string	回滚原因
`dryRun`	boolean	是否仅预演，不实际回滚

DefinitionDiffReqDTO

字段	类型	说明
`fromVersion`	long	源版本号，留空表示当前最新版本
`targetVersion`	long	目标版本号（必填）

ObjectTypeAggregateRollbackReqDTO

字段	类型	说明
`targetVersion`	long	指定要恢复的聚合历史版本号；为空时回到各成员当前已发布版本
`reason`	string	回滚原因
`dryRun`	boolean	是否仅预演，不实际回滚

DefinitionApplyRespDTO

字段	类型	说明
`result`	MutationResultDTO	变更结果
`previousLatestVersion`	long	apply 前 latest version
`previousPublishedVersion`	long	apply 前 published version
`appliedVersion`	long	本次 apply 产生的 version；无草稿时可等于已有 latest version

DefinitionPublishRespDTO

字段	类型	说明
`result`	MutationResultDTO	发布结果
`previousPublishedVersion`	long	发布前已发布版本号
`publishedVersion`	long	发布后已发布版本号（兼容字段，同 targetVersion）
`targetVersion`	long	目标 Resource Revision 版本号
`releaseSnapshotId`	string	生成的 Release Snapshot ID
`preview`	DefinitionDiffRespDTO	dryRun 时的 diff 预览
`materializePlan`	List<string>	物化计划摘要
`impactedRuntimeResources`	List<string>	受影响的运行态资源
`warnings`	List<string>	发布警告信息
`publishResult`	DefinitionPublishResultDTO	发布执行结果明细（commit 后填充）

DefinitionPublishResultDTO

字段	类型	说明
`resourceType`	DefinitionResourceTypeEnum	资源类型
`naturalKey`	string	资源自然键
`status`	Status	执行状态：`SUCCEEDED` / `FAILED` / `SKIPPED`
`publishedVersion`	long	发布到的版本号
`publishedAt`	LocalDateTime	发布完成时间
`message`	string	成功提示或失败原因
`errors`	List<string>	失败的详细错误信息

DefinitionSaveVersionRespDTO

字段	类型	说明
`result`	MutationResultDTO	变更结果
`unchanged`	boolean	是否未发生变化（幂等返回）
`version`	long	生成的版本号
`versionIntent`	DefinitionVersionIntentEnum	版本意图
`versionMetadata`	DefinitionResourceVersionDTO	版本元信息
`createdAt`	LocalDateTime	创建时间
`createdBy`	string	创建人

DefinitionRollbackRespDTO

字段	类型	说明
`result`	MutationResultDTO	变更结果
`rolledBackFromVersion`	long	回滚前版本号
`rolledBackToVersion`	long	回滚目标版本号
`version`	long	回滚后产生的新版本号
`preview`	DefinitionDiffRespDTO	dryRun 时的 diff 预览

DefinitionRestoreDraftRespDTO

字段	类型	说明
`result`	MutationResultDTO	变更结果
`rolledBackFromVersion`	long	恢复前版本号
`rolledBackToVersion`	long	恢复目标版本号
`newDraftVersion`	DefinitionResourceVersionDTO	恢复后产生的新草稿版本
`preview`	DefinitionDiffRespDTO	dryRun 时的 diff 预览

DefinitionRollbackPublishedRespDTO

字段	类型	说明
`result`	MutationResultDTO	变更结果
`rolledBackFromPublishedVersion`	long	回滚前已发布版本号
`rolledBackToPublishedVersion`	long	回滚目标已发布版本号
`publishedVersion`	long	回滚后当前已发布版本号
`releaseSnapshotId`	string	生成的 Release Snapshot ID（回滚类型）
`preview`	DefinitionDiffRespDTO	dryRun 时的 diff 预览

DefinitionDiffRespDTO

字段	类型	说明
`fromVersion`	long	源版本号
`toVersion`	long	目标版本号
`addedFields`	List<string>	新增的字段路径（兼容字段，已 `@Deprecated`）
`removedFields`	List<string>	删除的字段路径（兼容字段，已 `@Deprecated`）
`modifiedFields`	List<string>	修改的字段路径（兼容字段，已 `@Deprecated`）
`changedFields`	List<string>	所有发生变更的字段路径（兼容字段，已 `@Deprecated`）
`semanticChangedFields`	List<string>	定义语义变化字段路径
`physicalChangedFields`	List<string>	物理映射变化字段路径
`schemaPlan`	MaterializationPlanDTO	DDL / Schema 计划，仅 MANAGED 对象发布预览时填充
`summaryItems`	List<string>	中文业务变化摘要
`warnings`	List<string>	变更警告，例如字段移除或关键字段变更
`specPreview`	object	目标版本的完整 Spec 对象

ObjectTypeAggregateApplyRespDTO

字段	类型	说明
`objectName`	string	ObjectType 名称
`results`	List<MutationResultDTO>	成员 apply 结果

ObjectTypeAggregateMaterializeRespDTO

字段	类型	说明
`objectName`	string	ObjectType 名称
`materialized`	boolean	是否已完成物化

ObjectTypeAggregateSnapshotDetailRespDTO

字段	类型	说明
`objectName`	string	对象名称
`snapshot`	ObjectTypeAggregateSnapshotDTO	快照信息
`currentReleaseSnapshotId` / `currentReleaseSnapshotSequence`	string / long	当前生效的发布快照及序号
`currentDraftSnapshotId` / `currentDraftSnapshotSequence`	string / long	当前草稿快照及序号
`baseReleaseSnapshotId`	string	当前草稿所基于的发布快照 ID
`aggregateLifecycleStatus`	ObjectTypeAggregateLifecycleStatusEnum	聚合生命周期状态
`currentRelease` / `currentDraft`	boolean	是否当前发布/草稿
`sourceDraftSnapshotId` / `rollbackFromSnapshotId`	string	来源草稿快照/回滚来源快照
`members`	List<MemberRefDTO>	兼容字段（已 `@Deprecated`）
`fullMembers`	List<MemberRefDTO>	完整成员清单
`deltaMembers`	List<DeltaMemberRefDTO>	相对上一检查点的变化成员
`warnings`	List<String>	聚合级警告

DeltaMemberRefDTO：changeType（ADDED / MODIFIED / REMOVED / UNCHANGED）、resourceType、naturalKey、ownerScope、resourceVersion、previousResourceVersion。

ObjectTypeAggregatePublishRespDTO

字段	类型	说明
`objectName`	string	ObjectType 名称
`results`	List<DefinitionPublishRespDTO>	成员 publish 结果
`warnings`	List<string>	聚合级警告
`materializationPlan`	MaterializationPlanDTO	物化计划

ObjectTypeAggregateRollbackRespDTO

字段	类型	说明
`objectName`	string	ObjectType 名称
`results`	List<DefinitionRollbackRespDTO>	成员 rollback 结果
`warnings`	List<string>	聚合级警告

ObjectTypeAggregateCompareRespDTO

字段	类型	说明
`objectName`	string	ObjectType 名称
`items`	List<ObjectTypeAggregateCompareItemDTO>	成员 compare 结果
`warnings`	List<string>	聚合级警告

ObjectTypeAggregateCompareItemDTO

字段	类型	说明
`resourceType`	DefinitionResourceTypeEnum	资源类型
`naturalKey`	string	自然键
`diff`	DefinitionDiffRespDTO	成员 diff

ObjectTypeAggregateSaveVersionRespDTO

字段	类型	说明
`objectName`	string	ObjectType 名称
`aggregateSnapshotId`	string	聚合草稿快照 ID
`results`	List<DefinitionSaveVersionRespDTO>	成员保存版本结果
`affectedMembers`	List<AggregateRevisionRefDTO>	本次快照影响的成员引用
`createdRevisionRefs`	List<AggregateRevisionRefDTO>	本次为变更成员创建的 Resource Revision 引用

AggregateRevisionRefDTO

字段	类型	说明
`resourceType`	string	资源类型
`naturalKey`	string	自然键
`ownerScope`	string	成员所属作用域
`resourceVersion`	long	Resource Revision 版本号

ObjectTypeAggregateHistoryRespDTO

字段	类型	说明
`objectName`	string	ObjectType 名称
`entries`	List<ObjectTypeAggregateHistoryEntryDTO>	聚合历史条目

ObjectTypeAggregateHistoryEntryDTO

字段	类型	说明
`resourceType`	DefinitionResourceTypeEnum	资源类型
`naturalKey`	string	自然键
`ownerObjectName`	string	所属对象名（PROPERTY 等子资源时存在）
`version`	long	版本号
`changeSummary`	string	变更摘要
`createdBy`	string	创建人
`createdAt`	LocalDateTime	创建时间
`current`	boolean	是否为当前版本
`published`	boolean	是否为已发布版本

ObjectTypeAggregateSnapshotListRespDTO

字段	类型	说明
`objectName`	string	ObjectType 名称
`snapshots`	List<ObjectTypeAggregateSnapshotDTO>	聚合快照列表（按创建时间倒序）

ObjectTypeAggregateSnapshotDTO

字段	类型	说明
`id`	string	快照 ID
`snapshotKind`	string	快照类型：`DRAFT` / `RELEASE`
`aggregateType`	string	聚合类型，如 OBJECT_TYPE
`aggregateKey`	string	聚合自然键，如 ObjectType 名称
`changeSummary`	string	变更摘要（Draft Snapshot）
`reason`	string	发布原因（Release Snapshot）
`sourceSnapshotId`	string	来源 Draft Snapshot ID（Release Snapshot 指向其来源）
`createdBy`	string	创建人
`createdAt`	LocalDateTime	创建时间
`members`	List<MemberRefDTO>	快照包含的成员 Revision 引用

MemberRefDTO

字段	类型	说明
`resourceType`	string	资源类型
`naturalKey`	string	自然键
`ownerScope`	string	成员所属作用域
`resourceVersion`	long	Resource Revision 版本号

ObjectTypeAggregateViewRespDTO

字段	类型	说明
`objectName`	string	对象名称
`latestVersion`	long	聚合最新版本
`publishedVersion`	long	聚合已发布版本
`draftState`	DefinitionDraftStateEnum	聚合草稿状态
`hasUnpublishedChanges`	boolean	是否存在未发布变更
`projectionStatus`	DefinitionProjectionStatusEnum	投影状态
`lastPublishError`	string	最近发布错误
`lastPublishedAt`	LocalDateTime	最近发布时间
`lastPublishedBy`	string	最近发布人
`members`	List<ObjectTypeAggregateMemberRespDTO>	聚合成员
`datasetBindingMode`	DatasetBindingModeEnum	主数据集绑定模式：`EXTERNAL` 外部映射 / `MANAGED` 平台托管

ObjectTypeAggregateMemberRespDTO

字段	类型	说明
`resourceType`	DefinitionResourceTypeEnum	资源类型
`naturalKey`	string	自然键
`scope`	ResourceScopeDTO	资源作用域
`latestVersion`	long	最新版本
`publishedVersion`	long	已发布版本
`draftState`	DefinitionDraftStateEnum	草稿状态
`hasUnpublishedChanges`	boolean	是否存在未发布变更

接口列表

Bundle

方法	路径	请求体	响应	说明
POST	`/api/v1/definitions/bundles:dry-run`	BundleDryRunReqDTO	BundleApplyRespDTO	Bundle 试运行，返回变更预览
POST	`/api/v1/definitions/bundles:apply`	BundleApplyReqDTO	BundleApplyRespDTO	Bundle 应用，执行实际写入

单一资源保存

通用路径 /api/v1/definitions/resources/{resourceType}/{naturalKey}:save 兼容所有资源类型，请求体为 DefinitionSaveReqDTO，并支持通过查询参数补充作用域：

查询参数	说明
`ownerObjectName`	归属对象名（PROPERTY / ACTION / METRIC / ACCESS_POLICY）
`sourceObjectName`	源对象名（LINK_TYPE）
`targetObjectName`	目标对象名（LINK_TYPE）

各资源类型的具体保存路径如下：

方法	路径	请求体	说明
POST	`/api/v1/definitions/resources/{resourceType}/{naturalKey}:save`	DefinitionSaveReqDTO	保存定义资源草稿（兼容层）
POST	`/api/v1/definitions/object-types/{objectName}:save`	ObjectTypeSpecDTO	保存对象类型定义草稿
POST	`/api/v1/definitions/workflows/{name}:save`	WorkflowSpecDTO	保存工作流定义草稿
POST	`/api/v1/definitions/apps/{name}:save`	AppSpecDTO	保存应用定义草稿
POST	`/api/v1/definitions/page-views/{name}:save`	PageViewSpecDTO	保存页面视图定义草稿
POST	`/api/v1/definitions/datasets/{name}:save`	DatasetSpecDTO	保存数据集定义草稿
POST	`/api/v1/definitions/data-sources/{name}:save`	DataSourceSpecDTO	保存数据源定义草稿
POST	`/api/v1/definitions/pipelines/{name}:save`	PipelineSpecDTO	保存流水线定义草稿
POST	`/api/v1/definitions/access-policies/{name}:save`	AccessPolicySpecDTO	保存访问策略定义草稿
POST	`/api/v1/definitions/analysis-plans/{name}:save`	AnalysisPlanSpecDTO	保存分析计划定义草稿
POST	`/api/v1/definitions/object-types/{objectName}/properties/{apiName}:save`	PropertySpecDTO	保存对象属性定义草稿
POST	`/api/v1/definitions/link-types/{name}:save`	LinkTypeSpecDTO	保存关联类型定义草稿
POST	`/api/v1/definitions/actions/{name}:save`	ActionSpecDTO	保存动作定义草稿
POST	`/api/v1/definitions/metrics/{apiName}:save`	MetricSpecDTO	保存指标定义草稿

包编辑与安装

PackageCommandController 与 PackageEditController 提供包级校验、导入、编辑与安装接口：

方法	路径	说明
POST	`/api/v1/packages:validate`	校验已编译包
POST	`/api/v1/packages:validate-yaml`	校验 YAML 包
POST	`/api/v1/packages:import`	导入已编译包
POST	`/api/v1/packages:import-yaml`	导入 YAML 包
POST	`/api/v1/packages/{slug}:finalize`	完成包安装
GET	`/api/v1/packages/{slug}/edit-files`	列出包编辑文件
GET	`/api/v1/packages/edit-files`	自动解析当前 workspace 包并列出编辑文件
GET	`/api/v1/packages/{slug}/edit-files/file`	读取文件
POST	`/api/v1/packages/{slug}/edit-files:batch-get`	批量读取文件
PUT	`/api/v1/packages/{slug}/edit-files/file`	写入文件
POST	`/api/v1/packages/{slug}/edit-files/file:edit`	编辑文件
DELETE	`/api/v1/packages/{slug}/edit-files/file`	删除文件
POST	`/api/v1/packages/{slug}:validate-edit`	校验编辑后的包
POST	`/api/v1/packages/{slug}:install`	安装基线
POST	`/api/v1/packages/{slug}:install-file`	安装单个文件
POST	`/api/v1/packages/{slug}:reverse-generate`	反向生成包文件
POST	`/api/v1/packages/workspace-baseline:adopt`	采纳当前 workspace 为基线
POST	`/api/v1/packages/workspace-baseline:reset-baseline`	重置 workspace 基线

属性同步与下线

方法	路径	请求体	响应	说明
POST	`/api/v1/definitions/object-types/{objectName}/properties:sync`	PropertySyncReqDTO	List<MutationResultDTO>	同步对象属性
POST	`/api/v1/definitions/object-types/{objectName}/properties/{propertyApiName}:remove`	-	boolean	下线对象属性
POST	`/api/v1/definitions/object-types/{objectName}/properties/{propertyApiName}:restore`	-	boolean	恢复已下线对象属性

Workspace 级编排

方法	路径	请求体	响应	说明
GET	`/api/v1/definitions/workspace-changes`	-	WorkspaceChangesRespDTO	查询工作区未发布变更
POST	`/api/v1/definitions/workspace:apply`	WorkspaceApplyReqDTO（可选）	WorkspaceApplyRespDTO	对工作区目标集合执行 apply
POST	`/api/v1/definitions/workspace:publish-preview`	WorkspacePublishReqDTO（可选）	WorkspacePublishRespDTO	预演工作区批量发布
POST	`/api/v1/definitions/workspace:publish`	WorkspacePublishReqDTO（可选）	WorkspacePublishRespDTO	执行工作区批量发布
POST	`/api/v1/definitions/workspace:rollback`	WorkspaceRollbackReqDTO（可选）	WorkspaceRollbackRespDTO	回滚工作区目标集合到各自已发布版本
POST	`/api/v1/definitions/workspace:compare`	WorkspaceCompareReqDTO（可选）	WorkspaceCompareRespDTO	比较工作区目标集合的未发布差异

Workspace 响应统一为 items + warnings 结构；WorkspaceChangesRespDTO 仅含 items（WorkspaceChangeItemDTO）。

Workspace 请求 DTO：WorkspaceApplyReqDTO / WorkspacePublishReqDTO / WorkspaceCompareReqDTO 均含 targets: List<WorkspaceDefinitionTargetDTO>（为空表示对当前工作区所有未发布变更生效）；WorkspaceRollbackReqDTO 另含 reason / dryRun。WorkspaceDefinitionTargetDTO 字段为 resourceType / naturalKey。

ObjectType 聚合操作

方法	路径	请求体	响应	说明
POST	`/api/v1/definitions/object-types/{objectName}:apply`	-	ObjectTypeAggregateApplyRespDTO	聚合 apply ObjectType 及其子资源
POST	`/api/v1/definitions/object-types/{objectName}:materialize`	-	ObjectTypeAggregateMaterializeRespDTO	聚合物化 ObjectType 及其子资源
POST	`/api/v1/definitions/object-types/{objectName}:publish-preview`	DefinitionPublishReqDTO	ObjectTypeAggregatePublishRespDTO	聚合预览发布 ObjectType 及其子资源
POST	`/api/v1/definitions/object-types/{objectName}:publish`	DefinitionPublishReqDTO	ObjectTypeAggregatePublishRespDTO	聚合发布 ObjectType 及其子资源
POST	`/api/v1/definitions/object-types/{objectName}:rollback`	ObjectTypeAggregateRollbackReqDTO	ObjectTypeAggregateRollbackRespDTO	聚合回滚 ObjectType 及其子资源到各自已发布版本
POST	`/api/v1/definitions/object-types/{objectName}:compare`	-	ObjectTypeAggregateCompareRespDTO	聚合比较 ObjectType 及其子资源的未发布差异
POST	`/api/v1/definitions/object-types/{objectName}:save-version`	DefinitionSaveVersionReqDTO	ObjectTypeAggregateSaveVersionRespDTO	聚合保存 ObjectType 及其子资源草稿版本

单资源版本管理

以下接口统一作用于 /api/v1/definitions/resources/{resourceType}/{naturalKey}，均支持通过查询参数 ownerObjectName、sourceObjectName、targetObjectName 补充作用域：

方法	路径	请求体	响应	说明
POST	`/api/v1/definitions/resources/{resourceType}/{naturalKey}:save-version`	DefinitionSaveVersionReqDTO	DefinitionSaveVersionRespDTO	将当前草稿保存为新的草稿版本
POST	`/api/v1/definitions/resources/{resourceType}/{naturalKey}:apply`	-	DefinitionApplyRespDTO	固化定义资源草稿为版本
POST	`/api/v1/definitions/resources/{resourceType}/{naturalKey}:publish-preview`	DefinitionPublishReqDTO	DefinitionPublishRespDTO	预览定义资源发布影响
POST	`/api/v1/definitions/resources/{resourceType}/{naturalKey}:publish`	DefinitionPublishReqDTO	DefinitionPublishRespDTO	发布定义资源到运行态
POST	`/api/v1/definitions/resources/{resourceType}/{naturalKey}:rollback`	DefinitionRollbackReqDTO	DefinitionRollbackRespDTO	回滚定义资源到指定版本（兼容入口，建议分别使用 restore-draft / rollback-published）
POST	`/api/v1/definitions/resources/{resourceType}/{naturalKey}:restore-draft`	DefinitionRestoreDraftReqDTO	DefinitionRestoreDraftRespDTO	恢复草稿到指定历史版本
POST	`/api/v1/definitions/resources/{resourceType}/{naturalKey}:rollback-published`	DefinitionRollbackPublishedReqDTO	DefinitionRollbackPublishedRespDTO	将已发布运行态回滚到指定已发布版本
POST	`/api/v1/definitions/resources/{resourceType}/{naturalKey}:compare`	DefinitionDiffReqDTO	DefinitionDiffRespDTO	对比定义资源两个版本的差异
DELETE	`/api/v1/definitions/resources/{resourceType}/{naturalKey}`	-	MutationResultDTO	删除单资源

资源查询

方法	路径	查询参数	响应	说明
GET	`/api/v1/definitions/resources`	resourceType, current, size, keyword, status, objectName	PageVO<DefinitionResourceSummaryDTO>	分页查询定义资源
GET	`/api/v1/definitions/resources/{resourceType}/{naturalKey}`	ownerObjectName, sourceObjectName, targetObjectName	DefinitionResourceDetailDTO	获取定义资源详情
GET	`/api/v1/definitions/resources/{resourceType}/{naturalKey}/typed`	ownerObjectName, sourceObjectName, targetObjectName	DefinitionResourceDetailDTO<CanonicalSpec>	获取定义资源详情（spec 强类型）
GET	`/api/v1/definitions/resources/{resourceType}/{naturalKey}/versions`	ownerObjectName, sourceObjectName, targetObjectName, line	List<DefinitionResourceVersionDTO>	查询定义资源版本历史
GET	`/api/v1/definitions/resources/{resourceType}/{naturalKey}/versions/{version}`	ownerObjectName, sourceObjectName, targetObjectName	DefinitionResourceDetailDTO	获取指定版本详情
GET	`/api/v1/definitions/resources/{resourceType}/{naturalKey}/versions/{version}/typed`	ownerObjectName, sourceObjectName, targetObjectName	DefinitionResourceDetailDTO<CanonicalSpec>	获取指定版本详情（spec 强类型）
GET	`/api/v1/definitions/resources/{resourceType}/{naturalKey}/release-snapshots`	ownerObjectName, sourceObjectName, targetObjectName	List<DefinitionReleaseSnapshotDTO>	查询定义资源 Release Snapshot 历史
GET	`/api/v1/definitions/object-types/{name}/spec`	-	ObjectTypeSpecDTO	获取对象类型最新 Spec
GET	`/api/v1/definitions/object-types/{name}/history`	-	ObjectTypeAggregateHistoryRespDTO	获取对象类型聚合历史
GET	`/api/v1/definitions/object-types/{name}/snapshots`	-	ObjectTypeAggregateSnapshotListRespDTO	获取对象类型聚合快照历史
GET	`/api/v1/definitions/object-types/{name}/snapshots/{snapshotId}`	-	ObjectTypeAggregateSnapshotDetailRespDTO	获取对象类型聚合快照详情
GET	`/api/v1/definitions/object-types/{name}/aggregate-view`	-	ObjectTypeAggregateViewRespDTO	获取对象类型聚合视图

查询参数说明

参数	类型	说明
`resourceType`	string	资源类型，如 OBJECT_TYPE、PROPERTY、LINK_TYPE 等
`current`	long	分页当前页，默认 1
`size`	long	分页大小，默认 20
`keyword`	string	关键字过滤
`status`	string	状态过滤
`objectName`	string	对象名过滤
`line`	DefinitionHistoryLineEnum	版本历史线，默认 `ALL`
`ownerObjectName`	string	归属对象名
`sourceObjectName`	string	源对象名
`targetObjectName`	string	目标对象名