元数据注解

Softa 通过两条并存的路径维护 sys_* 目录表：

1. 注解（本页）——代码先行（code-first）。在 Java 实体类上声明元数据， 启动时由扫描器读取这些注解，与 sys_* 表对齐，并在开发模式下执行相应 DDL。 适合随代码库交付的基础定义——平台 / 框架模型，与源码一同版本化， 受代码评审和 CI/CD 约束。
2. Studio（可视化设计器）——配置先行（config-first）。可视化工作台 通过 WorkItem → Version → Deployment 的发布流程写入同样的 sys_* 行。 适合租户自定义与业务团队主导的配置，无需重新发布也能调整。 详见 Studio 使用指南。

两条路径不会互相覆盖：每条 sys_* 行都带有 Ownership 标记，注解扫描器只读写 PLATFORM_MAINTAINED 行。

需要 metadata-starter 作为应用的依赖，本节中的注解才会生效。 softa-orm 负责定义注解，metadata-starter 提供读取注解并与 sys_* 目录表对齐的扫描器和校验器。若缺少 metadata-starter，注解虽然仍写在你的类上， 但没有任何扫描器消费它们——sys_* 行不会被写入，也不会生成 DDL。

五个注解，全部位于 io.softa.framework.orm.annotation：

@Data
@EqualsAndHashCode(callSuper = true)
@Model(
    labelName = "Customer",
    businessKey = {"code"},
    description = "Customer master"
)
@Index(name = "uk_customer_code", fields = {"code"}, unique = true)
@Index(fields = {"status", "createdTime"})
public class Customer extends AuditableModel {
 
    private Long id;
 
    @Field(labelName = "Customer Code", required = true, length = 32)
    private String code;
 
    @Field(labelName = "Customer Tier")
    private CustomerTier tier;   // enum → FieldType.OPTION (inferred)
}
 
@OptionSet(name = "Customer Tier")
public enum CustomerTier {
    @OptionItem(itemName = "VIP Gold") GOLD("g"),
    @OptionItem(itemName = "Silver")   SILVER("s");
 
    @JsonValue private final String code;       // itemCode = @JsonValue
    CustomerTier(String code) { this.code = code; }
}

推断规则（无需注解）

@Model ↔ SysModel

各属性的业务语义：见 模型元数据。

审计字段（createdTime / createdBy / createdId / updatedTime / updatedBy / updatedId）来自 AuditableModel，不需要通过 @Field 声明——当类继承 AuditableModel 时，DdlGenerator 会自动注入这些列。

@Field ↔ SysField

各属性的业务语义与完整字段类型表：见 字段元数据。

@OptionSet ↔ SysOptionSet

运行时行为、缓存机制与 API 返回形态：见 选项集。

@OptionItem ↔ SysOptionItem

展示属性（itemTone、itemIcon）与 API 返回形态：见 选项集。

@Index ↔ SysModelIndex

@Index 是 @Repeatable 的——可以在同一个 @Model 类上叠加多次声明。

注意：@Model.businessKey 不会自动创建唯一索引。 多租户模型通常需要 UNIQUE (tenant_id, businessKey...)， 这种带租户语义的索引无法仅通过 @Index 表达——请显式声明：

@Index(fields = {"tenantId", "code"}, unique = true)

行归属（Ownership 枚举）

sys_model / sys_field / sys_option_set / sys_option_item / sys_model_index 中的每一行都带有 ownership 列 （io.softa.framework.orm.enums.Ownership）：

扫描器的读写都带有 WHERE ownership = 'PLATFORM_MAINTAINED' 过滤条件， 因此平台默认值与租户的自定义内容不会被一次注解对齐操作覆盖。

完整的合并规则契约见 Ownership.java 的 javadoc。