模型与字段
Model 是每个 AuraBoot 应用的基础。一个 Model 描述你希望存储或展示的业务数据。基于这份定义,AuraBoot 可以创建表、暴露动态 API、渲染表单字段、校验输入并绑定权限。
Model 类型
AuraBoot 针对不同的数据职责使用不同的 Model 类型:
| 类型 | 物理表 | 典型用途 |
|---|---|---|
entity | 是 | 客户、订单、任务、发票、Lead |
view | 否 | 由查询支撑的只读列表或详情投影 |
tree | 是 | 层级树形数据(分类、组织结构) |
virtual | 否 | 无物理表的虚拟模型 |
大多数业务模块从 entity 模型起步。当你需要读优化的页面、报表、Dashboard 或来自多个来源的组合数据时,view 模型才会派上用场。
Model 定义
一个简单的 entity 模型如下:
{
"code": "crm_lead",
"name": "Lead",
"modelType": "entity",
"tableName": "mt_crm_lead",
"description": "Sales lead tracking",
"fields": [
{ "code": "lead_name", "name": "Lead Name", "dataType": "string", "required": true },
{ "code": "email", "name": "Email", "dataType": "string", "unique": true },
{ "code": "status", "name": "Status", "dataType": "enum", "dictCode": "crm_lead_status" }
]
}| 属性 | 必填 | 说明 |
|---|---|---|
code | 是 | 稳定的 Model 标识,通常为 snake_case |
name | 是 | 人类可读的标签 |
modelType | 是 | entity、view、tree 或 virtual |
tableName | 否 | 物理表名;可自动生成 |
description | 否 | 业务用途与使用说明 |
fields | 是 | 由 API 与 UI 渲染的 Field 定义 |
Field 类型
| 数据类型 | 存储 | UI 行为 | 示例 |
|---|---|---|---|
string | varchar | 单行输入 | 名称、标题 |
text | text | 多行输入 | 备注、描述 |
integer | bigint | 数字输入 | 数量 |
decimal | numeric | 小数输入 | 金额、价格 |
money | numeric | 多币种金额 | 价格、合同金额 |
boolean | boolean | 开关或复选框 | 启用标识 |
date | date | 日期选择器 | 到期日期 |
datetime | timestamp | 日期-时间选择器 | 事件时间 |
enum | varchar | 下拉、单选、徽章(配 dictCode) | 状态 |
reference | bigint | 可搜索的 picker | 负责人 |
json | jsonb | 结构化对象 | 扩展属性 |
computed | virtual | 只读展示 | 总金额 |
Field 类型不仅是数据库层面的决定,也影响校验、生成的 UI 控件、过滤、排序、显示格式与 API 负载处理。
Dictionary
当某个字段的取值集合受控时,使用 Dictionary:
{
"code": "crm_lead_status",
"name": "Lead Status",
"items": [
{ "value": "new", "label": "New", "sortNo": 1 },
{ "value": "contacted", "label": "Contacted", "sortNo": 2 },
{ "value": "qualified", "label": "Qualified", "sortNo": 3 },
{ "value": "lost", "label": "Lost", "sortNo": 4 }
]
}Dictionary 取值适用于状态、分类、优先级、来源、地区等需要在表单、列表、过滤器、Dashboard 和 Workflow 之间保持一致的取值。
Reference 字段
Reference 字段连接 Model:
{
"code": "assigned_to",
"name": "Assigned To",
"dataType": "reference",
"referenceModelCode": "sys_user",
"refDisplayField": "display_name"
}Reference 用于列表列、详情页、子表、权限、Workflow 与报表。一种常见模式是一个父 Model 携带子记录:
crm_account
-> crm_contact.account_id
-> crm_opportunity.account_id
-> crm_activity.account_id系统字段
AuraBoot 会向托管的 entity 表添加标准系统字段:
| 字段 | 用途 |
|---|---|
id | 内部主键 |
pid | 稳定的公开标识 |
tenant_id | Tenant 隔离 |
created_at | 创建时间戳 |
updated_at | 最后更新时间戳 |
created_by | 创建者用户 |
updated_by | 最后修改者 |
不要在 Model JSON 里重复定义这些字段。在过滤、审计视图与集成中按需使用即可。
设计建议
- 倾向使用稳定、业务可读的 Model code,例如
crm_lead或pm_task。 - 数据存在后保持 Field code 稳定。重命名字段属于一次迁移。
- 对驱动 Workflow 的状态使用 Dictionary。
- 使用 Reference 字段,而不是在记录间复制显示名。
- 为含有超出标签业务含义的字段补充描述。
- 从 entity 模型起步;只有当某个页面或报表需要组合投影时才引入 view 模型。