iii-state-reactions

状态反应

类似于：Firebase onSnapshot、Convex mutations

核心概念

在适合任务时使用以下概念。并非每个状态反应都需要涵盖所有概念。

• 状态触发器会在被监视范围内的值发生变化时触发
• 处理器会收到用于描述变更的 { new_value, old_value, key, event_type }
• condition_function_id 控制是否执行——只有条件返回真值时，反应才会触发
• 多个反应可以独立监视同一范围
• 反应会在 state::set、state::update 和 state::delete 操作时触发

架构

state::set / state::update / state::delete
  → StateModule 发出变更事件
    → registerTrigger type:'state'（范围匹配）
      → condition_function_id 检查（如果已配置）
        → registerFunction 处理器（{ new_value, old_value, key, event_type }）

使用的 iii 原语

原语	用途
registerFunction	定义反应处理器
registerTrigger({ type: 'state' })	监视范围内的变更
config: { scope, key, condition_function_id }	范围筛选器和可选条件门控
事件载荷：{ new_value, old_value, key, event_type }	传递给处理器的变更详情

参考实现

完整可运行示例请参阅 ../references/state-reactions.js：该反应会监视一个状态范围，并在值发生变化时触发副作用，还带有可选的条件门控。

也提供 Python 版本：../references/state-reactions.py

也提供 Rust 版本：../references/state-reactions.rs

常见模式

使用此模式的代码通常会在适用时包含：

• registerWorker(url, { workerName }) — 初始化 worker
• registerFunction(id, handler) — 定义反应处理器
• registerTrigger({ type: 'state', config: { scope, key, condition_function_id } }) — 监视变更
• payload.new_value / payload.old_value — 比较变更前后的值
• payload.event_type — 区分 set、update 和 delete 事件
• trigger({ function_id: 'state::set', payload }) — 从反应中写入派生状态
• const logger = new Logger() — 为每个反应进行结构化日志记录

调整此模式

在适用于任务时使用以下调整方式。

• 将 scope 设置为监视特定领域（例如 orders、user-profiles）
• 使用 key 将反应范围缩小到某个范围内的单个键
• 添加 condition_function_id 进行筛选——只有条件函数返回真值时才作出反应
• 在一个处理器中写入状态，以触发另一个作用于不同范围的反应，从而串联反应

引擎配置

必须在 iii-config.yaml 中启用 StateModule，状态触发器才能触发。完整的带注释配置参考请参阅 ../references/iii-config.yaml。

模式边界

• 如果任务是直接读取或写入状态，而不需要反应，请优先使用 iii-state-management。
• 如果任务需要在多种触发器类型之间共享条件触发逻辑，请优先使用 iii-trigger-conditions。
• 当主要需求是对状态变化自动触发副作用时，请使用 iii-state-reactions。

何时使用

• 当任务主要涉及 iii 引擎中的 iii-state-reactions 时，使用此技能。
• 当请求直接要求使用此模式或实现等效方案时触发。

边界

• 切勿将此技能用作无关任务的通用回退方案。
• 如果有更具体的 iii 技能更适合，就不得使用此技能。
• 应用此技能中的示例前，务必先确认环境和安全约束。