状态机（FSM）与 DDD 框架集成技术方案

目录

1. 背景与目标
2. 现状分析
3. 整体架构设计
4. 核心模块设计
5. 与 DDD 框架的集成方案
6. 实施计划
7. 风险与应对

1. 背景与目标

1.1 背景

Matrix Framework 已具备：

• 完整的 DDD 分层架构（Adapter / Application / Domain / Infrastructure）
• 基于 Avro IDL 的领域建模 DSL
• 基于 COLA StateMachine 封装的状态机组件（easy-flows 模块）

但当前状态机与 DDD 框架之间存在断层：

• 领域服务中状态校验依赖硬编码和程序员自觉，缺乏机制化保障
• 聚合根的状态字段与状态机没有自动关联

1.2 目标

将状态机能力无缝融入 DDD 框架，实现：

2. 现状分析

2.1 现有状态机能力（easy-flows 模块）

基于 COLA StateMachine 二次封装，核心类位于 components/easy-flows/src/main/java/io/matrix/flows/fsm/：

flowchart LR
    subgraph "easy-flows fsm 模块"
        Fsm["Fsm<br/>状态机核心<br/>· fireEvent 触发转换<br/>· readyEvent 判断可执行<br/>· checkReadyEvent 校验<br/>· readyEvents 获取可执行列表<br/>· generatePlantUML 生成状态图"]
        FsmBuilder["FsmBuilder<br/>状态机构建器<br/>· external 外部转换<br/>· internal 内部转换<br/>· condition 条件判断<br/>· perform 动作回调"]
        Transit["Transit<br/>单次转换模型<br/>from / to / event / metadata"]
        Transits["Transits<br/>转换集合<br/>· isReady4Event<br/>· getEvents / getFromStates"]
        ReadyEventVisitor["ReadyEventVisitor<br/>计算可执行事件的访问者"]
        PlantUMLVisitor["PlantUMLVisitor<br/>生成 PlantUML 状态图"]
    end

    FsmBuilder -->|构建| Fsm
    Fsm -->|使用| ReadyEventVisitor
    Fsm -->|使用| PlantUMLVisitor
    ReadyEventVisitor -->|输出| Transits
    Transits -->|包含| Transit

已覆盖的核心能力：

• ✅ 构建全状态迁移图（generatePlantUML()）
• ✅ 根据当前状态判断可以执行操作（readyEvents(S, C)）
• ✅ 检验当前状态是否可执行某操作（readyEvent() / checkReadyEvent()）

2.2 现有 DDD 框架结构

flowchart LR
    subgraph "kernel-domain 模块"
        AggregateRoot["AggregateRoot 接口<br/>· identifier()"]
        Stateful["Stateful<S> 接口<br/>· getStatus()<br/>· setStatus(S)"]
        AggregateBase["AggregateBase 抽象基类"]
        BaseRepository["BaseRepository 接口"]
        BaseService["BaseService<br/>· publish() 事件发布<br/>· CommandBus 命令总线"]
        BaseDomainService["BaseDomainService<br/>· 持有 repository"]
        StatefulDomainService["StatefulDomainService<br/>· 状态机校验/触发/查询"]
        BaseAppService["BaseAppService<br/>应用服务基类"]
    end

    AggregateBase -.-> AggregateRoot
    BaseDomainService --> BaseService
    StatefulDomainService --> BaseDomainService
    BaseAppService --> BaseService
    BaseDomainService --> BaseRepository

关键改进：

• 新增 Stateful<S> 接口，聚合根实现后可直接获取/设置状态
• 新增 StatefulDomainService，提供状态机校验、转换、查询能力

2.3 已实现的状态机功能

3. 整体架构设计

3.1 分层架构图

flowchart LR
    subgraph "定义层（FsmDefinition）"
        B1["FsmDefinition<br/>状态机完整定义<br/>· 聚合根类型<br/>· 状态字段<br/>· 状态枚举/事件枚举<br/>· 初始状态<br/>· 转换规则列表"]
        B2["TransitionDef<br/>单条转换定义<br/>· fromStates 源状态列表<br/>· toState 目标状态<br/>· event 触发事件<br/>· condition 条件<br/>· action 动作"]
    end

    subgraph "注册层（FsmRegistry）"
        C1["FsmRegistry<br/>状态机注册中心<br/>· 按聚合根类型注册<br/>· 按名称注册"]
    end

    subgraph "构建层（代码方式）"
        G1["子类实现 buildFsm()<br/>使用 FsmBuilder 构建状态机"]
    end

    subgraph "运行层（状态机执行）"
        D1["StatefulDomainService<br/>带状态机的领域服务基类<br/>· getFsm() 获取状态机<br/>· checkTransition() 校验转换<br/>· fireTransition() 执行转换<br/>· listAvailableTransitions() 查询可执行操作"]
        D2["Fsm<br/>已有状态机核心（复用）"]
    end

    subgraph "领域层（DDD）"
        E1["AggregateRoot & Stateful<S><br/>聚合根（含状态字段）"]
        E2["BaseDomainService<br/>已有领域服务基类（复用）"]
        E3["Repository<br/>仓储"]
    end

    G1 -->|构建| D2
    B1 -->|包含| B2
    D2 -->|注册到| C1
    D1 -->|继承| E2
    D1 -->|获取| C1
    D1 -->|操作| E1
    E1 -->|持久化| E3

3.2 核心流程

3.2.1 状态机构建流程

flowchart LR
    Start["开始"] --> Subclass["子类继承 StatefulDomainService"]
    Subclass --> BuildFsm["实现 buildFsm() 方法<br/>使用 FsmBuilder 构建 Fsm"]
    BuildFsm --> InitFsm["@PostConstruct 自动调用 initFsm()"]
    InitFsm --> Register["注册到 FsmRegistry"]
    Register --> Done["完成"]

3.2.2 领域操作中的状态机使用流程

flowchart LR
    Cmd["收到 Command"] --> Load["加载聚合根"]
    Load --> Check["checkTransition(aggregate, event)<br/>校验当前状态是否允许执行目标事件"]
    Check -->|校验失败| Err["抛出 IllegalStateException"]
    Check -->|校验通过| Business["执行业务逻辑"]
    Business --> Fire["fireTransition(aggregate, event)<br/>触发状态转换，自动更新聚合根状态字段"]
    Fire --> Save["持久化聚合根"]
    Save --> Publish["发布领域事件"]
    Publish --> End["返回结果"]

4. 核心模块设计

4.1 模块划分

flowchart LR
    subgraph "easy-flows（已有，不改动）"
        FsmMod["fsm/ 包<br/>Fsm, FsmBuilder, Transit, Transits, Visitor"]
    end

    subgraph "kernel-domain（新增 stateful 包）"
        StatefulItf["Stateful<S> 接口<br/>聚合根状态访问"]
        Reg["FsmRegistry 接口<br/>+ DefaultFsmRegistry 默认实现"]
        Def["FsmDefinition 模型<br/>FsmDefinition, TransitionDef"]
        Service["StatefulDomainService 基类<br/>带状态机的领域服务"]
        Auto["FsmAutoConfiguration<br/>Spring Boot 自动配置"]
    end

    subgraph "业务模块（如 pulse-domain）"
        BizAggregate["Requirement<br/>implements AggregateRoot, Stateful<Status>"]
        BizService["RequirementDomainService<br/>extends StatefulDomainService"]
    end

    kernel-domain --> easy-flows
    BizAggregate --> kernel-domain
    BizService --> kernel-domain

4.2 核心类设计

4.2.1 Stateful — 有状态的聚合根接口

public interface Stateful<S> {
    S getStatus();
    void setStatus(S status);
}

接口: FsmRegistry
├── get(Class<T> aggregateClass) → Fsm<S,E,T>
│   按聚合根类型获取状态机
├── get(String fsmName) → Fsm<S,E,T>
│   按名称获取状态机
├── register(Class<T> aggregateClass, Fsm fsm) → void
│   按聚合根类型注册
└── register(String fsmName, Fsm fsm) → void
    按名称注册

默认实现: DefaultFsmRegistry
└── ConcurrentHashMap 缓存

BaseService
├── BaseDomainService（已有，不改动）
│   └── StatefulDomainService（新增）
└── BaseAppService

StatefulDomainService<
    T extends AggregateRoot & Stateful<S>,  // 聚合根类型
    R extends BaseRepository<T>,             // 仓储类型
    S extends Enum<S> & NamedEntry,          // 状态枚举类型
    E extends Enum<E> & NamedEntry,          // 事件枚举类型
    C                                         // 上下文类型，用于条件判断和动作回调
>

.external(S from, S to, E event)
    .perform((from, to, event, ctx) -> {
        // 转换发生时的回调动作
    })

@Data
@DomainObject(...)
public class Requirement implements AggregateRoot, Stateful<RequirementStatus> {
    private RequirementStatus status;  // Lombok @Data 自动生成 getStatus()/setStatus()
    // ... 其他字段
}

@Service
@RequiredArgsConstructor
@Slf4j
public class RequirementDomainService extends StatefulDomainService<
    Requirement, RequirementRepository, RequirementStatus, RequirementEvent, Requirement> {

    @Override
    protected String getFsmName() {
        return "RequirementFsm";
    }

    @Override
    protected Fsm<RequirementStatus, RequirementEvent, Requirement> buildFsm() {
        return FsmBuilder
            .builder(RequirementStatus.class, RequirementEvent.class,
                     Requirement.class, getFsmName())
            .external(RequirementStatus.PENDING_ASSESS, RequirementStatus.ASSESSED,
                      RequirementEvent.ASSESS)
            .external(RequirementStatus.ASSESSED, RequirementStatus.ADOPTED,
                      RequirementEvent.ADOPT)
            // ... 更多转换规则
            .build();
    }

    // 业务方法
    public void assessRequirement(AssessRequirementCmd cmd) {
        Requirement requirement = repository.load(cmd.getRequirementCode());
        
        // 状态校验：不允许则抛出 IllegalStateException
        checkTransition(requirement, RequirementEvent.ASSESS, requirement);
        
        // 执行业务逻辑...
        
        // 触发状态转换：自动更新 requirement.status
        fireTransition(requirement, RequirementEvent.ASSESS, requirement);
        
        repository.save(requirement);
    }
}

// 在 ApplicationService 或 Adapter 层
public List<String> listAvailableActions(String requirementCode) {
    Requirement requirement = repository.load(requirementCode);
    Transits<RequirementStatus, RequirementEvent> transits =
        requirementDomainService.listAvailableTransitions(requirement, requirement);
    
    return transits.getEvents().stream()
        .map(NamedEntry::getCode)
        .collect(Collectors.toList());
}

// 生成 PlantUML 供文档或前端展示
String plantUml = requirementDomainService.getFsm().generatePlantUML();

flowchart LR
    subgraph "Phase 1：基础框架搭建（✅ 已完成）"
        P1_1["Stateful<S> 接口"]
        P1_2["FsmRegistry 注册中心"]
        P1_3["StatefulDomainService 基类（4个泛型）"]
        P1_4["FsmBuilder Action 支持"]
        P1_5["FsmAutoConfiguration 自动配置"]
        P1_6["集成测试 15/15 通过"]
    end

    subgraph "Phase 2：业务集成（✅ 已完成）"
        P2_1["pulse 项目 Requirement 接入"]
        P2_2["RequirementDomainService 重构"]
    end

    subgraph "Phase 3：增强能力（❌ 待实现）"
        P3_1["状态变更历史自动记录（审计）"]
        P3_2["多状态字段支持"]
        P3_3["事务绑定（状态转换失败回滚）"]
        P3_4["状态机 Graph 可视化 API"]
    end

    P1_1 & P1_2 & P1_3 & P1_4 & P1_5 --> P1_6
    P1_6 --> P2_1 & P2_2
    P2_2 --> P3_1 & P3_2 & P3_3 & P3_4