ObjectType Spec

表达对象类型的定义语义，不包含运行态字段（如 id、status、currentPublishedVersionId）。安装行为字段（materializeOnInstall / publishOnInstall）保留在协议中，由投影层在写入后按顺序触发。

资源类型与自然键

资源类型	自然键	说明
`ObjectType`	`name`	对象类型名称，全局唯一

ObjectTypeSpecDTO

字段	类型	说明
`name`	string	名称，作为自然键
`displayName`	string	显示名称
`description`	string	描述
`icon`	string	图标
`primaryKey`	string	主键属性 API 名称
`primaryDatasetRef`	ResourceRefDTO	主数据集引用
`datasetBindingMode`	DatasetBindingModeEnum	主数据集绑定模式：`EXTERNAL` 外部映射 / `MANAGED` 平台托管；未显式声明时默认 `MANAGED`
`category`	string	未使用。分类占位字段，当前写入服务不消费。
`tags`	List<String>	未使用。标签占位字段，当前写入服务不消费。
`stateMachineEnabled`	boolean	未使用。状态机开关占位字段。
`auditEnabled`	boolean	未使用。审计开关占位字段。
`lineageEnabled`	boolean	未使用。血缘开关占位字段。
`states`	List<StateSpecDTO>	未使用。状态列表占位字段，对象状态机未启用。
`properties`	List<PropertySpecDTO>	属性列表（内联或独立提交均可），installer 会合并 ObjectTypePropertiesSpecDTO 中的属性
`materializeOnInstall`	boolean	安装时是否自动物化
`materialize`	ObjectTypeMaterializeSpecDTO	物化参数
`publishOnInstall`	boolean	安装时是否自动发布 Schema
`publish`	ObjectTypePublishSpecDTO	发布参数

datasetBindingMode 解析规则

显式声明 EXTERNAL 或 MANAGED 时，以声明值为准。
未显式声明时，统一默认 MANAGED，不再根据 primaryDatasetRef 是否存在推断。
EXTERNAL 对象不执行平台侧 schema 变更；MANAGED 对象由 Foundry 自动生成/演进 dataset、table、schema。

主数据集引用 (`primaryDatasetRef`)

primaryDatasetRef 使用 ResourceRefDTO 引用主数据集：

字段	说明
`kind`	资源类型，通常填 `Dataset`
`name`	数据集自然键（名称），优先使用
`apiName`	API 名称，`name` 为空时回退使用

写入服务解析 primaryDatasetRef 后，将数据集名称落库到 fd_ontology_object.primary_dataset_id：

若 primaryDatasetRef 指向的数据集不存在，且 materializeOnInstall 不为 true，创建/更新时抛出异常。
若 materializeOnInstall 为 true，则允许主数据集在物化阶段自动生成，无需提前存在。
创建时 primaryDatasetRef 为空且 materializeOnInstall 为 true，物化阶段会自动创建并绑定主数据集。

物化参数 (`materializeOnInstall` / `materialize`)

当 materializeOnInstall 为 true 时，投影层会触发 objectTypeApi.materializeObject。bundle 路径不再暴露独立 materialize 开关，而是通过统一 publish 链路在内部推进物理层同步。

ObjectTypeMaterializeSpecDTO

字段	类型	说明
`targetDataSourceId`	string	目标数据源 ID/名称；为空时使用 workspace 默认存储
`tableNamePrefix`	string	物理表名前缀
`releaseNotes`	string	版本 release notes；为空时默认 `"Auto materialized by definition projection"`

发布参数 (`publishOnInstall` / `publish`)

当 publishOnInstall 为 true、bundle 级 defaultPublishOnInstall 为 true，或 FE/CLI 显式调用统一 publish 接口时，投影层会触发 objectTypeApi.publishObjectSchema。

ObjectTypePublishSpecDTO

字段	类型	说明
`hardDrop`	boolean	是否硬删除物理列
`releaseNotes`	string	版本 release notes；为空时默认 `"Auto published by definition projection"`

属性内联声明

ObjectTypeSpecDTO.properties 支持在对象类型规格中直接内联声明属性，也可以独立使用 ObjectTypePropertiesSpecDTO 提交。投影层的行为如下：

OntologyDomainProjectionAdapter.project 将内联属性以 REPLACE 模式同步，确保已移除的属性在 ontology 层进入 REMOVED 态。
BundleInstallPlanBuilder 会将 objectTypeProperties 资源中的外部属性合并到对应 ObjectTypeSpecDTO 后再执行投影。
当 primaryKey 指定了属性 API 名称，且该属性未在 properties 中声明时，后端会自动创建该主键属性（STRING 类型、必填、可排序）。

消费位置

foundry-ontology-biz: OntologyDefinitionWriteService 将 name / displayName / description / icon / primaryKey / primaryDatasetRef / datasetBindingMode 投影到 fd_ontology_object。
foundry-ontology-biz: OntologyDomainProjectionAdapter.project 在写入后根据 materializeOnInstall / publishOnInstall 调用 objectTypeApi.materializeObject / ontologyApi.publishObjectSchema。
foundry-asset-biz: ObjectTypeInstaller 解析 primaryDatasetRef，注册 objectType 到安装上下文，并触发属性同步。
foundry-asset-biz: SpecToLegacyAssembler 在兼容路径中将字段映射到 ObjectCreateReqDTO。
foundry-definition-biz: ObjectTypeAggregateService 使用 DatasetBindingModeResolver 在聚合发布时解析绑定模式，对 MANAGED 且已绑定数据集的对象执行增量 schema apply。

示例 YAML

kind: ObjectType
name: Plant
spec:
  name: Plant
  displayName: 工厂
  description: 工厂对象
  icon: factory
  primaryKey: plant_id
  primaryDatasetRef:
    kind: Dataset
    name: plant_primary_dataset
  datasetBindingMode: MANAGED
  properties:
    - apiName: plant_id
      displayName: 工厂ID
      dataType: STRING
      required: true
      unique: true
      searchable: true
      titleProperty: true
    - apiName: status
      displayName: 工厂状态
      dataType: ENUM
      required: true
      semantic:
        semanticType: ENUM
        dictMapping:
          ACTIVE: 活跃
          INACTIVE: 停用
  materializeOnInstall: true
  materialize:
    targetDataSourceId: default_postgres
    tableNamePrefix: ot_
    releaseNotes: 初始物化
  publishOnInstall: true
  publish:
    hardDrop: false
    releaseNotes: 初始发布

示例 JSON

{
  "kind": "ObjectType",
  "name": "Plant",
  "spec": {
    "name": "Plant",
    "displayName": "工厂",
    "description": "工厂对象",
    "icon": "factory",
    "primaryKey": "plant_id",
    "primaryDatasetRef": {
      "kind": "Dataset",
      "name": "plant_primary_dataset"
    },
    "datasetBindingMode": "MANAGED",
    "properties": [
      {
        "apiName": "plant_id",
        "displayName": "工厂ID",
        "dataType": "STRING",
        "required": true,
        "searchable": true,
        "titleProperty": true
      },
      {
        "apiName": "status",
        "displayName": "工厂状态",
        "dataType": "ENUM",
        "required": true,
        "semantic": {
          "semanticType": "ENUM",
          "dictMapping": {
            "ACTIVE": "活跃",
            "INACTIVE": "停用"
          }
        }
      }
    ],
    "materializeOnInstall": true,
    "materialize": {
      "targetDataSourceId": "default_postgres",
      "tableNamePrefix": "ot_",
      "releaseNotes": "初始物化"
    },
    "publishOnInstall": true,
    "publish": {
      "hardDrop": false,
      "releaseNotes": "初始发布"
    }
  }
}