Definition Spec — 核心概念

本文档按后端 foundry-definition-spec-api 当前实际 DTO，梳理 Canonical Spec 的核心概念与跨资源协议，是各资源文档的公共基础。

1. 定位与目标

foundry-definition-spec 是平台统一的定义侧规格协议层，目标包括：

• 为 CLI、前端 Authoring、模块间调用提供同一份 canonical spec 输入协议。
• 将 ObjectType、Property、LinkType、Metric、Action、AccessPolicy、PageView、App、Workflow、Dataset、DataSource、Pipeline、AnalysisPlan 等定义资源纳入统一 bundle 管理。
• 通过 DefinitionResource / DefinitionResourceVersion / DefinitionReleaseSnapshot 支持版本化、幂等写入、dry-run、发布与回滚。
• 隔离定义语义（spec）与运行态字段（id、status、physical column state 等），避免安装/升级逻辑泄露底层实现细节。

2. 模块结构

be/foundry-definition-spec/
├── foundry-definition-spec-api/        # DTO / Enum / Projection 接口 / SpecReader
│   └── src/main/java/com/loambase/foundry/definition/spec/
│       ├── dto/                        # 资源规格 DTO
│       ├── dto/request/                # Upsert / Sync / Bundle 请求
│       ├── dto/response/               # Bundle / Workspace 响应
│       ├── enums/                      # 枚举
│       ├── projection/                 # 领域投影处理器接口
│       ├── result/                     # 变更结果 DTO
│       ├── api/                        # 跨模块读取 spec 的接口
│       └── vo/                         # 查询返回 VO

3. CanonicalSpec

所有定义资源规格 DTO 的共同父接口，用于在 bundle、installer、OpenAPI 与 SDK 之间统一输入协议。

public interface CanonicalSpec {
}

当前实现类包括：

• ObjectTypeSpecDTO
• ObjectTypePropertiesSpecDTO
• PropertySpecDTO
• LinkTypeSpecDTO
• MetricSpecDTO
• ActionSpecDTO
• AccessPolicySpecDTO
• PageViewSpecDTO
• AppSpecDTO
• DataSourceSpecDTO
• DatasetSpecDTO
• PipelineSpecDTO
• WorkflowSpecDTO
• AnalysisPlanSpecDTO
• SeedDataSpecDTO（种子数据规格；Bundle 的 seedData 使用 SeedDataEntryDTO，本 DTO 用于通用 canonical 入口）
• MapSpecDTO（未知 kind 的通用兜底，以原始 Map 承载）

4. ResourceRefDTO

跨资源引用的统一方式。kind 标识资源类型，name 为自然键，apiName 用于需要区分显示名与 API 名的场景（解析不到 name 时回退为 id）。

约定：manifest 中允许使用 object: Xxx 等简写，安装器 adapter 会将其转换为 objectRef: { kind: ObjectType, name: Xxx }。

5. ResourceLocatorDTO / ResourceScopeDTO

DefinitionCommandController 与 DefinitionQueryController 使用 ResourceLocatorDTO 定位一个定义资源；ResourceScopeDTO 表达资源在自然键之外的作用域维度（所属对象、源对象、目标对象）。

5.1 ResourceLocatorDTO

5.2 ResourceScopeDTO

6. DefinitionBundleSpec

CLI install 将 authoring manifest 编译为 DefinitionBundleSpec 后，通过 /definitions/bundles:dry-run 或 apply 提交；FE authoring 也可将多资源保存编排为此结构批量提交。

6.1 DefinitionBundleMetadata

6.2 DefinitionBundleOptions

syncMode 取值说明：

• UPSERT：仅对传入资源做 upsert，不删除未出现的资源。
• REPLACE：以传入资源集合为目标状态，缺失且由本包管理的资源执行删除。

当 syncMode 为空时，pruneMissingResources = true 等效于 REPLACE。

7. 投影框架

7.1 设计意图

• 每个资源类型一个 DomainProjectionHandler，避免大一统接口暴露不相关方法。
• Property 因具备集合语义（MERGE / REPLACE），单独暴露 PropertyProjectionHandler#syncProperties。
• ProjectionContext 封装一次投影调用所需的元数据，为回滚、重放、幂等、审计预留扩展点。

7.2 ProjectionContext

7.3 ProjectionMode

7.4 DomainProjectionHandler

public interface DomainProjectionHandler<T> {
    DefinitionResourceTypeEnum resourceType();
    MutationResultDTO project(ProjectionContext context, T spec);
 
    default MutationResultDTO delete(ProjectionContext context) {
        // 默认返回“未支持”的结果；具体资源类型可选择覆盖，返回 runtime 侧是否已清理
    }
}

7.5 PropertyProjectionHandler

public interface PropertyProjectionHandler {
    default DefinitionResourceTypeEnum resourceType() {
        return DefinitionResourceTypeEnum.PROPERTY;
    }
    List<MutationResultDTO> syncProperties(
        ProjectionContext context,
        String objectNaturalKey,
        List<PropertySpecDTO> properties,
        PropertySyncMode mode
    );
}

8. DefinitionResourceSpecReader

跨模块读取 Definition 层 spec 的接口，位于 com.loambase.foundry.definition.spec.api 包，由 definition-biz 实现。其他业务模块只需依赖 spec-api 即可注入使用，避免直接依赖 definition-biz。

public interface DefinitionResourceSpecReader {
    <T> Optional<T> getLatestSpec(String workspaceId, String resourceType, String naturalKey, Class<T> specClass);
    <T> Optional<T> getPublishedSpec(String workspaceId, String resourceType, String naturalKey, Class<T> specClass);
    <T> Optional<T> getVersionSpec(String workspaceId, String resourceType, String naturalKey, long version, Class<T> specClass);
    <T> Optional<T> getSpecByVersionId(String versionId, Class<T> specClass);
 
    // WORKFLOW 快捷方法
    Optional<WorkflowSpecDTO> getWorkflowSpec(String workspaceId, String naturalKey);
    Optional<WorkflowSpecDTO> getPublishedWorkflowSpec(String workspaceId, String naturalKey);
    Optional<WorkflowSpecDTO> getWorkflowVersionSpec(String workspaceId, String naturalKey, long version);
}

9. 关键约束

1. 定义语义 vs 运行态字段：Spec DTO 只应包含定义语义，禁止将运行态字段（如 id、currentPublishedVersionId、datasetColumnName、physicalColumnState）写入 canonical spec。
2. 自然键设计：ObjectType / LinkType / Metric / AccessPolicy / Dataset / DataSource / Pipeline / App / Workflow / AnalysisPlan 等均以 name 作为自然键；Property 以对象下的 apiName 作为自然键。
3. 引用解析：ResourceRefDTO 中的 name 用于资源引用，安装器通过名称解析目标资源。
4. Property 删除：可通过 PropertySyncReqDTO 或 ObjectTypePropertiesSpecDTO 的 REPLACE 模式删除属性，也可通过 :remove 接口下线单个属性。
5. 物化与发布顺序：物化必须在发布之前执行，因为发布需要物化过程中生成的 primaryDatasetId。
6. 安装后自动触发：
   • 数据集配置中，若 syncSchemaOnInstall / syncDataOnInstall 为 true，需自动触发同步 schema / 同步数据。
   • ObjectType 配置中，若 materializeOnInstall / publishOnInstall 为 true，需自动触发物化 / 发布本体。