Technical Design · V1.0

食堂智能客服
订单咨询与退款疑问

把“订餐咨询”统一落到订单技术域；把退款拆成现金退款与退款订单两个真实业务域。Agent负责理解、查询与解释，资金动作继续由人工审批。

2026-09-03storedevelop_ai_agent_0903本地实现完成待真实账号验收

01｜范围与结论

订单咨询

真实查询，同条件复核

具名人员或订单号可查询真实订单状态，并把相同姓名与日期带入消费订单页面。

退款消歧

两个退款域不能混用

未说明类型时先选择现金退款或退款订单；不能默认跳到退款订单。

具名人员

双域分别回复

用户指名具体人物且未说明类型时，按权限分别查询两类退款，并在同一答复中清楚分开。

技术边界本期不执行退款、调账、补单，不承诺到账时限，不建设师生小程序客服。设备报修与营养配餐不属于本文范围。

02｜系统事实

退款域	页面	前端路由	查询逻辑	人员字段	权限
现金退款	账户管理 › 现金管理 › 现金退款	`/accountManagement/cashManagement/cashRefund`	`CashRefund::getList`	`staff_name`	部门数据权限
退款订单	订单管理 › 退款订单	`/orderManagement/refund`	`MealOrder::getRefundOrderList`	`nickname`	订单人员 + 餐厅权限

两类退款的表结构、状态、审批入口和权限链不同。Agent只负责统一对话入口，不统一底层退款数据。

03｜技术架构

用户问题订单/退款自然语言

→

AgentAssistant编排与日志

→

客服 Agent意图/类型/人物

→

只读工具双退款域查询

→

结果验证权限/同名/完整性

→

用户答复结果与筛选入口

组件	职责	安全限制
`AgentAssistant`	编排、来源标记、完整文本展示、日志	不生成退款SQL，不做资金写入
`CanteenCustomerServiceAgent`	订单咨询、退款类型与人物路由	不决定权限，不编造结果
`RefundSupportReadTool`	双域查询、精确姓名、金额汇总、异常分类	不返回手机号、UUID、用户ID、卡号
`Agent` Controller	注入真实业务Logic与账号权限	复用原查询，不绕开数据范围

04｜意图与路由

订单咨询

订单、消费记录、交易、支付、扣款与“查不到、未生成、状态异常、失败、重复扣款、为什么、怎么处理”等问题表达组合时，进入订单咨询。

问题	处理
支付成功但订单查不到，应该怎么处理？	返回核对字段与消费订单入口，不直接判定订单状态。
查询某人今天的消费订单状态	权限内读取真实状态，并将人员和当天日期带入消费订单页。
今天有多少条消费订单？	复用消费订单统计能力。
为什么看不到订单管理？	交给权限帮助能力，不被异常咨询误接管。

退款路由矩阵

人物	退款类型	Agent行为
未指名	未明确	返回“现金退款 / 退款订单”二选一。
未指名	现金退款	只返回现金退款说明和入口。
未指名	退款订单	只返回退款订单说明和入口。
已指名	未明确	同时查询两个退款域并分别回复。
已指名	已明确	只查询指定退款域。

05｜退款双域流程

类型不明

用户：退款怎么还没到账？
Agent：系统中有两类退款，请选择：
[现金退款]  [退款订单]

指名人员且类型不明

从问题中提取具体姓名；“老师、员工、某人”等角色词不算姓名。
退款类型缺失时，请求现金退款和退款订单两个域。
先按菜单权限过滤，再调用有权限的查询工具。
默认查询最近一个月，与两个列表默认口径一致。
姓名必须完全匹配；同名对应多个内部标识时停止汇总。
分别输出笔数、申请金额、最近状态、申请时间和复核入口。

已按最近一个月查询“示例人员”的退款情况：
现金退款：1笔，申请金额合计¥20.00；最近单号CR***，状态待审核。
退款订单：1笔，申请金额合计¥12.50；最近单号RO***，状态已同意。
以上为只读查询，不会自动退款或修改账户。

06｜数据与 API 契约

统一入口

POST /p/agent/ask
Content-Type: application/x-www-form-urlencoded

question=示例人员的退款进度在哪里查看？
current_route=/agentAssistant

observation类型

refund_support_lookup

退款域

cash_refund / refund_order / both

时间范围

last_1_month

来源

完整只读结果标记为 readonly_tool

展示

具体人物双域答复使用完整纯文本，避免摘要截断第二个退款域。

页面联动

现金退款：
/accountManagement/cashManagement/cashRefund?agent=1&staff_name=<姓名>&date_scope=last_1_month

退款订单：
/orderManagement/refund?agent=1&search_key=nickname&keyword=<姓名>&date_scope=last_1_month

现金退款页只在显式agent=1时应用姓名筛选；普通手工进入页面保持原行为。

07｜权限与安全

控制点	实现	失败行为
登录	`/p/agent/ask`继续执行登录校验	返回未登录，不执行查询
现金退款	`resolvePermittedDepartmentUuids()`	不调用现金退款域
退款订单	`resolvePermittedOrderUserIds()` + `resolvePermittedRestaurantIds()`	不调用退款订单域
隐私	只返回笔数、金额、单号、状态、申请时间	不返回手机号、UUID、用户ID、卡号
资金动作	查询链路无写操作	必须进入原页面人工办理

08｜异常与恢复

状态	用户表达	恢复方式
verified	可以返回0笔或真实汇总。	点击对应页面复核。
ambiguous_person	存在同名人员，请补充手机号或人员编号。	人工唯一定位人员。
result_truncated	记录较多，本次不输出不完整汇总。	进入列表继续筛选。
query_failed	查询失败，不能当作没有记录。	重试或进入页面核验。
permission_denied	当前账号无目标退款域权限。	联系有权限人员。

09｜代码落点

文件	职责
`application/p/logic/AgentAssistant.php`	Agent编排、来源、日志与完整双域文本。
`application/p/logic/agent/CanteenCustomerServiceAgent.php`	订单咨询与退款意图、类型、人物和答复。
`application/p/logic/agent/RefundSupportReadTool.php`	双域只读查询、金额汇总、同名与截断保护。
`application/p/controller/Agent.php`	注入现金退款/退款订单查询和权限范围。
`public/static/src/view/accountManagement/cashManagement/refundList.vue`	消费显式Agent姓名筛选。
`public/static/src/view/order/customTable.vue`	复用退款订单人员筛选。

10｜测试、部署与验收

自动化

154 tests

覆盖订单状态、双退款工具、只读边界、页面筛选和权限守卫。

断言

935 assertions

全部通过；PHP 7.3语法检查通过。

前端

HMR passed

PC webpack开发服务增量编译成功。

上线影响

无数据库迁移、无新增依赖、无退款写接口变化。
POST /p/agent/ask保持兼容，只增加新observation。
回滚只需撤回Agent注入、双域路由和现金退款页筛选。

当前阻断真实浏览器数据验收未完成。本地记录的默认管理员密码在当前数据库中登录失败，未尝试猜测密码或绕过登录。真实账号、两类退款权限和页面筛选完成验收前，不标记正式上线。