org.squirrelframework.foundation 是 Squirrel Framework（松鼠框架） 的核心基础包，该框架是一个轻量级的 Java 开发框架，专注于提供 领域驱动设计（DDD）支持、事件驱动编程（EDP）能力 及相关工具类。

org.squirrelframework.foundation.fsm 

是 Squirrel Framework 中负责有限状态机（Finite State Machine, FSM） 实现的核心包，提供了一套灵活、可扩展的状态机框架，用于简化复杂业务状态流转逻辑的开发。

状态机在业务系统中应用广泛，例如：订单状态流转（创建→支付→发货→完成）、工作流审批流程、设备状态管理等场景，通过状态机可以将状态变更逻辑清晰分离，提高代码可读性和可维护性。

概念	说明	核心接口 / 类
状态（State）	表示业务对象所处的状态（如订单的 "已创建"、"已支付"）	通常用枚举或自定义类实现，无强制接口
事件（Event）	触发状态变更的动作（如 "支付" 事件触发订单从 "已创建" 到 "已支付"）	通常用枚举或自定义类实现
上下文（Context）	状态转换时携带的数据（如订单 ID、操作人等）	可自定义类型
状态机（StateMachine）	核心控制器，管理状态流转、事件触发、状态监听等	StateMachine 接口
状态转换（Transition）	定义从一个状态到另一个状态的规则（源状态→目标状态，由特定事件触发）	内部通过 Transition 类管理
监听器（Listener）	监听状态转换过程中的事件（如状态变更前 / 后执行逻辑）	StateMachineListener 接口

核心类与接口解析

1. StateMachine 接口

状态机的核心接口，定义了状态机的基本操作：

• fire(event, context)：触发事件，执行状态转换
• getCurrentState()：获取当前状态
• start()：启动状态机
• stop()：停止状态机

2. StateMachineBuilder 接口

用于构建状态机的建造者接口，通过链式调用定义状态转换规则：

• withInitialState(initialState)：设置初始状态
• transit(from, on, to)：定义状态转换（从 from 状态，通过 on 事件，转换到 to 状态）
• withListener(listener)：注册状态监听器
• build()：创建状态机实例

3. StateMachineListener 接口

状态机事件监听器，可通过实现该接口监听状态转换过程：

• beforeStateChange(...)：状态转换前触发
• afterStateChange(...)：状态转换后触发
• whenExceptionThrown(...)：状态转换发生异常时触发

一个简单的订单状态流转逻辑：

• 状态：CREATED（已创建）→ PAID（已支付）→ SHIPPED（已发货）→ DELIVERED（已送达）
• 事件：PAY（支付）、SHIP（发货）、DELIVER（送达）

在 Squirrel Framework 的状态机模块中，StateMachineParameters 是一个用于封装状态机核心参数的工具类，主要用于定义状态机的状态类型（S）、事件类型（E） 和上下文类型（C） 这三个核心泛型参数

externalTransition 会导致状态机的当前状态发生变更，并完整触发状态转换的生命周期（包括离开源状态、执行转换动作、进入目标状态等环节）。

fire(event, context) 方法是状态机触发事件的核心入口，它会按照预定义的规则自动调用所有与该事件相关的注册逻辑（包括条件校验、转换动作、状态生命周期方法和监听器）。这种机制使得状态流转的逻辑与触发方式解耦，符合 “事件驱动” 的设计思想，简化了复杂状态管理的实现。