撤机工单 MCP 工具设计（withdraw.order.list.query / withdraw.order.detail.query）

需求：撤机工单查询工具（对齐老系统 /withdrawOrder/pageList、/withdrawOrder/lookDetails）
日期：2026-09-18
状态：已实现，单测 281/281 通过
分类：workorder ｜类型：读

1. 老系统语义来源

老系统撤机模块（WithdrawOrderController，2025-09 新增）：

主表 withdraw_order（m2，单号 CJGD 前缀）+ withdraw_order_details
流程走共享 order_process（order_type=1 区分撤机）
作业人员走共享 install_order_user（type=1）
状态机 orderState：0待审核 / 1被驳回 / 2调度中 / 3作业中 / 4待取回 / 5已完成 / 6已取消
type：0部分撤机 / 1全部撤机
业务链路：申请 → 调度（通过→作业中）→ 结单 → 自动生成取货工单（pickup_order.type=2， withdraw_order_no 回填）→ 取货入库自动生成入库单

已知老系统缺陷（MCP 侧修正）

pageList 按 finishDateStart/End 过滤时经 beanToWrapper 生成不存在的列 finish_date，实体列实为 finish_time——该过滤在老系统会直接 SQL 报错。MCP 侧显式映射到 finish_time。
lookDetails 详情接口没有权限校验（只按单号查）——MCP 侧补齐行级过滤（见 §4）。
老系统列表对人名空值补 -，MCP 侧不补（保持 null，交由 agent 判断）。

2. 工具设计

2.1 withdraw.order.list.query

入参全部可选，风格对齐 pickup/relocation：

参数	说明
type	0部分撤机 / 1全部撤机（白名单校验）
orderState	7 值白名单，非法拒绝
withdrawOrderNo / pickupOrderNo	撤机单号 / 关联取货单号，模糊
agentId / districtName	所属公司 id 精确 / 项目名称模糊
applyUserName / maintenanceUserName / cooperateUserName	申请人/运维/协同，模糊
applyDateFrom/To ~ finishDateFrom/To	5 组日期范围（申请/审核/调度/取货/完成），yyyy-MM-dd，结束含当天
page / rows	默认 1/20，rows>100 截断为 100 并返回 notice

返回：total/page/rows/[notice]/records，records 同时给 orderState+orderStateText、type+typeText；排序固定 id DESC。

2.2 withdraw.order.detail.query

入参 (id, withdrawOrderNo) 二选一；返回信息组：

record：主单全字段（期望/实际撤机日期、撤机理由 memo、联系人、项目地址等）
withdrawDetails：withdraw_order_details 中 in_count>0 的行（实际取回明细）
maintenanceUsers / cooperateUsers：来自 install_order_user（type=1，user_type 0/1）
processes：order_process（order_type=1，schedule_state=2 已办、排除抄送 theme=12，按 operationTime+id 升序），主题/类型同时给 code+文案
certificates：凭证附件，1:1 对齐老系统 lookDetails 的两个来源（见下方说明），输出 {id, fileName, bucket, objectKey, source}（不拼 URL，与现有 4 组工单一致）

不存在或无权统一抛 NOT_FOUND_OR_FORBIDDEN（不泄露存在性）。

凭证口径（2026-09-18 修正）

老系统取货/入库凭证（theme 6/7）的 aggregate_id 挂在派生取货工单的 pickup_order_process（经取货单号二次查询，operation_theme 1=取货、2=入库确认），与共享 order_process 是两套各自自增的 id，不能按 order_process.id 混查（会查不到或把其他取货工单的凭证挂到本单）。MCP 侧按取货单号查 pickup_order_process 取 id 集合再批量 IN 查 warehouse_in_out_pic(in_out_allocation_type=12)（source=pickup_process）；结单节点的发货附件来自 m1 mall_logistics_pic(order_no=取货单号)（source=logistics）。无取货单号时返回空。

3. 与老系统字段映射

过滤维度	老系统参数	MCP 实体列
申请日期	applyDateStart/End	apply_time
审核日期	auditDateStart/End	audit_time
调度日期	dispatchDateStart/End	dispatch_time
取货日期	pickupDateStart/End	pickup_time
完成日期	finishDateStart/End	finish_time（老系统误生成 finish_date）

4. 行级权限

PermissionService.applyWithdrawOrderRowFilter，1:1 复刻老系统 getWorkOrderAuth(type=3)：

总部（isagent=0）放行
代理商：apply_agent_id/agent_id ∈ {本代理+授权代管} OR property_id ∈ 代管物业 OR 本人出现在 order_process(order_type=1)
销售非负责人：只看自己创建物业 + 代管代理名下物业（property_id 过滤），空集塞 0
列表与详情复用同一方法，防详情绕过

5. 实现清单

新增：entity/m2/WithdrawOrder.java、entity/m2/WithdrawOrderDetails.java、 mapper/m2/WithdrawOrderMapper.java、mapper/m2/WithdrawOrderDetailsMapper.java、 mcp/tool/WithdrawOrderTools.java
修改：permission/PermissionService.java（applyWithdrawOrderRowFilter）
测试：WithdrawOrderToolsTest（6 用例：参数组合/截断 notice/人名不补/非法参数查库前拒绝/ 详情权限与存在性隐藏/详情组装/Spring AI schema 发布）、 PermissionServiceWithdrawOrderRowFilterTest（4 身份）
文档：doc/agent-mcp-tools-reference.md §28/29、本文件（README 不逐工具列举，无需改）

6. 上线检查单

单测全量通过（281/281）
PR 合入 main
远程部署（./deploy/deploy.sh remote-deploy）
prod scope 1（code='test'）幂等绑定 tool id（ToolSyncService 启动自动同步 tool 表后 INSERT scope_tool，防 tools/list 不可见——prod 作用域是 code='test' 不是 operation）
线上 tools/list 冒烟（真实 AK，由用户确认）

5.7 KiB Raw Blame History Unescape Escape