设计和变更表结构

表结构是数据库与应用、智能体、工作流和 API 之间的字段契约。字段一旦被调用方引用，改名、删除或修改类型都可能造成运行失败或数据丢失。

查看表结构

图 1：在 表结构 页签查看字段名称、描述、索引、类型和必填状态；右上角进入编辑。

系统字段

当前数据库自动维护以下字段：

字段	页面类型	含义	是否手工维护
id	String(uuid)	记录唯一标识和主键	系统生成，不可删除
sys_platform	String	记录产生或使用的渠道	系统按调用渠道维护
uuid	String	最终用户唯一标识，用于用户数据范围	系统按用户上下文维护
created_at	Time	记录创建时间	系统生成

旧文档中的 bstudio_create_time 已对应为当前页面的 created_at。导入模板和工作流字段映射应使用当前字段名，不要继续创建同义字段。

系统字段不应由 CSV、JSON、用户输入或模型输出伪造。当前页面会固定显示系统字段，并限制删除和类型修改。

自定义字段

支持的数据类型

类型	适用内容	示例	设计注意
String	名称、编号、状态、说明	order_status = "pending"	需要约定枚举值、格式和最大长度
Integer	次数、等级、数量	priority = 3	不保存小数，不用字符串代替
Number	金额、比例、测量值	amount = 199.50	明确单位和精度
Boolean	是/否、启用状态	approved = true	统一使用布尔值，不使用“是/否”字符串
Time	创建、计划或业务时间	due_at	明确时区和输入格式

字段名称

当前前端校验要求字段名称：

• 以小写英文字母开头。
• 只包含小写字母、数字和下划线。
• 不能与同表字段重复。
• 不能使用 id、sys_platform、uuid、created_at 等系统保留字段。

建议使用 customer_name、order_status、due_at 等稳定语义。不要使用 field1、临时缩写、含空格名称或把显示文案直接作为字段名。

描述、索引和必填

配置	用途	建议
描述	帮助模型和维护者理解字段	写清业务含义、枚举值、单位、格式和示例，但不放真实敏感数据
设为索引	加快高频条件查询	只为真实筛选、排序或唯一定位字段设置，避免所有字段都建索引
是否必填	新增记录时必须提供	上线前明确默认值；已有数据表新增必填字段时先处理历史空值

编辑表结构

图 2：编辑弹窗会固定系统字段，并允许增加、修改或删除自定义字段。顶部警告说明删除字段和类型转换可能影响已有数据。

各类变更的影响

变更	主要风险	推荐方式
新增可选字段	旧调用方不传值时为空	先增加，再逐步让调用方写入
新增必填字段	历史数据没有值，旧写入请求失败	先增加可选字段并补值，最后再改为必填
字段改名	工作流、表单、API 和导入模板仍引用旧名	新增新字段，迁移数据和调用方后删除旧字段
修改类型	已有值可能无法转换，保存可能失败	导出数据，在测试样本验证转换后再操作
删除字段	该列数据及引用关系丢失	先导出、检查引用、停止写入，确认后删除
新增/删除索引	影响查询性能和写入成本	根据真实查询条件和日志调整

安全变更流程

1. 导出测试和线上数据，记录数据库、字段和导出时间。
2. 搜索应用、智能体、工作流、API、SDK 和导入模板中的字段引用。
3. 在测试数据中构造正常、空值、边界值和旧格式记录。
4. 优先采用“新增字段—双写或迁移—切换读取—删除旧字段”的兼容方案。
5. 保存后执行新增、查询、更新、删除、导入和导出回归。
6. 验证不同用户、渠道以及测试/线上环境没有出现范围变化。
7. 观察调用日志和失败记录，确认迁移完成后再清理旧字段。

页面提示保存成功只说明结构操作完成，不代表所有调用方已经兼容。

常见问题

为什么字段类型修改后保存失败？

已有数据中存在无法转换的值。先导出数据，定位不兼容记录；如果无法无损转换，新增目标类型字段并迁移，而不是强制覆盖原字段。

为什么提示使用了保留字段？

字段名与系统字段或数据库保留名称冲突。改用带业务前缀的名称，例如把 status 细化为 order_status；不要通过大小写或特殊字符绕过校验。

新字段保存成功，为什么工作流仍然看不到？

重新打开数据库选择器或节点配置，确认工作流加载了最新表结构；同时检查当前草稿是否仍引用旧字段 ID 或旧发布版本。

下一步进入管理数据、导入导出与渠道。