workflow 管理订单状态需 places、transitions、实体状态字段三者严格对齐；状态值须统一为类常量，getter 必须返回规范字符串，transition 的 from 必须覆盖当前状态，guard 失败默认静默，应加日志排查。
Workflow 能管好订单状态，但前提是 places、transitions、实体状态字段三者完全对齐——差一个字符大小写或下划线，apply() 就直接报 “Transition does not exist”。
places 和实体 getStatus() 返回值必须字面一致
常见错误现象：workflow.yaml 里写了 places: [paid, shipped]，但订单实体中 getStatus() 返回的是 'Paid' 或 'paid_status'，结果 can('ship') 永远返回 false。
实操建议：
- 所有状态值统一定义为类常量，例如
Order::STATUS_PAID = 'paid'，并在workflow.yaml和实体方法中复用 - 检查
getState()或getStatus()方法是否真的返回字符串，而不是null、int或对象 - Doctrine 实体中避免用
$status字段直接赋值；改用setState(string $state)并确保 getter 始终返回规范字符串
transition 的 from 列表必须覆盖当前状态
错误现象：apply('ship') 报错 “Transition ‘ship’ does not exist”，但配置里明明写了 from: paid —— 实际上是因为订单当前状态是 'payment_confirmed'，而这个值根本不在任何 from 列表中。
实操建议：
- 用
$workflow->getMarking($order)->getPlaces()打印当前标记，确认真实状态值（不是靠猜或日志） -
from支持数组，比如取消操作可从多个状态触发：from: [pending, paid, shipped]，别漏掉合法入口 - 多 workflow 共存时（如主流程 + 退款子流程），务必显式调用
$registry->get($order, 'order_main_workflow')，否则可能拿错 workflow 实例
guard 静默失败是调试黑洞
错误现象：can('pay') 返回 true，但 apply('pay') 却没效果、无异常、数据库也不更新 —— 大概率是 guard 回调返回了 false，而 Symfony 默认不抛异常也不记录。
实操建议：
- 在 guard 函数第一行加
error_log("guard for order #{$subject->getId()} returned " . ($result ? 'true' : 'false')); - guard 中避免调用
$subject->getRelatedEntity()类方法，Doctrine Proxy 可能引发 N+1 查询甚至死循环 - 测试阶段临时注释 guard，确认 transition 路径本身通了，再逐步加回业务逻辑
如何安全获取全部状态用于前端展示
想把订单所有状态（含 label、颜色、是否终态）传给前端？别手动维护数组，直接从 workflow 定义读取。
实操建议：
- 注入对应 workflow 服务，例如
WorkflowInterface $orderWorkflow - 调用
$definition = $orderWorkflow->getDefinition()，再用$definition->getPlaces()得到原始状态名数组 - 每个状态的元数据（如
label: '已支付'）需通过$definition->getMetadataStore()->getPlaceMetadata($place)单独获取 - 注意：metadata 不会自动继承，每个
place都要显式配置，否则getPlaceMetadata()返回空数组
最易被忽略的一点：Doctrine 实体里永远不要绕过 apply() 直接改 $order->status = 'shipped'。marking store 和数据库一旦脱节，can() 和事件监听就会彻底失准——这不是 bug，是设计使然。
