109 lines
5.7 KiB
Markdown
109 lines
5.7 KiB
Markdown
# 撤机工单 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. 上线检查单
|
||
|
||
- [x] 单测全量通过（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，由用户确认）
|