退款状态不能复用订单状态机，因其是独立资金动作，强依赖支付渠道响应、允许人工重试但禁止回退，需设processing为可自循环中间态，rejected/refunded为终态；配置须严格遵循workflow.yaml路径、framework.workflows结构、marking_store属性名一致、supports类名完整；实体状态变更必须通过$workflow->apply()触发，字段应为public string $status且初始值非空；guard回调禁查外部api、需加锁防并发、应提前refresh关联对象并加日志确认执行。
退款状态为什么不能照搬订单状态机
直接复用订单的 pending→paid→shipped 状态链，会导致退款单卡在 refunding 无法推进，甚至误判为“已完结”。退款不是订单的逆向流程，而是独立资金动作：它不依赖发货完成，但强依赖支付渠道响应；它允许人工干预重试，但禁止状态回退到 completed 后再发起新退款。
常见错误是把 failed 设为终止态——一旦支付渠道超时或签名验签失败，状态就卡死，客服只能手动 SQL 更新，既慢又易出错。正确做法是让所有异常都导向可重试的中间态，比如 processing，再靠补偿任务兜底。
-
rejected和refunded是终态，不可再触发任何 transition -
processing必须支持自循环（retrytransition），且 from/to 都是它自己 - 不要定义
cancelled这类模糊状态——它到底是用户撤回？还是系统拦截？必须拆成user_withdrawn或system_rejected
workflow.yaml 怎么配才不会 silent fail
配置写错，$workflow->apply($refund, 'complete') 会静默失败，不报错、不更新数据库、也不触发事件——你查日志发现 nothing，但退款单状态还是 processing。
关键检查点：
- 文件路径必须是
config/packages/workflow.yaml，写成workflows.yaml或放在config/根目录下都不行 - 顶层结构必须是
framework: workflows:，顶格写workflows:会导致容器里压根没注册服务 -
marking_store的property值（比如status）必须和 Refund 实体的 public 属性名完全一致，包括大小写和空格 -
supports必须明确写成- App\Entity\Refund，漏掉命名空间或拼错类名，$registry->get($refund)就找不到 workflow
最小可用配置示例：
framework:
workflows:
refund:
type: 'state_machine'
audit_trail: enabled: true
marking_store:
type: 'method'
property: 'getState' # 要求 Refund 类有 public function getState(): string { return $this->status; }
supports:
- App\Entity\Refund
places:
- pending
- processing
- completed
- rejected
- user_withdrawn
transitions:
submit:
from: pending
to: processing
complete:
from: processing
to: completed
reject:
from: [pending, processing]
to: rejected
withdraw:
from: pending
to: user_withdrawn
retry:
from: processing
to: processing
Refund 实体里 state 字段怎么写才安全
别用 $refund->status = 'completed' 手动赋值——这会绕过 guard 校验、跳过事件监听、审计日志断档，且 $workflow->can($refund, 'complete') 永远返回 false。
正确姿势只有一条：所有状态变更必须走 $workflow->apply()，然后显式 $entityManager->flush()。
- 实体字段必须是
public string $status = 'pending';，初始值不能是null或空字符串 - 推荐加一层封装：
public function getState(): string { return $this->status; }，避免将来改字段名时要批量修 YAML - 不要在 setter 里做逻辑判断（如
if ($status === 'completed') { $this->completedAt = new \DateTime(); }），这类副作用应放在 workflow 的on_entered.completed事件监听器里 - 快照字段（如
original_amount、channel）应在创建退款单时一次性写入，后续状态变更不再修改
guard 回调里最容易踩的三个坑
guard 函数返回 false 会直接中断 transition，但不抛异常、不打日志、也不告诉你哪里拦住了——你看到 $workflow->can($refund, 'complete') === true，但 apply() 就是不动。
- 别在 guard 里查外部 API（比如调微信退款查询接口）——超时或网络抖动会让整个状态变更阻塞，建议把结果缓存在本地，由补偿任务刷新
- 查数据库时用
SELECT ... FOR UPDATE锁住关联订单，否则并发退款可能重复扣减平台手续费 - guard 接收的
$subject是原始实体，不是 Doctrine Proxy 对象；如果用了 lazy loading，在 guard 里调$subject->getOrder()->getAmount()可能触发 N+1 查询，应提前$entityManager->refresh($subject->getOrder())
调试时最有效的一招：在 guard 开头加 error_log("guard complete for refund {$subject->getId()}");，确认它是否被执行——很多问题根本不是逻辑错，而是 guard 根本没跑。
复杂点不在代码多，而在每个 transition 都要同时考虑支付渠道约束、财务对账要求、客服人工通道入口——比如 retry 不仅要重发请求，还得记录操作人、生成新 trace_id、通知风控系统。这些细节漏掉一个，线上就容易出资损。
