Property Spec

表达对象属性的定义语义。运行态字段（如 id、status、physicalColumnState）不出现在定义协议中；datasetColumnName 作为 authoring 场景下物理列映射草稿保留在协议中。

资源类型与自然键

资源类型	自然键	说明
`Property`	`${objectName}.${apiName}`	对象名与属性 API 名称组成复合自然键，在对象范围内唯一

字段	类型	说明
`apiName`	string	API 名称，属性自然键的一部分
`displayName`	string	显示名称
`dataType`	PropertyDataTypeEnum	数据类型
`required`	boolean	是否必填；写入 `metaConfig.validation.required`，并影响物化 DDL
`unique`	boolean	未使用。唯一性约束占位字段。
`defaultValue`	Object	未使用。默认值占位字段。
`description`	string	未使用。描述占位字段，当前写入服务不消费。
`searchable`	boolean	是否可搜索
`sortable`	boolean	是否可排序
`groupable`	boolean	是否可分组
`titleProperty`	boolean	是否为标题属性
`pii`	boolean	是否包含个人身份信息
`propertyKind`	PropertyKindEnum	属性种类
`stabilityLevel`	StabilityLevelEnum	稳定级别
`materializationStrategy`	MaterializationStrategyEnum	物化策略
`datasetColumnName`	string	绑定的物理列名；为空时默认使用 `apiName` 的 snake_case
`reference`	ReferenceSpecDTO	引用规格
`compute`	ComputeSpecDTO	计算规格
`semantic`	SemanticSpecDTO	语义规格
`ui`	UiSpecDTO	UI 规格
`validation`	ValidationSpecDTO	验证规格
`security`	SecuritySpecDTO	安全规格
`capabilities`	CapabilitySpecDTO	能力规格

取值	说明
`STRING`	字符串
`INTEGER`	整数（存储层映射为整数）
`LONG`	长整数（存储层映射为整数）
`NUMBER`	数字（存储层映射为浮点数）
`DOUBLE`	浮点数（存储层映射为浮点数）
`BOOLEAN`	布尔
`DATE`	日期
`DATETIME`	日期时间（存储层映射为时间戳）
`TIMESTAMP`	时间戳（存储层映射为时间戳）
`ENUM`	枚举，需配合 `semantic.dictMapping` 使用
`REFERENCE`	引用，需配合 `reference` 使用
`COMPUTED`	计算，需配合 `compute` 使用
`JSON`	JSON，存储层按字符串落盘
`ARRAY`	数组，存储层按字符串落盘
`OBJECT`	对象，存储层按字符串落盘

用于独立声明 ObjectTypeProperties canonical 资源，支持按对象聚合的属性同步。

字段	类型	说明
`objectRef`	ResourceRefDTO	所属对象引用；属性同步链路仅消费 `name`，`kind` / `apiName` 未使用
`syncMode`	PropertySyncMode	同步模式，默认 `MERGE`
`properties`	List<PropertySpecDTO>	属性列表

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

取值	说明
`MERGE`	仅对传入属性做 upsert，不删除未出现的属性
`REPLACE`	以请求中的属性集合作为目标状态，缺失属性执行逻辑删除（进入 `REMOVED` 态）

字段	类型	说明
`objectRef`	ResourceRefDTO	引用目标对象；仅 `name` 被消费
`referenceType`	ReferenceTypeEnum	引用类型：`SINGLE` 单值引用 / `MULTI` 多值引用
`cascadeRule`	CascadeRuleEnum	级联规则：`NONE` / `RESTRICT` / `CASCADE` / `SET_NULL`

字段	类型	说明
`computeType`	ComputeTypeEnum	计算类型：`DERIVED` 表达式派生 / `AGGREGATED` 关系聚合 / `DYNAMIC` 运行时动态计算
`expression`	string	计算表达式，`DERIVED` 时使用
`relationPath`	List<String>	关系路径，`AGGREGATED` 时使用
`aggregate`	AggregateTypeEnum	聚合函数，`AGGREGATED` 时使用
`filter`	FilterSpecDTO	未使用。计算属性过滤条件占位字段。
`materializationStrategy`	MaterializationStrategyEnum	未使用。计算属性物化策略占位字段。

字段	类型	说明
`semanticType`	string	语义类型
`description`	string	描述
`dictMapping`	Map<String, String>	字典映射；ENUM 属性的枚举值域唯一来源（键为枚举值，值为展示文案）

字段	类型	说明
`required`	boolean	未使用。请使用顶层 `PropertySpecDTO.required`，写入服务不会读取此字段。
`min`	double	最小值
`max`	double	最大值
`maxLength`	integer	最大长度；同时影响物化 DDL
`regex`	string	正则表达式
`errorMessage`	string	错误提示信息

foundry-ontology-biz: OntologyDefinitionWriteService.syncProperties / buildPropertyEntity / applyPropertyUpdate / buildPropertyMetaConfig 将字段投影到 fd_ontology_property。
foundry-ontology-biz: OntologyDomainProjectionAdapter 实现 PropertyProjectionHandler，并在 ObjectType 投影时以 REPLACE 模式同步内联属性。
foundry-definition-biz: DefinitionWriteService.syncProperties 协调 authoring 与 bundle 流程中的属性版本写入。
foundry-definition-biz: BundleDefinitionUpsertExecutor 解析 ObjectTypePropertiesSpecDTO.objectRef.name 后调用属性同步。
foundry-definition-biz: DefinitionCommandController 暴露属性同步入口。

仅支持通过 PropertySyncReqDTO 或 ObjectTypePropertiesSpecDTO 的 REPLACE 模式删除属性：目标集合中未出现的现存属性会被标记为 REMOVED，而非物理删除。