# 创建 API（Template + Create）

该文档补充 `modules/database_meta/API.md`，专注于新添加的创建相关接口：

- POST /metadata/create/template — 返回用于前端渲染创建表单的模板
- POST /metadata/object/create — 接收表单数据以生成预览 SQL 或执行创建

---

## POST /metadata/create/template

描述：返回用于前端渲染创建表单的模板（字段定义、枚举选项、示例等）。前端使用该模板生成表单，用户填完后调用 `/metadata/object/create` 进行预览或执行。

请求体（JSON）：

```json
{
  "objectType": "table",   // 必需：要创建的对象类型，例如 table/database/index
  "parentName": "mydb"     // 可选：父上下文（例如创建表时为数据库名）
}
```

响应（成功示例）：

```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "objectType": "table",
    "operation": "create",
    "parentHint": "parentName should be the database name",
    "fields": [
      {"name":"tableName","label":"Table Name","type":"string","required":true},
      {"name":"engine","label":"Engine","type":"enum","enumOptions":["InnoDB","MyISAM"],"default":"InnoDB"},
      {"name":"charset","label":"Charset","type":"enum","enumOptions":["utf8mb4","utf8","latin1","ascii","ucs2","utf16","utf32","big5","gbk"],"default":"utf8mb4"},
      {"name":"columns","label":"Columns","type":"list","nestedFields":[{"name":"name","type":"string"},{"name":"type","type":"string"}]}
    ],
    "example": {"tableName":"users","columns":"[{\"name\":\"id\",\"type\":\"INT\"}]","engine":"InnoDB"}
  }
}
```

备注：模板中会包含枚举选项（例如 `charset` 的常用字符集），驱动层已将常用字符集手动列出，前端应根据返回的 `enumOptions` 渲染下拉选择，而不是硬编码字符集列表。

说明（关于 `operation` 与 `current` 字段）
- 返回的模板为 `meta.ObjectTemplate`。为了统一模板格式，`ObjectTemplate` 包含一个可选字段 `operation`，值示例为 `"create"|"update"|"delete"`。
-- 对于创建（create）场景，`operation` 的值为 `"create"`。通常 `ObjectTemplate.Current`（对象级当前值）在创建场景不带值或为空；前端无需依赖 `current` 来填充创建表单。
-- 当调用更新（update）或删除（delete）模板端点时，服务端会在 `ObjectTemplate.Current`（map[string]string）以及每个 `TemplateField.Current`（string）中填充当前值，便于前端渲染默认值或展示影响预览。有关 `current` 的详细使用示例和前端优先级，请参阅 `API.md` 中的“关于当前值 (current) 的获取与使用”章节。

---

## POST /metadata/object/create

描述：接收前端渲染并提交的创建表单数据。支持两种模式：preview（execute=false，仅返回生成的 SQL）和 execute（execute=true，驱动尝试执行生成的 SQL，需慎用）。

请求体（JSON）：

```json
{
  "objectType": "table",          // 必需
  "parentName": "mydb",           // 可选，若为表则通常为数据库名
  "properties": {                  // 必需，表单字段和值
    "tableName": "users",
    "columns": [{"name":"id","type":"INT","nullable":false}],
    "engine": "InnoDB",
    "charset": "utf8mb4"
  },
  "execute": false                  // 可选，false=preview（默认），true=execute（执行 SQL）
}
```

响应（preview 成功示例）：

```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "success": true,
    "generatedSQL": ["CREATE TABLE `mydb`.`users` ( `id` INT NOT NULL ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;"],
    
  }
}
```

响应（execute 路径注意）：

- 若 `execute==true`，驱动会尝试执行生成的 SQL；请注意 DDL 操作在不同数据库/引擎下可能不可回滚，务必在有足够权限和审计的前提下使用。
- 当前实现对 execute 路径可能仍处于未全部实现或受限状态，客户端应以返回的 `message`/`success` 为准，并在开启执行前要求用户二次确认。

---

## 常见字段映射说明

- 驱动层将 `CreateTemplate` 中的字段作为前端渲染的契约，典型字段含义：
  - `type=="enum"`：请使用 `enumOptions` 渲染下拉菜单；不要在客户端硬编码 charset，而应使用驱动返回的 `enumOptions`。
  - `type=="list"`：表示可重复的子项（如 columns），`nestedFields` 描述每个子项的字段。

## 安全与权限建议

- `execute==true` 操作应仅对受信任用户开启，并做好审计日志。建议在 handler 层或 API 网关对执行创建/删除的请求进行额外权限校验并记录调用者信息（用户、时间、请求体、生成的 SQL）。

## 向前不兼容（Breaking changes）提醒

本模块近期进行了若干向前不兼容的接口与行为调整：

- 不再接受 dotted ID（点号拼接）的 `objectID`/`parentID`；请改为使用结构化字段 `objectName` / `parentName`。
- `GetRootObjects`/`GetChildObjects`/`GetObjectDetails` 新增 `fetch` 参数以支持“仅返回类型/计数”或“展开详细数据”的两种模式。

---

如果你希望我把这份文档合并回 `API.md` 的特定位置、生成 OpenAPI/Swagger，或为 `/metadata/object/create` 添加单元测试（覆盖 preview 路径），请告诉我下一步要做什么。