symfony 7.x workflow组件需显式建模与严格校验，apply()抛“transition does not exist”源于三重拦截：当前state不在from列表、guard返回false或marking store加载失败；须检查workflow.yaml配置、实体state字段类型及值、多workflow时显式指定name、marking_store类型匹配、guard调试与性能规避、前端状态需动态提取元数据、can()与apply()执行差异及事件/持久化陷阱。
Symfony 7.x 的 Workflow 组件不是“开箱即用的状态管理器”，它是一套需要显式建模、严格校验、谨慎集成的流程控制机制。直接往实体上丢 apply('pay') 很可能报 "Transition 'pay' does not exist"，这不是 bug，是设计使然。
为什么 Workflow::apply() 总抛 “Transition does not exist”
这个错误根本不是代码写错了，而是状态机在 apply 前做了三重静默拦截：当前 state 不在 transition 的 from 列表里、guard 回调返回 false、或者 marking store 加载失败导致 getMarking() 返回空。
- 检查
workflow.yaml中该 transition 的from是否包含实体当前的 state 值（注意大小写、前后空格、是否为 null） - 确认 Doctrine 实体的 state 字段已加载且类型是字符串（如
'created'），不是未初始化对象或null - 多个 workflow 共存时，别用
$registry->get($order)，必须显式指定 name：$registry->get($order, 'order_main_workflow') -
marking_store: type: single_state要求数据库字段名和 place 名完全一致；若用multiple_state，字段值必须是形如['created' => true]的数组
Guard 静默失败是最难排查的坑
guard 是 PHP callable，返回 false 就直接终止 transition，不抛异常、不打日志、也不进事件监听器 —— 它像一道没标签的门，推不开还找不到锁孔。
- 在 guard 里加
error_log("guard called for {$subject->getId()}")确认它是否被执行 - guard 接收的是原始实体对象，不是 Doctrine Proxy；如果用了 lazy loading，
$subject->getCustomer()可能触发 N+1 查询甚至死锁 - 避免在 guard 里调外部 API 或查数据库；它运行在
apply()同步流程中，阻塞整个事务 - 测试阶段先注释 guard，确认 transition 路径本身通了，再逐步加回逻辑
如何安全地把工作流状态暴露给前端
别直接把数据库里的 state 字段值扔给前端，那只是个标识符。要展示“待支付”“已发货”，得从 workflow definition 动态提取元数据。
- 通过
$workflow->getDefinition()->getPlaces()获取所有合法状态名数组 - 用
$workflow->getDefinition()->getMetadataStore()->getPlaceMetadata($placeName)拿 label、color、sort 等扩展信息 - 组合成结构化数组：
['created' => ['label' => '新建', 'color' => 'gray']]，供前端渲染或权限判断 - 这个数组必须每次从 workflow service 构建，不能硬编码 —— 否则配置改了，前端状态文案就脱节
can() 返回 true 却 apply() 失败？后续环节全在黑盒里
can() 只检查两件事：transition 是否存在 + guard 是否放行。而 apply() 还要完成 marking 更新、事件分发（workflow.entered、workflow.completed）、持久化（如果你配了 enabled: true 的 DoctrineORMMarkingStore）—— 任一环节崩了，都表现为 apply 失败且无明确提示。
- 监听
workflow.entered事件的回调里抛异常？Symfony 默认吞掉，不会冒泡到 apply 调用处 - 用了 Doctrine MarkingStore 但没在事务里调
$em->flush()？state 字段不会更新，下次apply()仍卡在旧状态 - 自定义
MarkingStore实现里写了saveMarking()但忘了 return 或 throw 异常？流程就停在半路
真正麻烦的从来不是定义几个状态，而是当 guard 不执行、event 监听器静默失败、marking store 和数据库字段错位时，你得一层层掀开 Symfony 的封装去看底层标记怎么加载、transition 如何匹配、事件怎么分发 —— 这些细节不在文档首页，但在每个生产事故的堆栈最底下。
