feat(mcp): add delivery order query tools (REQ-20260916-0020)

2026-09-16 16:23:11 +08:00
parent c430cc9322
commit 58da0c59d8
17 changed files with 1074 additions and 0 deletions
@@ -583,6 +583,38 @@

 ---

+## 20. delivery.order.list.query
+
+分页查询送货工单，对应旧系统 `POST /delivery/deliveryListByPage`。
+
+- 分类：workorder ｜ 类型：读
+- 数据来源：m2 `delivery_order`。
+- 入参：`deliveryOrderNo`、`sourceOrderNo`、`agentId`、`districtName`、`orderType`、
+  `orderState`、`sendMode`、`applyUserName`、申请/完成日期范围及 `page/rows`。
+- `orderType`：0=装机单送货，1=出库单送货；`orderState`：0=派送中，1=已完成，2=已取消；
+  `sendMode`：0=快递公司，1=自行派送。
+- 申请日期按业务字段 `apply_time` 查询，不沿用旧接口的 `create_time`；申请与完成日期可同时过滤。
+- 行级权限：总部看全部；代理身份可看申请代理或所属代理在自己、直属下级、授权代管范围内的工单，
+  以及授权代管物业和本人参与流程的工单；销售非负责人按其可见物业范围过滤。
+- 返回 `total/page/rows/records`，固定按 ID 倒序；记录同时返回状态、类型、配送方式的码值与文案。
+
+## 21. delivery.order.detail.query
+
+按 `id` 或 `deliveryOrderNo` 查询详情，两者至少传一个；同时传入时必须匹配同一条可见记录。
+
+- 行级权限与列表完全一致；不存在和无权统一返回 `NOT_FOUND_OR_FORBIDDEN`。
+- `record`：送货主单和文案字段。
+- `logistics`：物流公司/单号或派送员信息、物流状态；无物流记录时为 null。
+- `goods`：m2 `install_distribute_details` 配发物品，含物料、SN、数量、出入仓库和商城订单号。
+- `shippingFiles`：m1 `mall_logistics_pic` 发货图片。
+- `processes`：`schedule_state=2` 的流程记录及 m2 `warehouse_in_out_pic` 签收附件，按操作时间、ID 正序。
+- `relatedDocuments`：m2 `install_to_out_warehouse` 关联的出库、入库、调拨或划转单。
+- 所有附件仅返回 `id/fileName/bucket/objectKey`，不拼接公开 URL。
+
+详细设计见 `delivery-order-mcp-tools-design.md`。
+
+---
+
 ## 附录：在线查看工具清单

 ```bash
@@ -0,0 +1,43 @@
+# 送货工单 MCP 工具设计
+
+## 范围
+
+基于旧系统 `DeliveryOrderController` 的 `/delivery/deliveryListByPage` 与 `/delivery/deliveryScan`，
+提供两个只读 MCP 工具：
+
+- `delivery.order.list.query`
+- `delivery.order.detail.query`
+
+不包含送货签收、取消、导出等写操作。
+
+## 数据关系
+
+| 数据 | 数据库/表 | 关联键 |
+|---|---|---|
+| 主单 | m2 `delivery_order` | `delivery_order_no` |
+| 配发物品 | m2 `install_distribute_details` | `delivery_order_no` |
+| 流程 | m2 `delivery_order_process` | `delivery_order_no` |
+| 签收附件 | m2 `warehouse_in_out_pic` | `aggregate_id=process.id`, `file_type=3`, `in_out_allocation_type=11` |
+| 关联单据 | m2 `install_to_out_warehouse` | `delivery_order_no` |
+| 物流 | m1 `mall_order_logistics` | `order_no=delivery_order_no` |
+| 发货图片 | m1 `mall_logistics_pic` | `order_no=delivery_order_no` |
+
+跨库数据分开查询，不使用跨库 JOIN。详情先在带行权限的主单查询中确定可见记录，再读取关联信息。
+
+## 权限
+
+列表和详情统一调用 `PermissionService.applyDeliveryOrderRowFilter`：
+
+1. 总部身份不增加过滤。
+2. 销售非负责人按自己创建及代管代理名下的物业范围过滤，同时保留本人流程参与记录。
+3. 其他代理身份可见申请代理或所属代理在自己、直属下级和授权代管范围内的工单；另包含代管物业、
+   本人参与 `delivery_order_process` 的工单。
+4. 详情不存在与无权查看统一返回 `NOT_FOUND_OR_FORBIDDEN`。
+
+## 查询与输出约束
+
+- 日期严格使用 `yyyy-MM-dd`，结束日期通过次日零点的排他上界实现“含当天”。
+- 列表分页默认 1/20，rows 最大 100，固定 `id DESC`。
+- 详情同时传入 ID 和单号时按 AND 匹配，避免参数指向不同工单。
+- 流程只返回 `schedule_state=2` 的已处理记录，兼容历史 `operation_type=0/5/6`。
+- 附件不返回拼接的 OSS HTTP 地址，只返回 bucket 和 objectKey，由有权限的上层服务决定访问方式。