数据模型设计器

负责：
  - 定义实体、字段、类型、约束
  - 定义实体间关系与级联行为
  - 生成 DDL 并执行迁移
  - 为 API 生成 CRUD 接口
  - 为 UI 提供字段元数据

不负责：
  - 复杂业务逻辑（那是后端服务）
  - 复杂查询与报表（那是查询层）
  - 跨库分布式事务

type FieldType =
  | 'string' | 'text' | 'integer' | 'decimal'
  | 'boolean' | 'date' | 'datetime' | 'enum'
  | 'json' | 'file' | 'ref';

interface EntityField {
  id: string;
  name: string;            // 列名，snake_case
  label: string;
  type: FieldType;
  length?: number;         // string 长度
  precision?: number;      // decimal 精度
  scale?: number;
  nullable?: boolean;
  unique?: boolean;
  defaultValue?: unknown;
  enumValues?: string[];   // enum 取值
  refEntity?: string;      // ref 指向的实体
  comment?: string;
}

一对一（1:1）：用户 ↔ 用户档案
  外键放在从表，加唯一约束

一对多（1:N）：订单 → 订单项
  外键放在「多」的一方

多对多（M:N）：学生 ↔ 课程
  需要中间表，含两个外键 + 联合唯一

{
  "entities": {
    "order": {
      "fields": [
        { "name": "id", "type": "string", "unique": true },
        { "name": "customer_id", "type": "ref", "refEntity": "customer" }
      ]
    },
    "order_item": {
      "fields": [
        { "name": "id", "type": "string" },
        { "name": "order_id", "type": "ref", "refEntity": "order", "nullable": false },
        { "name": "qty", "type": "integer" }
      ]
    }
  },
  "relations": [
    { "type": "1:N", "from": "order", "to": "order_item", "onDelete": "cascade" }
  ]
}

-- 由模型生成的建表语句（PostgreSQL）
CREATE TABLE "app_1024"."order" (
  id           varchar(36) PRIMARY KEY,
  customer_id  varchar(36) NOT NULL REFERENCES "app_1024"."customer"(id),
  amount       numeric(12,2) NOT NULL DEFAULT 0,
  status       varchar(20) NOT NULL DEFAULT 'draft',
  created_at   timestamptz NOT NULL DEFAULT now(),
  updated_at   timestamptz NOT NULL DEFAULT now(),
  tenant_id    varchar(36) NOT NULL,
  CONSTRAINT chk_status CHECK (status IN ('draft','paid','shipped'))
);

CREATE INDEX idx_order_tenant ON "app_1024"."order"(tenant_id);

生成规则：
  1. 每个实体一张表
  2. 每个字段一列（类型映射）
  3. 主键固定为 id（varchar(36) 或 bigserial）
  4. 审计列固定：created_at / updated_at / created_by
  5. 多租户加 tenant_id 并建索引
  6. ref 字段生成外键约束
  7. 唯一约束与 check 约束按模型生成

迁移类型：
  新增表         → CREATE TABLE（安全）
  新增可空列     → ALTER TABLE ADD COLUMN（安全）
  新增非空列     → 需默认值或分步（先可空 → 回填 → 设非空）
  改列类型       → 可能锁表，需评估（用 USING 转换）
  改列名         → 破坏性，需同步更新引用
  删列           → 最危险，先软删（标记废弃）再物理删

interface Migration {
  id: string;
  version: number;
  up: string[];      // 正向 SQL
  down: string[];    // 回滚 SQL
  destructive: boolean;  // 是否破坏性
  requiresConfirm?: string; // 需用户输入确认短语
}

-- 第 1 步：加可空列
ALTER TABLE "order" ADD COLUMN remark varchar(200);
-- 第 2 步：回填历史数据
UPDATE "order" SET remark = '' WHERE remark IS NULL;
-- 第 3 步：设为非空
ALTER TABLE "order" ALTER COLUMN remark SET NOT NULL;

自动生成的索引：
  - 主键（隐含唯一索引）
  - 外键列（加速关联查询）
  - tenant_id（多租户隔离）
  - 高频过滤字段（基于查询统计推荐）

用户可加：
  - 唯一索引（业务唯一）
  - 复合索引（多列组合查询）

CREATE UNIQUE INDEX uk_order_no ON "order"(tenant_id, order_no);
CREATE INDEX idx_order_status_created ON "order"(tenant_id, status, created_at DESC);

数据源类型：
  1. 平台内建表（由设计器管理 DDL）
  2. 外部库只读（映射已有表，不管理 DDL）
  3. 外部 API（虚拟实体，无物理表）

统一抽象：
  Entity {
    kind: 'internal' | 'external' | 'virtual',
    ddlManaged: boolean,
    ...
  }

interface Entity {
  id: string;
  name: string;
  kind: 'internal' | 'external' | 'virtual';
  ddlManaged: boolean;     // 平台是否管理其 DDL
  fields: EntityField[];
  dataSourceId?: string;   // 外部数据源引用
}

三层校验：
  1. 数据库层：NOT NULL / UNIQUE / CHECK / FK
  2. 应用层：字段级校验（长度、范围、格式）
  3. 业务层：跨实体规则（如库存足够）

低代码设计器通常管前两层，第三层交给流程/服务。

{
  "name": "amount",
  "type": "decimal",
  "precision": 12,
  "scale": 2,
  "nullable": false,
  "validators": [
    { "type": "min", "value": 0 },
    { "type": "max", "value": 1000000 }
  ]
}

联动链路：
  模型字段 → 表单字段（自动生成默认表单）
  模型字段 → 列表列（自动生成默认列表）
  模型关系 → 关联选择器（ref 字段渲染成下拉）
  模型枚举 → 选项源

重命名字段的联动：
  模型层改 name → 扫描所有引用 → 批量更新绑定 → 生成迁移

环境流转：
  开发环境改模型 → 生成迁移脚本 → 版本化
  → 测试环境执行 → 验证
  → 生产环境执行 → 记录

要点：
  - 模型版本与应用版本绑定
  - 迁移脚本随版本归档，可重放
  - 生产迁移需审批 + 备份
  - 结构漂移检测（实际表结构 vs 模型定义）