集合与数据

集合是机器人的自有数据表。你可以在其中存储申请、订单、对话中收集的回答、游戏积分、课程预约——一切由机器人从用户处收集或通过集成获取的数据。该功能位于左侧菜单：数据 → 集合。

什么是集合

集合由字段（描述列的 Schema）和记录（数据行）组成。每条记录是集合字段的一组值；内部以灵活的 JSON 文档形式存储，因此集合在添加新字段时不会出问题。

集合名称在同一机器人内唯一，并作为反应动作中的标识符使用（例如 leads、orders、scores）。

字段类型

创建集合时，需指定字段列表及每个字段的类型：

  • text — 字符串（姓名、邮箱、备注）。
  • number — 数字（金额、数量、积分）。
  • bool — 是/否（true / false）。
  • datetime — 日期和时间。
  • json — 嵌套对象或数组，用于复杂值。

类型影响字段在界面中的编辑方式以及保存时值的转换方式。Schema 并非强制约束：如果记录中出现 Schema 外的字段，它同样会被保存并以独立列显示。

创建集合

  1. 打开数据 → 集合，点击添加。
  2. 输入名称（使用拉丁字母，不含空格——这样在反应中引用更方便）。
  3. 点击字段按钮添加所需列，并为每列选择类型。
  4. 如需配置存储规则（见下文），完成后保存。

记录：查看与编辑

集合卡片上有一个表格图标按钮——点击后打开该集合的数据窗口：

  • 查看 — 所有行以列表形式显示，每个字段对应一个单元格，最新记录排在最前面。
  • 添加记录 — 根据集合 Schema 打开表单；每个字段按其类型编辑（bool 使用开关，json 使用 JSON 输入框等）。
  • 编辑（铅笔图标）— 修改现有行。
  • 删除（垃圾桶图标）— 删除该行。

记录也可通过机器人反应动作自动填充（见下文）。手动编辑与自动写入操作的是同一个集合。

存储保留期（Retention）

为防止集合无限增长，可设置自动清理规则：

  • 最大保留记录数 — 超出限制时，最旧的记录会被删除。
  • 最长保留天数 — 超过指定天数的记录会被删除。

清理由后台进程定期执行；规则可组合使用。

从反应中操作数据

集合与反应构建器直接关联。反应动作中提供以下操作：

  • 创建记录 — 添加一行；值来自模板（例如 {{user.id}}、{{message.text}}）。可设置去重键，使重复调用更新同一行而非产生重复记录。
  • 更新记录 — 修改满足条件的行。
  • 查询记录 — 将行作为数组读入执行上下文，以供后续遍历。
  • 删除记录 — 按条件删除行。
  • 循环（for-each） — 遍历上下文中的数组，并对每个元素执行嵌套动作（例如，按集合中的列表逐一发送消息）。

这样，机器人无需外部数据库即可管理 CRM、积累申请、累计积分并生成报告。

从 Mini App 访问

可以从机器人的 Telegram Mini App 读取集合记录：前端通过集合名称、过滤条件和限制来请求数据。这样可以在 Telegram 内部直接向用户展示其订单、历史记录或排行榜。

使用建议

  • 为字段取简短的机器名称（email、total、paid）——在反应模板中引用更方便。
  • 对于幂等写入（例如"每个用户只有一条申请"），使用去重键。
  • 对日志和临时数据启用 retention，防止集合无限增长。
  • 当值的结构不固定时，使用 json 类型。