mobile wallpaper 1mobile wallpaper 2mobile wallpaper 3mobile wallpaper 4
3230 words
8 minutes
商城 Agent 实战(六):让 Agent 安全执行退货申请工作流
2026-08-16
2026-09-28

项目源码:huanchenfeng/agentShop。本文按 2026-09-28 核对的项目实现讲解,重点是一次退货申请怎样从自然语言变成确定的业务操作。

用户问“这个订单能退吗”,系统只需要查询;用户说“确认提交退货申请”,系统才可能写入业务表。这两个动作必须分开,即使模型在一次回答中连续调用多个 Tool,也不能跳过服务端的确认检查。

本文围绕一个场景展开:会员选择自己的已完成订单,填写退货原因,查看预览,在下一轮明确确认。读完后,应能分清谁保存待执行动作、谁校验授权,以及在哪些故障下仍可能无法判断申请是否成功。

1. 先确定自动流程能处理什么#

当前项目只自动处理当前登录会员的订单,要求订单状态为已完成、收货后仍在 7 天窗口内,并且只有一条订单明细。这里的“单商品”指一条明细,不等于购买数量只能为 1;多条明细的商品选择和部分数量退货尚未纳入这条自动流程。

提交前还要检查是否已经存在状态为 0、1、2 的退货申请。7 天窗口是这个示例项目采用的业务规则,实际商城应以自己的已确认规则实现。

一次正常操作如下:

查询候选订单 → 检查资格 → 收集原因
↓
生成预览,结束当前轮
↓
用户下一轮明确确认提交
↓
校验确认记录,重新检查订单
↓
创建退货申请

RAG 可以解释退货规则,Memory 可以帮助理解“刚才那个订单”,但它们都不能证明订单属于谁,也不能授权写入。订单事实来自业务服务,确认依据来自当前用户输入与服务端保存的待执行动作。

2. 将身份、流程与落库分开#

模型通过 Tool 请求操作,最终创建仍交给业务 Service:

组件负责的事情
AI Service理解意图、选择工具、组织回复
售后 Tool预览、确认凭证、锁和重复调用处理
工作流服务保存当前会话的售后进度
退货业务 Service重查订单、校验资格、构造并插入申请

对应源码分别是 PortalAssistant、PortalAfterSalesTools、AfterSalesWorkflowService 和 OmsPortalOrderReturnApplyServiceImpl。

登录会员不能成为模型可填写的 Tool 参数。Controller 在进入 AI Service 前,从认证上下文取得会员,将身份、会话和本轮原始输入放入 PortalAiToolContext。下面省略了 Controller 外层的校验、日志与会话锁:

try (PortalAiToolContext.Scope ignored =
PortalAiToolContext.open(memberId, conversationId, userMessage)) {
return portalAssistant.chat(memoryId, userMessage);
}

memoryId 是服务端生成的会员与会话隔离标识,不是直接把客户端会话名当作唯一键。上下文还为本次请求生成 userTurnId,供后续判断预览与确认是否来自不同轮次;Scope 结束后恢复或清理线程上下文。

业务 Service 在创建时仍会检查当前登录会员与目标订单。Tool 的身份上下文用于传递可信信息,不能替代数据库侧的归属校验。

3. 预览阶段保存的是什么#

previewReturnApplication 收到订单和原因后,先检查资格,再生成摘要。例如:

订单:示例订单 A
商品:示例商品
原因:商品与描述不符
操作:提交退货申请

这一阶段不插入退货申请表,但会更新 Redis。服务端生成两个不同用途的标识:

  • confirmationToken:消费一次确认记录时使用的凭证。
  • pendingActionId:识别这次待执行动作,供重复调用处理和后续排查使用。

确认记录绑定会员、会话、订单、商品、原因、预览轮次和待执行动作标识,有效期为 30 分钟。Redis 保存的值包含 Token 与序列化记录:

confirmationToken | ConfirmationRecord JSON

与此同时,工作流进入 WAIT_CONFIRMATION,保存订单、原因、Token 和 pendingActionId。工作流状态的有效期是 2 小时,与确认记录的 30 分钟不同。状态仍存在,不代表确认凭证仍可使用。

AfterSalesStage 定义了选择订单、检查资格、等待确认、提交中、完成、转人工等阶段。不过,定义枚举不会自动限制状态迁移。当前实现的约束主要写在 Tool 的分支校验中,工作流服务负责保存状态,并没有一个集中校验所有“旧状态 → 新状态”的转换引擎。

4. 什么才算一次有效确认#

createReturnApplication 会检查本轮的原始用户消息,而不是模型生成的解释。当前实现对整段消息做规定的空白与标点标准化后,只接受四种表达:

确认提交
确认提交退货申请
同意提交
同意提交退货申请

“好的”“可以”“继续”不会通过这一检查。模型即使把这些话改写成“用户已确认”,也不能改变 Tool Context 中的原始输入。

服务端还要求:

  1. 当前上下文属于登录会员。
  2. 提交的订单、原因和 Token 与保存的待执行动作一致。
  3. 当前 userTurnId 与生成预览时不同。
  4. 消费到的确认记录确实绑定当前会员、会话和动作。

跨轮检查可以阻止模型在同一个请求内先预览、再立即创建。不过,两个不同的请求编号并不能证明用户已经在界面上阅读完整摘要。进一步改进时,可以把预览作为结构化卡片展示,让确认按钮显式绑定 pendingActionId;这是交互层的补强,当前实现仍采用文本确认。

如果用户修改订单或退货原因,应重新生成预览,让确认针对新的动作,而不是继续使用旧凭证。

5. 提交时的真实执行顺序#

顺序会影响故障行为。当前代码先取得订单锁,再消费确认凭证,而不是反过来:

检查登录身份、原始确认消息和待执行动作
↓
已完成且参数一致?返回已保存结果
↓
取得订单锁(30 秒)
↓
原子消费确认记录,并检查记录绑定关系
↓
重新校验资格、核对商品
↓
设置服务端派生的幂等键为 PENDING(24 小时)
↓
保存 SUBMITTING,调用业务 Service 写数据库
↓
保存申请编号,工作流改为 COMPLETED
↓
比较锁值后释放订单锁

先获取锁,意味着锁竞争失败时不会提前消耗本次确认凭证。锁使用随机值标识持有者,释放时比较值后再删除,防止过期的旧请求删除新请求的锁。

但 30 秒租期不是执行时长的上限。若请求未完成锁便过期,后续请求仍可能进入。安全释放解决的是“不能删掉别人的锁”,不能让已经过期的锁继续保护业务。

确认凭证怎样做到只消费一次#

源码通过 Lua 完成读取、比较和删除,并返回完整记录供 Java 校验:

local value = redis.call('GET', KEYS[1])
if not value then return nil end
local separator = string.find(value, '|', 1, true)
local token = value
if separator then
token = string.sub(value, 1, separator - 1)
end
if token ~= ARGV[1] then
return '__TOKEN_MISMATCH__'
end
redis.call('DEL', KEYS[1])
return value

这里比较的是存储值开头的 Token,并非把整段 JSON 与 Token 直接比较。脚本成功后,Java 再解析记录,核对会员、会话、订单、原因与 pendingActionId。

原子消费可以防止同一份 Redis 确认记录被同时取走两次。它并没有把 Redis 和数据库变成一个事务:消费之后进程退出,数据库可能还没有收到创建请求。

6. Redis 防重与数据库幂等有什么区别#

Tool 虽然保留了 idempotencyKey 参数,但真正使用的键由服务端派生:

memberId + orderId + productId + pendingActionId

同一待执行动作因此具有稳定标识。正常路径下,工作流中的完成记录与 Redis 中的申请编号可以用于复用结果。

随后,createConfirmedReturn 会再次查询订单,检查登录会员、订单归属、完成状态、收货时间、商品明细和已有申请。商品、金额与会员信息根据服务端查询结果构造,不能直接接受模型提交的完整申请对象。

需要特别说明:当前业务实现检查已有申请后再插入,pendingActionId 写在申请描述中,没有以它建立数据库唯一约束。因此,文章不能把这套实现描述为“任何重试都只会插入一次”。

故障位置可能出现的结果
Token 已消费,尚未落库凭证失效,但申请还未创建
数据库已写入,Redis 回写失败用户收到失败或转人工,申请可能已经存在
订单锁过期后请求重叠两个请求可能都通过“尚无申请”的查询
工作流或幂等记录过期重试未必还能找到原结果

当前异常分支会删除部分 Redis 幂等记录并转人工。这个动作不能撤销已经提交的数据库写入,也不能证明“申请没有创建”。

更可靠的后续设计是:把待执行动作标识作为数据库中的独立字段,建立合适的唯一约束,在同一数据库事务中记录动作与创建结果;遇到唯一键冲突时查询原结果。具体约束还要覆盖“同一订单商品能否同时存在多份有效申请”这类业务规则,不能只去重请求编号。

这些是改进方向,当前源码尚未完成。人工排查或自动恢复时,也应先查询实际申请记录,再决定是否重新发起。

7. 旧创建入口与人工接管#

如果原有创建接口仍允许客户端提交完整退货对象,新 Tool 的确认检查就可能被绕开。当前项目关闭了两个旧入口:

  • Controller 的 /returnApply/create 返回失败,提示使用受控流程。
  • Service 的旧 create(OmsOrderReturnApplyParam) 抛出不支持异常。

这收紧了已知旧路径。不过,新业务方法 createConfirmedReturn 本身并不消费确认 Token,确认校验仍在 Tool 层。将来增加定时任务、其他 Controller 或内部调用时,需要明确它们的授权来源,不能仅凭方法名中有 Confirmed 就假定已经确认。

遇到多条订单明细、资格无法自动处理、工具失败或用户要求人工时,当前实现会调用工单服务,创建真实的 CustomerTicket,并把工单号保存到售后状态中。它已经不只是把阶段改成 TRANSFERRED_TO_HUMAN。

用户看到的反馈应包含可查询的工单号。若数据库写入结果不明确,客服还需要知道失败发生在哪一步,核对申请表后再处理。工单的持久化、领取和状态一致性见人工接管与评测篇。

8. 怎样验证这条链路#

不要只断言回复包含“申请成功”。至少要同时检查 Tool 返回、业务表和流程记录。可以按下面的顺序准备测试数据与断言:

先验证正常路径。 同一会员预览一笔合格订单,下一轮发送明确确认,检查申请字段来自服务端订单数据,返回的申请编号能查询到。

再验证拒绝路径。 无预览、模糊确认、同轮提交、跨会话 Token、其他会员订单,以及预览后订单状态变化,都应在落库前被拒绝。断言应包含申请表未新增记录。

最后验证故障路径。 重复提交、订单锁竞争、Token 消费后进程中断、数据库成功后 Redis 失败,分别检查实际写入次数、用户反馈和恢复方式。对“结果未知”的场景,应允许发现已存在的申请,而不是盲目重试。

项目中的单元测试可以帮助验证这些分支,但 mock Redis 与数据库不能证明跨进程并发、租期过期和双存储故障都已处理。本文不以历史测试数量作为上线结论,也没有声称完成真实商城的故障演练。

阅读源码时,可以先看 PortalAfterSalesTools 的预览与创建方法,再看业务 Service 如何构造申请,最后对照异常分支。这样能把“用户确认了什么”“实际写入了什么”“失败后还能查到什么”连接起来。

参考资料#

Share

If this article helped you, please share it with others!

商城 Agent 实战(六):让 Agent 安全执行退货申请工作流
https://github.com/huanchenfeng/agentShop
Author
梦幻晨风
Published at
2026-08-16
License
CC BY-NC-SA 4.0

Some information may be outdated

Table of Contents