项目源码: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 中的原始输入。
服务端还要求:
- 当前上下文属于登录会员。
- 提交的订单、原因和 Token 与保存的待执行动作一致。
- 当前
userTurnId与生成预览时不同。 - 消费到的确认记录确实绑定当前会员、会话和动作。
跨轮检查可以阻止模型在同一个请求内先预览、再立即创建。不过,两个不同的请求编号并不能证明用户已经在界面上阅读完整摘要。进一步改进时,可以把预览作为结构化卡片展示,让确认按钮显式绑定 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 = valueif 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 如何构造申请,最后对照异常分支。这样能把“用户确认了什么”“实际写入了什么”“失败后还能查到什么”连接起来。
参考资料
If this article helped you, please share it with others!
Some information may be outdated






