交互（行为）模型

交互模型是应用让静态页面”动起来”的关键。Zion 的交互模型基于 事件驱动（Event-Driven） 机制：

触发器：定义何时执行（如：按钮点击、页面加载、定时任务到达）
动作：定义做什么（如：更新数据库、显示提示、调用 API）

一个例子：从用户视角到开发者视角

用户操作：在商品列表中点击某个商品，进入详情页，再点击支付按钮即可购买该商品。

开发者视角：需要把上述流程拆成「何时 + 做什么」的配置

当用户点击商品卡片这个视图时，需要执行一个跳转页面动作，跳转到对应商品的详情页。
当用户点击详情页上的支付按钮时，需要先执行一个运行行为流动作在服务端安全地创建一个状态为待支付的订单，并在行为流返回成功后，执行支付动作完成交易。

对应的开发配置：

在商品卡片视图组件的右边栏-行为面板中，在「点击时」下配置一个跳转页面动作，并传入目标页面（详情页）和参数（商品 id）。
在支付按钮组件的右边栏-行为面板中，在「点击时」下配置一个运行行为流（创建订单）动作，并传入 product_id 给后端。在其“成功时”分支中，使用行为流返回的订单 ID 和待支付金额数据配置一个支付动作。

理解这种从用户操作到对应的开发配置的映射关系，对于掌握 Zion 的交互模型至关重要。

前后端交互的能力边界

在 Zion 中，**前端（客户端）和后端（服务端）**的交互有着明显的界限和分工：

前端交互: 运行在用户的浏览器或移动端 App 中（客户端）。
后端行为流: 运行在服务器上（服务端）。

为什么要区分前端和后端？

这种区分源于运行环境的本质差异：

安全性考虑：

前端代码是公开的，存在被篡改的风险
权限相关操作（如赋予角色）必须在后端执行，确保安全性

数据一致性保障：

前端随时可能被关闭，或者在流程中途断网。依赖前端进行多步数据变更可能导致部分更新。
后端的数据库操作提供 ACID 事务支持，确保复杂数据操作的原子性。
必须同时成功或失败的多步数据变更（如订单创建 + 库存扣减）必须包裹在后端的行为流中执行。（注：行为流中的第三方 API 调用不受数据库事务控制，无法自动回滚）。

性能与架构：

计算应该尽量靠近数据存储的地方，以减少数据传输的开销和延迟。
复杂的计算、定时任务、批量处理等应该在服务器上执行。

能力边界划分

只能在前端执行：

UI 即时反馈（如显示/隐藏元素、页面跳转、滚动控制）
用户输入的实时验证行为（如格式检查）
前端状态管理（如页面变量）

只能在后端执行：

权限操作（如赋予角色、移除角色）
多步骤事务性工作流（如带库存扣减的订单处理）
定时任务（如每日报表生成、数据清理）
Webhook 回调处理
支付结果处理（涉及资金的操作必须在后端执行以确保安全）

两者都能执行：

数据库操作（增删改查）
第三方 API 服务调用
AI 智能体调用

注：对于这些操作，单步动作可以放在前端或后端。但是，多步操作应尽量放在后端以确保数据一致性。此外，从前端发起调用时，还需考虑 RPS（每秒请求数）的限制。

前端交互

前端交互直接配置在组件的属性面板中。

触发器类型

前端触发器根据触发时机可分为三类：

用户交互触发：

响应用户的直接操作（如点击、悬停、滚动、获得焦点），用于响应用户行为。

父子组件触发顺序：当父容器和子组件在视觉上完全重叠，且都配置了相同的触发器时，其执行机制会因触发器类型而异（如“点击时”与“悬停时”的处理逻辑不同）。关于重叠组件触发行为的具体执行与拦截规则，请查阅：行为列表。

状态变化触发：

响应组件状态的变化（如输入值变化、视频播放/暂停等），用于同步逻辑与数据或状态更新（如立即验证表单、触发依赖下拉框、在视频结束时显示“重播”按钮）。

生命周期触发：

在页面、应用或组件（暂未支持）的特定生命周期阶段自动触发，常用于初始化数据或清理资源。

完整的触发器列表及其适用场景请参考：触发器列表。

可执行的动作

前端动作在浏览器或移动端 App 中执行，主要分为四大类：

界面与本地操作：

导航：跳转页面、返回、打开链接等
提示与弹窗：显示提示、打开/关闭弹窗等
组件操作：设置输入值、滚动、切换视图、播放/暂停媒体等
操作系统 / 硬件交互：上传/下载文件、获取位置、分享、剪贴板等

状态管理：

变量控制：设置/清空页面变量、客户端变量等
数据源：刷新数据源等

后端调用：

账户：注册、登录、登出、重置密码等
数据库：创建、更新、删除数据、事务
行为流：触发后端工作流
API：调用预配置的 API 接口。当系统内置的行为无法满足需求时，API 是连接外部服务的工具，可用于查询天气、翻译文本、连接外部硬件等扩展功能。详情请参考：API 集成与调试
AI Agent：开始/继续/停止与 AI 智能体对话
支付：发起支付、处理退款（如微信支付、支付宝支付）

逻辑控制：

条件：条件分支处理
列表循环：遍历集合中的每个元素并执行动作

同步动作 vs 异步动作

在前端交互中，区分同步动作和异步动作非常重要：

同步动作会立即执行。这些动作不可被中断，且在它们之间无法插入其他操作。典型的例子包括：
- 显示提示
- 打开弹窗
- 跳转页面
这些动作会立即更新 UI 或改变应用状态，调用后即视为完成。
异步动作包含一个完整的生命周期：有开始、等待期间和结束——它们可能需要时间来完成，并支持成功/失败分支。例子包括：
- 后端操作如修改数据库
- 触发行为流
- 调用 API
对于异步动作，后续步骤通常取决于其执行结果（成功或失败），你可以为不同的结果配置不同的后续动作。

💡

完整的动作列表及其配置方法请参考：前端行为列表。

执行流程

配置前端交互时，多个动作可以组合使用。是否顺序或异步执行，取决于动作的嵌套方式。

顺序/串行执行

当动作嵌套在前一个动作的成功时或失败时分支下，会按顺序执行。

注意：并非所有动作都支持成功/失败分支。涉及需要等待响应的操作（如数据库、API、行为流、账户操作）具有这些分支，而即时 UI 操作（如跳转、显示提示）或变量设置则没有。

页面导航: 跳转页面、返回、打开链接。
数据库操作: 增删改查 (CRUD)、批量修改。
支付/登录: 微信支付、SSO 登录。
调用后端: 调用配置好的行为流 (Actionflow)。
调用 AI: 调用大模型 Agent。
界面反馈: Toast 提示、弹窗、抽屉。
状态管理: 设置页面变量、客户端变量。
组件控制: 滚动列表、重置表单、播放视频。
设备能力: 拨打电话、复制到剪贴板、扫码。

执行过程：

触发器触发后，执行动作 A
当 A 成功完成时，执行动作 B
当 B 成功完成时，执行动作 C
当 A 失败时（如返回错误、断网、超时），执行动作 D

适用场景：后续动作依赖前序动作的结果（如：先提交创建订单 → 等待成功并获取返回的 order_id → 携带该 ID 跳转到详情页）

并行/异步执行

当多个动作在同一层级（不嵌套在成功/失败分支内）时，它们被配置为异步执行。它们会按顺序依次开始，但不会等待前一个动作完成才开始下一个。


触发器
├─ 动作 A
├─ 动作 B
└─ 动作 C

执行过程：

触发器触发后，A、B、C 依次开始执行（先 A，然后 B，再 C）。
如果动作是异步的，流程不会等待它完成；它会立即开始下一个动作。
开始顺序是有保障的，但完成顺序不保证 - 动作将严格按照配置的顺序开始，但异步动作可能以任意顺序完成。
错误隔离 - 如果动作 A 发生错误（如请求超时），动作 B 和 C 依然会被执行。

适用场景：当动作是独立的，且不需要等待它们的结果时。例如先显示一个通知，然后刷新列表，接着跳转页面。

⚠️

竞态风险：如果异步执行的多个动作同时访问或修改相同数据，最终结果不可预测。在动作间有数据依赖关系时，避免配置为异步执行。

前端执行机制：串行与并行

并行: 同一个触发器下直接添加多个行为，它们会几乎同时开始执行（不保证结束顺序）。
串行 (回调): 利用行为的 成功时 和 失败时 回调，实现严格的顺序执行。在成功/失败分支下配置的动作，会在前一个动作完成后才执行。

示例：提交表单

场景：用户填写表单后点击提交按钮。

触发器：按钮的“点击时”。
动作 1 (调用后端)：调用名为“提交订单”的行为流，将表单数据传给后端。
动作 2 (界面反馈)：在动作 1 的“成功时”分支下，添加“Toast 提示”，显示“提交成功”。
动作 3 (页面导航)：在动作 2 之后（同样在成功分支下），添加“返回上一页”。

后端交互 (Actionflow)

后端交互需要在“行为流”面板中创建和编排，它更像是一个独立的逻辑程序。

执行过程说明：

用户点击提交按钮，触发”运行行为流”动作
等待行为流执行完成：
- 如果成功：异步执行三个动作（显示提示、跳转页面、刷新列表），它们会依次开始，且不等待彼此完成
- 如果失败：只显示错误提示

⚠️

注意：由于提示、跳转、刷新这三个动作被配置为异步执行，实际执行时页面会立即跳转，提示可能来不及显示。如果需要确保用户看到提示，可以通过使用“定时任务”处理。

这个例子展示了：

顺序/串行执行：先等待行为流完成
异步执行：成功后，多个 UI 动作不再互相等待执行
错误处理：失败时执行不同的逻辑

后端逻辑（行为流）

后端逻辑在行为流面板中配置。行为流运行在服务器上，支持多步骤业务逻辑编排。一次配置，随时调用。

触发器类型

行为结果

上下文中包含了上一步动作的执行结果。无论是前端串行执行，还是后端行为流节点，后一个节点都可以通过上下文获取前一个节点的执行结果。

前端示例: 第一步“调用行为流”返回了订单 ID，第二步“跳转页面”时，可以直接在上下文的“行为结果”中选择这个订单 ID 作为页面参数。
后端示例: 第一步“API 请求”获取了天气信息，第二步“修改数据”时，可以从上下文的“行为结果”中读取温度并写入数据库。

系统触发（自动触发，无需用户操作）：

定时任务（Cron）：按时间计划自动执行，用于周期性任务（如每日报表生成、数据清理）
Webhook：接收外部系统的 HTTP 回调，用于系统集成（如支付网关回调、第三方订单同步）
数据变更：由数据库数据变更自动触发，常用于自动化数据同步或级联更新（如新用户注册时赋予初始积分、同步数据到外部系统）

完整的行为流触发器类型列表及其适用场景请参考：行为流触发器列表。

可用节点类型

行为流是你实现复杂逻辑和编排多步流程的地方。你可以通过连接和配置不同的节点来实现。常见的节点类型包括：

数据库操作：

数据库增删改查

集成：

调用 API
调用其他行为流
运行 AI 智能体

逻辑操作：

条件
列表循环（For Each）
条件循环（While Loop）

特权操作（只能在后端执行）：

权限操作（如赋予/移除角色）
后端代码执行（代码块 Code Block）

其他常用节点：

获取用户信息（如用户 ID、微信 OpenID）
文件处理（保存图片、视频、文件等）

完整的节点类型列表请参考：行为流节点列表。如何构建行为流，请参考：构建行为流。

行为流执行模式

创建行为流时，必须选择其执行模式：

模式	响应方式	事务	超时限制	使用场景
同步	调用方等待结果	数据库操作支持 ACID 事务，支持回滚。其他操作按各自机制处理	整个行为流 15 秒（专属实例无限制）	如库存追踪、支付处理
异步	立即返回任务 ID。调用方不等待。	无事务	每个节点 15 秒（专属实例无限制）	长时间运行的任务（如 AI 智能体执行、视频生成）

目前AI节点必须在异步执行模式下才可以使用。

示例：支付 Webhook 处理行为流

场景：后端接收来自支付平台的支付结果回调。

配置信息：

触发器：Webhook
变量：status (文本)、message (文本)
输出：status (文本)、message (文本)

节点流程：


1. [代码块节点] extract_webhook_data
   功能：提取 webhook 数据
   输出：payment_status, order_id, payment_found

2. [条件节点] check_payment_found
   条件：payment_found = true
   
   ├─ TRUE 分支（存在支付记录）：
   │   3. [条件节点] check_payment_status
   │      条件：payment_status = "success"
   │      
   │      ├─ TRUE 分支（支付成功）：
   │      │   4. [数据库查询节点] query_payment
   │      │      查询：payment_record
   │      │      条件：order_id = extract_webhook_data.order_id
   │      │      输出：account_id
   │      │
   │      │   5. [数据库更新节点] update_account
   │      │      更新：account
   │      │      条件：account_id = query_payment.account_id
   │      │      更新：is_member = true
   │      │
   │      │   6. [设置变量节点] set_success
   │      │      设置：status = "支付成功"
   │      │
   │      │   7. [设置变量节点] set_message
   │      │      设置：message = "会员已激活"
   │      │
   │      └─ FALSE 分支（支付失败）：
   │          8. [设置变量节点] set_failed_status
   │             设置：status = "支付失败"
   │
   │          9. [设置变量节点] set_failed_message
   │             设置：message = "支付失败，会员未激活"
   │
   └─ FALSE 分支（订单不存在）：
       10. [设置变量节点] set_error_status
          设置：status = "订单不存在"

       11. [设置变量节点] set_error_message
          设置：message = "订单不存在，请重新下单"

12. [输出节点] 返回结果
   输出：{status, message}

行为结果与数据传递

行为结果是动作或节点在执行过程中产生的输出数据。它们是执行上下文的一部分。

除了行为结果，上下文还包括环境数据（如当前用户、当前时间、当前页面和组件等）。这些内容详见：数据绑定。

本节重点介绍动作如何产生结果，以及后续动作如何使用这些结果。

核心原则：

单向传递：数据只能从前序动作传递到后续动作
执行顺序决定访问权限：只有顺序执行的动作（非并行）才能访问前序结果
数据作用域（分支隔离）：行为结果具有局部作用域 - 分支（条件/循环）内创建的数据只在该分支内有效。
- 在循环分支内，系统会自动注入一个本地 当前项 上下文，供内部节点引用当前处理的项。
- 要访问或者向分支外传递数据，需使用全局作用域的变量：页面/客户端变量（前端）或行为流变量（后端）。

获取执行结果

通用输出规则：无论是在前端配置行为还是在后端配置节点，产生结果的底层逻辑是相同的：只有涉及查询、变更或处理数据的操作才会产生输出结果（如：数据库增删改查、API 调用、账号操作、代码块等）。仅用于控制界面交互、路由或内部逻辑流向的操作（如：跳转页面、显示提示、条件分支、循环、设置变量等）不会产生结果。

数据绑定路径：在配置后续步骤时，前序结果可通过以下数据绑定路径访问：

前端行为：上下文 → 行为结果 → 行为名称 → 字段名
后端行为流：行为流数据 → 节点名称 → 字段名

各类行为及节点的完整输出字段说明，请参考：行为流节点列表和前端行为列表。