用户行为

用户行为涵盖身份认证、资料维护和账户安全管理，可用于构建完整的用户体系。

刷新当前用户数据

重新获取并更新当前用户的最新数据。

常用场景

• 当用户修改个人资料（如用户名、头像）成功后，刷新当前用户数据，让页面展示最新内容。

参数配置

无

运行结果与输出

无

运行机制

• 工作原理：

  • 行为触发后，系统向服务端发起数据查询（操作名称为 zvmAccount）。
  • 服务端从请求中解析出账户 id。然后将其作为过滤条件从账户表查询数据。
  • 将查询到的账户数据和用户的权限角色列表合并后，返回给前端页面。
  • 前端使用返回结果更新当前用户数据。

• 边界限制：

  • 如果访客处于未登录（游客）状态，该行为依然会向服务端触发一次网络请求。由于不存在帐户 id，后端会返回空对象，前端会使用该空对象更新当前用户数据，不会报错。

常见错误

• 网络连接或服务端 / 权限异常：包括用户设备断网、弱网、请求网关失败，或请求触发 RPS 限制、权限限制这些情况。系统会采用绝对静默捕获机制，不会在界面上弹出任何提示，也不会打断行为流，后续行为会继续执行。但是当前用户数据的刷新自动中止，保持旧状态。

示例

获取用户微信头像与昵称

用于快速获取用户微信头像和昵称。

常用场景

• 在个人中心页引导用户补全微信头像与昵称以作个性化展示
• 在发布评论、帖子或加入群组前，强要求补全用户基础信息

参数配置

无

运行结果与输出

• 结果：无
• 成功时：用户在补全头像与昵称，点击确认保存，新数据自动写入账户表并安全返回原页面，然后行为流转入 成功时 分支。

运行机制

• 工作原理：

  • 登录态校验：行为触发后，系统首先检查用户是否登录。若未登录，则直接拦截并展示“请先登录”的 Toast 提示，中断逻辑执行。（由于用户会在应用加载完成时自动静默登录，所以中断逻辑通常不会触发）。
  • 页面跳转：校验通过后，自动页面跳转至资料补全页面（Zion 内置，开发者无法自定义）。
  • 预填现有资料：系统会自动从账户表拉取当前用户的头像和用户名，并在界面中预先展示。
  • 微信原生信息采集：
    • 头像选择：点击头像组件时，调起微信原生的头像选择框，用户可直接选用微信头像或本地相册图片。
    • 昵称填写：点击昵称输入框时，调起微信原生键盘一键回填其微信昵称。
  • 数据保存与流转：
    • 用户点击页面底部的“保存”按钮时，系统会自动将新头像和用户名写入账户表。
    • 保存成功后，自动退出该页面，并流转入 成功时 分支。

• 边界限制：

  • 中途取消：用户在内置页面点击“取消”按钮，或通过微信左上角返回键/滑动手势直接退出资料设置页。此时该行为在原页面静默终止，不会流转入 成功时 分支。

常见错误

• 获取现有资料失败：在页面初始化拉取已有资料时，若因网络异常导致请求失败，系统会弹出 Toast 提示“用户信息查询请求失败”或“用户信息查询请求结果错误”；若用户曾经保存过损坏的头像数据，会提示“用户头像数据错误”。此时资料预填会失效，但不影响用户继续填写新资料。
• 未填写完整拦截：若用户未选择头像或未输入昵称就点击“保存”，系统会拦截并弹出 Toast 提示“请填入头像和昵称”，且不会提交保存。
• 头像上传失败：当用户选择完图片并由底层将其上传至云端对象存储时，若发生断网或上传异常，系统会直接弹出带有底层报错信息的 Toast（提示详细的 Error 信息），图片选择不会生效。
• 服务器更新失败：当用户点击保存按钮提交新头像和昵称时，若由于网络异常、数据库连接问题或触发了安全限制（RLS），导致数据写入账户表失败。页面会弹出 Toast 提示“修改用户信息失败”，此时页面无法关闭，且行为流会继续保持挂起状态。

示例

获取手机号

拉起微信授权弹窗，一键获取用户绑定的手机号。

常用场景

• 绑定手机号的流程中，让用户一键完成号码填报。
• 创建预约单、提交快递收件信息前一键导入联系方式。

参数配置

• 入参：

运行结果与输出

• 结果：无
• 成功时：用户在弹窗中点击“允许”，系统成功解析出明文手机号并自动赋值给上面配置的变量后，流转入 成功时 分支。

运行机制

• 工作原理：

  • 查找微信行为：Zion 引擎扫描触发器为 点击时 的行为流最外层，检查是否包含获取手机号行为。
  • 执行顺序逆转：行为流并不会按照你在编辑器里配置的顺序从上到下执行！而是首先触发微信的原生弹窗。即使你把获取手机号放在行为流的最后一步，微信弹窗依然会在用户点击的瞬间第一个弹出来。
  • 后端解密与回填：当用户同意授权后，系统将微信下发的密文发送到 Zion 后端进行解密。解密成功后，明文手机号覆盖写入变量。
  • 流转成功：只有在解密与赋值全部成功完成后，系统才会“放行”，正式从上到下执行你在编辑器中配置的整条行为流（此时再执行到获取手机号节点时，该节点不会被执行，而是直接流转入 成功时 分支）。
  💡

  “获取手机号”只能直接配置在组件的 点击时 事件下，并且必须位于行为流最外层。不能将它配置在其他行为的 成功时、失败时、条件分支、循环或其他嵌套位置；编辑器会对不符合要求的配置报错。

常见错误

• 微信主体资质未满足：只有已认证的企业、政府、媒体或非营利组织主体的小程序才可合法调用获取手机号接口。个人主体小程序在运行该行为时将直接报错拒绝。
• 配置位置不正确：若“获取手机号”不是直接配置在组件的 点击时 事件最外层，编辑器会报错，且不允许保存该配置。
• 用户拒绝授权：当用户在弹窗中点击“拒绝”或关闭弹窗时。这属于正常的用户终止操作。由于底层的错误捕获并未接入系统的 Toast 提示，因此界面上不会弹出任何报错信息（绝对静默），但整条行为流会被丢弃，不再执行。
• 后端解密失败：由于网络断开、或者后端的解密失败等原因，导致获取不到真实手机号。此时底层会捕获错误并执行拦截，界面上不会有任何弹窗提示（绝对静默），同时行为流被完全中断抛弃。

示例

发送验证码

生成并向目标手机或邮箱发送 6 位数字验证码（有效期为 5 分钟）。

常用场景

• 登录、注册、修改密码、注销等敏感节点的用户身份校验。

参数配置

运行结果与输出

• 结果：无
• 成功时：系统成功生成验证码并发出，流转入 成功时 分支。
• 失败时：因号码为空、格式错误、短信余额不足或发送过于频繁导致失败，系统流转入 失败时 分支。

运行机制

• 工作原理：

  • 云端生成与绑定：触发该行为后，Zion 云端服务器会生成一个安全的 6 位纯数字验证码，并将其与目标手机号 / 邮箱以及选定的使用场景一起写入高速缓存中进行强绑定。该验证码的有效过期时间严格设定为 5 分钟。
  • 发送过程：
    • 若选择 短信 / 邮件：直接调用 Zion 官方的基础服务通道发送给用户（发送短信会消耗项目所在空间的短信额度）。
    • 若选择 自定义配置：系统会将 发送给、验证码、场景 作为变量，传递给自定义行为流，由开发者自己对接第三方平台（如阿里云）来发送出去。

• 边界限制：

  • 发送频率限制（1分钟冷却）：为防止恶意刷短信，Zion 底层对所有验证码接口强制设定了 1 分钟的最小发送间隔（冷却期）。如果用户在 1 分钟内对同一个手机号 / 邮箱重复触发“发送验证码”，后端会直接拦截并抛出请求过于频繁的错误。
  • 强场景锁定限制（易错点）：生成的验证码和参数中选择的 场景 严格绑定。例如：发送时选择“注册”场景，后续却调用“登录”相关行为进行校验，即使验证码数字正确，系统也会判定校验失败。前后配置的场景必须完全一致。

配置说明

若使用“自定义”发送方式，需依次完成以下 3 步配置：

第一步：创建发送行为流

• 新建自定义行为流，添加 3 个入参：接收账号、验证码、使用场景。
• 在自定义行为流添加发送节点，可使用内置的阿里云发送短信  / 阿里云发送邮件  / Twilio 发送短信  节点，或通过 API 等其他通道发送验证码。
• 将上述入参绑定到发送节点的对应参数上。

第二步：添加自定义配置

• 进入 设置 → 验证码，并添加自定义配置。
• 填写基础信息：
  • 名称：配置的名称（如：腾讯云短信）。
  • 发送验证码的行为流：选择【第一步】创建的行为流。
  • 行为流输入： 在数据绑定菜单的「常量」分类下，将 发送目标、验证码、场景 分别绑定到行为流的 接收账号、验证码、使用场景 入参。

第三步：使用自定义配置

在发送验证码行为的“自定义配置”中选择刚添加的自定义配置。即可使用自定义配置发送验证码。

常见错误

• 自动弹窗报错：当发送失败时（例如手机号为空、格式不对、触发了发送频率限制、或者短信包余额不足），除了进入 失败时 分支外，Zion 底层会自动弹出一个系统 Toast 提示（如 “Too Many Requests” 或对应的中文错误）。开发者无需在 失败时 分支中重复配置“显示提示”，以免出现双重报错弹窗。
• 发送过于频繁 (ALIYUN_SMS_VERIFICATION_CODE_REQUEST_TOO_FREQUENT)：同一手机号在一分钟内重复请求验证码时触发。建议在发送按钮上增加 60 秒倒计时，避免用户重复提交。

示例

校验验证码

对用户输入的手机短信验证码进行单步真伪和有效性校验。

常用场景

• 在高敏感的领券、限量预约、资产提现等业务发生前，进行短信二次校验防刷。

参数配置

• 入参：

运行结果与输出

• 结果：无
• 成功时：系统判定验证码和目标手机匹配且未超时。后端将自动“消费”并废弃此码，同时进入 成功时 分支继续运行后续行为（如提交订单）。
• 失败时：验证码不匹配、已过期、或网络异常导致校验未通过，系统将直接中断流转，并进入 失败时 分支。

运行机制

• 工作原理：
  • 一次性消费核销：触发后，系统向后台发送包含手机号和验证码的核销请求。服务端会跟缓存中的手机号、验证码进行严格匹配。若一致，则立刻将此验证码作“一次性消费”（即从缓存中彻底抹除，防止黑客进行多重提交或重放攻击），并放行通过。

常见错误

• 系统绝对静默：与发送验证码不同，当校验验证码失败时（如输入的验证码错误、手机格式错误、或是同一个验证码被使用了第二次），不会在界面上自动弹出任何报错 Toast！它只会静默地流转进 失败时 分支。
• 排查与配置建议：由于系统完全静默，如果未在 失败时 分支配置任何行为，用户填错验证码后页面会毫无反应。建议添加显示提示行为（如“验证码错误或已失效，请重试”），形成完整的交互闭环。

示例

注册

在应用中创建新用户账号。

常用场景

• 手机号快速注册：用户首次打开 Web 应用，通过手机号和验证码快速创建账号。
• 邮箱密码注册：网页端用户使用邮箱、密码和邮箱验证码进行账号注册。

参数配置

• 前置条件：若使用手机号或邮箱注册，必须在注册行为前执行「发送验证码」行为，获取用于验证身份的验证码。

• 参数：

根据选择的注册方式，需要绑定以下参数：

用户名注册：

邮箱注册：

手机号注册：

运行结果与输出

• 结果：无
• 成功时：注册成功后，系统会自动登录该用户，并刷新当前用户数据。然后转入 成功时 分支。
• 失败时：因信息重复、格式错误、网络异常等导致注册失败时，系统将中断逻辑，转入 失败时 分支。

运行机制

• 凭证加密存储：系统在将新用户信息写入数据库前，会自动对用户设置的明文密码进行加盐哈希（Hash）单向加密处理，数据库中仅存储密文，保证数据安全。
• 原子化注册与登录：注册请求在后端是一个原子操作。账户创建成功后，后端会直接签发该用户的会话令牌，前端接收到后即刻建立登录状态，无需用户再次手动触发登录行为。
• 默认角色分配：新创建的用户账号会自动被系统赋予 Logged-in User 角色，以获取对应的基础访问权限。
• 验证码单次消费：若使用手机号或邮箱注册，后端在校验验证码通过后会立刻将其作“一次性消费”核销，防止恶意重放攻击。

边界情况

• 未配置登录方式阻断：如果在项目的登录设置中未开启对应的注册方式，即使前端触发了注册行为，后端也会在网关层直接拒绝创建该类型的账号。

特殊说明

• 游客状态平滑过渡：注册前用户处于游客状态，可能已经产生了一些临时业务数据（如游客购物车）。注册成功并自动登录后，系统不会自动将游客期的数据合并到新账号下；如需合并，可在注册后的 成功时 分支中通过额外的数据修改行为完成归属权转移。

常见错误

示例

登录

已注册用户通过用户名、手机号、邮箱、验证码等方式登录应用。支持用户名密码、手机号验证码、手机号密码、邮箱密码、微信扫码、微信授权多种方式。

常用场景

• 应用进入首页时，要求用户先登录以访问个性化内容。
• 用户在提交表单或发帖操作前，需要完成登录行为以进行身份校验。

参数配置

• 入参配置：

根据选择的登录方式，需要绑定以下不同的参数：

用户名登录：

手机号密码登录：

手机号验证码登录：

邮箱登录：

单点登录或注册（详情见设置 SSO ）：

微信扫码登录：

微信授权登录：无参数配置

运行结果与输出

• 结果：无
• 成功时：登录验证通过时触发。
• 失败时：验证未通过、账号不存在或网络异常时触发。建议配置为弹出错误提示或清空输入框。

运行机制

• 工作原理：
  • 客户端将用户输入的账号标识与凭证发送至后端，系统在数据库中检索匹配的账号并比对密码或验证码。验证通过后，生成登录状态并返回给客户端。
  • 微信互通机制：微信扫码登录的跨客户端帐号互通，是通过 UnionID 机制，系统将同一微信用户在不同客户端（如 Web 扫码、小程序、公众号 H5）的账号自动关联。

常见错误

示例

静默登录

在小程序应用加载时，自动完成用户登录。Zion 将该行为强制添加在 应用加载完成时 事件下，开发者无法编辑和删除，也无法自行添加。

因此，在小程序端，所有用户均为已登录状态，没有游客状态。

常用场景

无

参数配置

无

运行结果与输出

无

运行机制

• 工作原理：
  1. 在 应用加载完成时 触发后，系统调用微信小程序的 wx.login 接口得到临时登录凭证 Code。整个过程无需开发者手动配置，也无需用户进行任何点击操作。
  2. 后端向微信服务器发起请求，用临时登录凭证 Code 安全地换取该微信用户针对当前小程序的唯一标识 Open ID。
  3. Zion 后端在数据库中检索是否存在与该 Open ID 绑定的用户账号。如果存在，则直接登录该账号。若不存在，且未配置多端账号互通，系统会在后台自动为该用户注册并创建一个全新的系统账号，然后自动登录。
  Open ID 是微信生态中用于标识用户的唯一凭证。该凭证具有小程序隔离性，同一个微信用户在不同的小程序中，其 Open ID 是完全不同的。

常见错误

• 暂无特殊错误说明

示例

登出

清除本地用户的登录状态。

常用场景

• 提供退出登录按钮，供用户主动退出当前账号。
• 在个人中心提供账号切换功能，先执行登出清理。

参数配置

无

运行结果与输出

无

运行机制

• 工作原理：
  • 清除本地凭证：行为触发后，立即彻底清空保存在本地缓存或 Cookie 中的用户数据。
  • 广播状态变更：触发状态通知，让所有依赖当前用户数据的页面组件、变量和条件分支立即更新。当前用户数据恢复为游客状态，相关界面随之重新渲染（例如原本展示用户昵称的组件将显示为空值或默认提示）。

常见错误

• 离线执行无阻碍：由于该行为是纯前端的本地状态清理和缓存重置操作，不需要向服务端发起网络请求。因此在设备断网、弱网等极端离线环境下依然能够无条件成功执行，不会出现加载挂起或网络报错打断逻辑的情况。
• 延迟请求凭证失效：登出成功后本地存储的令牌被立刻抹除。如果当前页面有其他尚未执行完毕、或通过定时器延迟触发的异步数据查询行为，这些请求在发送时将无法携带有效的身份凭证，导致被服务端网关拦截并触发 401 未授权报错。在设计上应尽量避免在登出行为之后配置其他需要用户凭证的串行逻辑。

示例

绑定

将当前登录的系统账号与手机号、邮箱或第三方单点登录账号进行关联。

常用场景

• 绑定手机号：用户通过微信快捷登录后，绑定个人手机号码，用于接收短信通知。
• 绑定邮箱：用户绑定个人邮箱，用于接收系统通知，或者作为备用登录凭证。

参数配置

• 入参配置：

运行结果与输出

• 结果：绑定手机号与绑定邮箱无直接前端出参。单点登录绑定会触发页面重定向。

运行机制

• 工作原理：
  • 绑定手机号：Zion 自动处理用户登录态。后端接收到请求并自动将手机号码标准化为 E.164 国际格式。校验短信验证码有效后，系统将手机号与当前账号关联。
  • 绑定邮箱：Zion 自动处理用户登录态。后端校验邮箱验证码有效后，将邮箱地址与当前账号关联。绑定行为本身不进行邮箱格式强校验。
  • 单点登录绑定：这是一个重定向流程。用户触发行为后，系统将用户重定向至单点登录服务商的授权页面。完成授权后，服务商将用户重定向回 Zion 指定的目标页面，并在后台执行成功时行为流，完成账号关联。

常见错误

• 暂无特殊错误说明

示例

解绑

解除当前登录账号与手机号、邮箱或单点登录账号的绑定关系。

常用场景

• 更换绑定联系方式：先解绑当前手机号/邮箱，再绑定新手机号/邮箱。

参数配置

• 入参配置：

运行结果与输出

• 结果：无
• 成功时：解绑成功时触发。
  解绑成功后，前端不会自动更新当前用户数据。建议在 成功时 分支调用 刷新当前用户数据，或者重新加载页面，否则界面仍会显示已解绑的手机号。

运行机制

• 工作原理：
  • 对于手机号和邮箱解绑，后台设置中必须开启对应的验证码登录功能。系统在验证验证码或确认 SSO 账号信息后，会检查该账号是否还有其他可用的登录方式。
  • 如果解绑的是当前唯一的登录方式，系统会拒绝解绑并回滚事务，以防止账号变成无法登录的死账号。

常见错误

• 未登录错误 (HTTP 403 / ACCOUNT_NOT_AUTHENTICATED)：用户未登录时调用，系统拒绝执行。
• 验证码错误 (HTTP 400)：输入的验证码错误或已过期，系统返回 HTTP 400 错误（VerificationCodeAuthenticationException）。
• 唯一登录方式限制 (HTTP 403 / UNBIND_ONLY_LOGIN_METHOD)：若该凭证是当前账号唯一的登录方式，系统会取消解绑操作。
• SSO 配置不存在 (HTTP 500 / SSO_ID_NOT_FOUND)：SSO解绑时，如果选择的配置不存在，系统返回 HTTP 500 错误。
• 账号不存在错误 (HTTP 404 / EntityNotExistsException)：执行操作时发现当前登录的账号本身不存在。

示例

重置密码

通过验证码核验身份并重设登录密码。平台提供“手机号重置密码”与“邮箱重置密码”两个独立行为，暂不支持直接用旧密码修改新密码。

常用场景

• 用户忘记密码时，通过已绑定的手机号或邮箱接收验证码找回并重新设置密码。
• 在安全中心，通过验证码核验身份后主动修改密码。

参数配置

• 入参配置：

运行结果与输出

• 结果：无直接前端出参。
• 成功时：重置密码成功。建议在 成功时 分支配置页面跳转，将用户重定向至登录页并要求其重新登录。
• 失败时：验证码失效、格式不符或网络异常导致重置失败，建议配置为弹出错误提示。

运行机制

• 工作原理：
  • 验证码单次消费：行为触发后，系统比对接收目标与验证码记录。校验通过后，该验证码立即失效，防止重复核销。
  • 密码覆盖存储：系统复用原有加密盐值对新密码进行加密处理，覆盖数据库中的旧密码。

常见错误

• 验证码错误或失效：输入的验证码错误或已过期，系统返回错误，进入 失败时 分支。
• 未登录/账号不存在：对未绑定相关手机/邮箱或非活跃账号执行重置，系统拒绝该操作。

示例

注销

用于用户自主销户。

常用场景

应政策与合规要求（如个人信息保护法），在用户设置中提供账号注销通道。

参数配置

• 入参配置：

运行结果与输出

• 结果：无直接输出数据。
• 成功时：系统自动比对验证码或密码。验证通过后，后端执行账号软删除。前端立即执行登出行为，用户退回游客状态。系统不会自动弹出“注销成功”提示，也不会自动跳转。建议在注销行为后，手动配置“显示提示（Toast）”和“跳转页面”行为。
• 失败时：验证失败或网络异常时，注销中止，用户保持登录状态。系统会自动弹出错误提示，固定显示 3 秒。

运行机制

• 运行机制与数据变动：
  • 账号软删除：注销后会清空绑定的第三方账号授权信息（如微信授权），清空手机号和邮箱，使用随机字符串重置登录名和密码，并将账号状态变更为 DELETED。
  • 业务数据残留：系统仅对账户表及凭证表（未暴露）执行更新。自定义业务表（如订单、评论）中的数据不会被自动级联删除或脱敏。开发者可自行通过触发器或 Actionflow 清理。
• 异常边界：
  • 未登录：抛出 Account not authenticated。
  • 账号未绑定对应联系方式：抛出 PHONE_NUMBER_NOT_FOUND 或 EMAIL_NOT_FOUND。
  • 对已注销账号重复操作：抛出 account already deleted。
  • 验证码错误：抛出 bad verification code。

常见错误

• 暂无特殊错误说明

示例