数据类型

在配置数据模型和声明运行期变量（如客户端变量、页面变量、行为参数）时，必须选择正确的数据类型。

Zion 的底层基于企业级关系型数据库 PostgreSQL 构建。为了让您的系统具有高运行性能、强数据完整性和精确的科学计算，本手册详细列出了平台支持的所有核心数据类型的存储规范与适用场景。

1. 基础数据类型

基础数据类型用于存储传统的文本、数字和日期信息：

类型名称	底层物理类型 (PostgreSQL)	存储字节与限制	适用业务场景与选型参考
文本	`text`	支持最大 `1 GB` 的超长字符。	普通文本（用户名、邮箱、地址）、长篇大论的富文本正文、HTML 字符串等。
整数	`integer`	`4 字节`。数值范围：`-2,147,483,648` 到 `+2,147,483,647`。	用于计数、数量、分页号、排序权重、物理 ID、逻辑状态码（如：`0: 草稿`, `1: 已发布`）。
无限精度小数	`numeric`	高精度的可变长度类型。最大支持 `131072` 位。	强烈推荐用于价格、交易、账户资金等财务数据。它能绝对避免常规计算机因浮点数运算产生的舍入误差。
布尔值	`boolean`	`1 字节`。取值：`true` (真 / 是) 或 `false` (假 / 否)。	开关状态（开启、关闭）、逻辑标记（如：`is_logged_in` 是否登录、`is_vip` 是否会员）。

⚠️

为什么有了小数，还必须强调“无限精度”？
在一般的 JavaScript 或大部分高级语言中，小数默认以双精度浮点数（Float）在内存中表示。计算 0.1 + 0.2 时，因为二进制转换问题会产生微小误差，输出 0.30000000000000004。
在 Zion 中，数据库层采用标准的 Postgres numeric (无限精度小数) 类型，它会在数据库中强制执行完全精确的十进制数字计算，绝不损失任何精度，完美契合商业、电商及银行级财务账单审计要求。

2. 时间与时区数据类型

日期和时间处理必须遵循标准的国际时区规范，Zion 对时间的设计极其严谨：

类型名称	标准 ISO 格式	核心物理特征	典型应用场景
日期时间（带时区）	`YYYY-MM-DDTHH:mm:ss.sssZ`	带有绝对时间戳，自动结合客户端本地时区进行显示转换。	订单支付时间、行为触发日志、会议预约、用户登录时间戳。
日期	`YYYY-MM-DD`	不包含具体的小时、分钟、秒，也不受跨时区的影响。	生日（如 `1998-05-12`）、入职纪念日、合同起止日期。
时间（带时区）	`HH:mm:ss.sssZ`	仅表示一天中的某个时间段，包含了时区基准。	每日例会时间（如 `14:30:00`）、店铺每日营业/打烊时间。

3. 多媒体及二进制资源类型

图片、视频和文件类型本身在数据库中并不直接存放巨大的物理二进制数据。它们的工作机制是：

文件一经在前端或后台上传，会被自动分发部署到云端的对象存储（OSS/COS）中。
数据库中该字段实际保存和读写的是该资源对应的绝对 URL 地址链接（形如：https://fz-zion.oss-cn-shanghai.aliyuncs.com/image/...）。

类型名称	数据库物理展现	编辑器默认行为	适用场景与最佳实践
图片	`text (URL 链接)`	在前台拖入“图片”组件后，可以直接将图片源绑定为此字段，自动提取并渲染。	商品主图、用户头像、发票报销照片（支持 `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp` 等格式）。
视频	`text (URL 链接)`	在前台视频播放组件中，可直接将播放源绑定此字段。	短视频、产品介绍视频、教学课程视频（支持 `.mp4`, `.mov` 等主流在线流格式）。
文件	`text (URL 链接)`	在点击行为中，可以一键绑定触发“下载此文件”。	PDF 附件、Word 员工手册、Excel 模板、压缩包下载。

4. 地理位置与高级非结构化数据类型

为了应对复杂的周边查询和不确定数据结构的快速读写，Zion 提供了以下企业级高级类型：

4.1 经纬度

物理构成：在 PostgreSQL 中使用地理位置点数据表示，内部由经度和纬度的数字双精度数组表示（例如：[120.2934, 30.3150]）。
核心价值：支持在数据源拉取时，调用强大的地理位置公式运算。例如：可调用距离计算公式计算“用户当前位置”与“多门店数据表经纬度”之间的距离差，并按照该距离执行“自近及远”的数据排序，直接实现**“查看周边店铺”**这一高频商业场景。

4.2 JSONB（非结构化 JSON 字段）

物理构成：二进制 JSON。它是 Postgres 专属的非结构化扩展类型。
核心特征：它不仅支持存储复杂的、多维嵌套的 JSON 树形对象和数组，还会在写入时自动对其进行语法去重和格式精简。最重要的是，JSONB 在底层支持高级的索引检索（GIN 索引），这使得您可以直接在数据源过滤条件中，通过写路径语法高效地检索 JSON 字段内部的具体子属性，而不是像常规数据库那样每次都得全表慢查询解析。
适用场景：
- 保存结构不确定的第三方 Webhook 回调原始日志。
- 保存商品的可变多维属性配置（如：{"颜色": "红色", "尺码": "XXL"}）。
- 在页面变量中，临时存放一整行复杂的临时缓存数据。