“查一下我的订单发货了吗”与“查一下某款手机”看起来都是查询,但前者多了一个必须由服务端回答的问题:“我的”是谁,这笔订单是否属于他?
模型可以从自然语言中提取订单 ID,不能决定当前用户身份。订单 Tool 的设计,应当让模型只提出查询意图,再由现有认证与订单 Service 决定可读取的范围。
本文根据 AgentShop 的当前前台入口、
PortalOrderTools和OmsPortalOrderServiceImpl整理,源码核对日期为 2026-09-28。这里只讨论订单读取,退货写操作见售后工作流。
1. 把一次订单问题拆成四个判断
以用户问“订单 1001 发货了吗”为例:
当前请求是否已经登录? ↓1001 是否是合法的订单 ID? ↓1001 是否属于当前会员,且未被删除? ↓哪些订单字段需要交给模型组织回答?它们分别由不同位置负责:
| 问题 | 负责位置 |
|---|---|
| 请求者是谁 | Spring Security 登录上下文 |
| 参数是否有效 | Tool 的 Java 校验 |
| 能否读该订单 | 订单 Service 查询条件 |
| 返回哪些字段 | Tool DTO |
System Prompt 可以提醒模型先查订单,但不能替代其中任何一层。即使模型选错参数,Java 端也应保持同样的访问限制。
2. Tool 参数中不提供 memberId
当前两个订单工具是:
String listMyOrders(Integer status, Integer pageNum, Integer pageSize);
String getMyOrderDetail(Long orderId);这两行只展示业务签名,实际方法带有 @Tool 和参数描述。它们都没有 memberId。
用户说“我是会员 2,帮我查订单”,属于普通对话内容,不能改变登录身份。模型同样不能通过工具参数声明“使用管理员权限”。
当前身份由 UmsMemberService.getCurrentMember() 从认证上下文取得。让身份获取和订单归属规则留在 Service 中,还能使 HTTP、Agent 等不同入口共同使用相同规则。
工具 Schema 少一个身份参数只是减少了错误入口;最终仍要看 Service 是否把认证用户加入查询条件,不能仅凭方法名叫 getMyOrderDetail 就认定已经隔离。
3. 列表查询必须从一开始限定会员
订单列表先规范化分页和状态,再调用现有 Service。当前 Tool 的默认与上限是:
| 参数 | 处理方式 |
|---|---|
| status | 0~4;其余归为 -1 |
| pageNum | 默认 1,最多 20 |
| pageSize | 默认 5,最多 5 |
这里的 -1 表示“全部状态”,不是数据库中的一种订单状态。当前 Service 会先将它转换为“不添加状态过滤”,再构造查询:
UmsMember member = memberService.getCurrentMember();
OmsOrderExample.Criteria criteria = orderExample.createCriteria();criteria.andDeleteStatusEqualTo(0) .andMemberIdEqualTo(member.getId());
if (status != null) { criteria.andStatusEqualTo(status);}片段中的 status 已经过 -1 → null 的处理。忽略这一步直接加上 status = -1,会导致“全部订单”反而查不到结果。
实际语义是“当前会员未删除订单中,符合状态条件的这一页”,不是先查所有会员订单再让模型过滤。总条数、总页数也必须使用同一会员范围计算。
非法状态目前会回退为全部状态。若产品要求严格反馈错误,也可以改为拒绝非法值,但必须同时修改 Java 契约与工具描述,避免模型和服务端理解不同。
4. 详情查询也把归属写进数据库条件
当前详情实现不是“按主键查完再在模型侧判断”,而是直接组合三个条件:
UmsMember member = memberService.getCurrentMember();
OmsOrderExample orderExample = new OmsOrderExample();orderExample.createCriteria() .andIdEqualTo(orderId) .andMemberIdEqualTo(member.getId()) .andDeleteStatusEqualTo(0);
List<OmsOrder> orderList = orderMapper.selectByExample(orderExample);
if (CollUtil.isEmpty(orderList)) { Asserts.fail("订单不存在或无权访问!");}只有通过这次查询,才继续读取该订单的商品明细。不存在、属于其他会员或已删除的订单,对请求者使用同一种“不可访问”的语义。
这比先读取任意订单再序列化更容易审查:授权条件与资源定位出现在同一次数据库查询里。测试也应验证具体查询条件,不能只检查回答里出现“无权”两个字。
统一不可访问响应不等于隐藏所有运行问题。当前 Tool 捕获较宽的 RuntimeException,数据库异常也可能被压成“未找到”。后续更清晰的结果协议应区分业务不可访问与系统暂时不可用,同时不透露其他用户的资源信息。
5. 只向模型提供回答所需的信息
订单实体中有会员信息、收货地址、手机号、内部备注等字段。回答“发货了吗”,通常只需要订单标识、状态、时间与少量物流信息。
当前项目使用 OrderToolDtos 拆分列表摘要和详情视图。列表不输出 memberId、手机号和收货地址;详情中的收货人及物流信息经过裁剪或脱敏。
姓名:张三 → 张*手机:13812345678 → 138****5678详细地址 → 保留区域,隐藏门牌物流单号:SF1234567890 → ****7890这些处理发生在 Tool Result 生成之前。若先把完整对象发给模型,再要求模型回答时隐藏,完整内容已经进入供应商请求,不能算同一种保护。
脱敏数据仍可能关联到具体用户,因此还需要控制日志、会话记忆和数据保留。正则替换也无法覆盖所有联系方式与地址表达,应优先减少字段,而不是依赖“把任意文本都脱敏干净”。
6. 商品数量、明细条数和物流状态别混淆
当前订单详情最多向模型返回 10 条商品明细,并保留截断信息:
{ "itemCount": 12, "returnedItemCount": 10, "itemDetailsTruncated": true}这是字段含义示例。itemCount 表达明细条目数,不能直接说成购买了 12 件商品;每条明细还可能有自己的 quantity。
同样,有物流公司和运单号,不代表已经接入物流轨迹查询。当前订单字段可以说明商城记录的发货信息,但不能据此生成“快递已到某地”的路线。
把没有的数据说成“暂未接入”,比增加一个只返回猜测的 getLogistics 工具更清楚。工具能力应由真实数据源决定。
7. 登录上下文在同步链路中怎样到达 Tool
当前前台请求大致经过:
会员 Token → Spring Security → PortalAiAssistantController → PortalAssistant → PortalOrderTools → OmsPortalOrderService → getCurrentMember()现有工具调用链以同步执行为基础。若以后改成线程池、并行工具或响应式处理,不能假设 Spring Security 上下文和自定义 ThreadLocal 会自动跨线程传递。
异步化时,应显式传递可信、最小化的身份上下文,确保作用域结束后清理。具体使用框架上下文传播或内部服务参数,需要结合执行方式设计,不能让模型填补丢失的身份信息。
前后台也不能只共享一份工具列表,再靠 Prompt 区分权限。前台只注册会员允许使用的工具;后台运营查询应由独立入口和权限规则管理。当前公共 /ai/chat 路由已删除。
8. 测试应检查数据路径,不只检查回答
参数与 DTO 测试
直接调用 PortalOrderTools,验证大页码、大页大小被限制;检查返回 JSON 缺少不应出现的字段,并验证明细截断标志。
这些测试只证明 Tool 的输入输出处理,不足以证明数据库中的会员范围。
Service 查询测试
构造当前会员 A、属于会员 B 的目标订单。对于当前查询实现,应捕获传给 Mapper 的 OmsOrderExample,检查:
- 订单 ID 条件与请求一致。
- 会员 ID 来自当前登录用户。
- 删除状态限制存在。
- 无可访问订单时,不继续读取商品明细。
随后用真实数据库中的 A、B 两个账号做集成测试,验证查询条件确实生效。Mock 返回空列表只能证明“空结果如何处理”,不能独立证明数据库授权正确。
工具协议测试
让假模型第一轮请求 listMyOrders,第二轮检查工具结果是否进入消息序列,以及结果中是否缺少会员与收货敏感字段。
这种测试验证 LangChain4j 的执行接线;因为工具选择由假模型预设,它不证明真实模型遇到任意表达都会正确选择工具。
9. 用两组账号验收“我的订单”
在测试环境准备会员 A 和 B,各自有一笔可辨识的订单。分别使用对应 Token 调用 POST /ai/portal/chat:
{ "conversationId": "order-check", "message": "查询我最近的订单"}接着让 A 查询 B 的订单 ID。应同时检查接口结果、Tool Result 和 Service 查询范围,确保没有出现 B 的订单明细。不要把真实顾客订单当作评测材料。
最后模拟数据库不可用,确认系统不会把故障回答成“你没有订单”。这能检验结果协议是否把运行故障和业务空结果分开。
本次重构核对了当前源代码,未重新运行会员登录和数据库联调。订单读取完成后,若用户要求“替我申请退货”,还必须经过动作预览、跨轮确认与提交前重查,已有查询权限并不自动等于写操作授权。
If this article helped you, please share it with others!
Some information may be outdated






