[REQ-20260916-0020] 送货工单 MCP 查询工具（列表+详情） (#18)

2026-09-16 16:41:08 +08:00
parent c430cc9322
commit 6c8fe2e3bb
17 changed files with 1074 additions and 0 deletions
@@ -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，由有权限的上层服务决定访问方式。