出库单 MCP 工具设计

1. 背景与范围

参考旧系统 POST /myWarehouseOut/allListByPage 和 GET /myWarehouseOut/lookDetail，在 xiaoqu-agent-service 新增两个只读工具：

工具	分类	用途
`warehouse.out.list.query`	warehouse/read	分页查询出库单
`warehouse.out.detail.query`	warehouse/read	按主键或出库单号查询完整详情

只读取 m0/m1/m2，主要数据表为 m2 的 warehouse_out、warehouse_out_details、 warehouse、warehouse_out_audit_process、warehouse_in_out_pic、 warehouse_out_certificate；收货地址和物流信息按需读取 m1。

本次不返回关联入库单详情，不修改旧模块和业务表，不新增 Flyway migration。新工具由现有 ToolSyncService 自动登记，初始不属于任何 Scope，发布后需在管理后台授权。

2. 列表工具

2.1 入参

单号模糊查询：outOrderNo、allocationOrderNo、mallOrderNo、deliveryOrderNo、 installOrderNo、pickupOrderNo。
归属精确查询：agentId、warehouseId、warehouseTypeId、applyUserId。
状态精确查询：orderState、sendMode、outSynchronizeState、assetSynchronizeState。
客户查询：useCustomerType、useCustomerId 精确查询，useCustomerName 模糊查询。
日期：outDateFrom/outDateTo 过滤 out_date；applyDateFrom/applyDateTo 过滤 apply_date。日期格式固定为 yyyy-MM-dd，业务时区为 Asia/Shanghai，结束日期包含当天。
分页：page 默认 1；rows 默认 20、上限 100，超出上限截断并返回 notice。

旧接口错误地把出库日期条件改写为申请日期条件，本工具不复制该行为。

2.2 出参

顶层统一返回 total/page/rows/records。每条记录包含主单号、来源类型、代理商、出库类型、仓库集合、数量、状态及状态文案、申请人及申请时间、客户、待办人、出库确认人及日期、物流、同步状态、关联工单号和备注。

sourceType：有调拨单号为 ALLOCATION，否则有商城订单号为 MALL，其余为 NORMAL。

orderState：0=待审核、1=被驳回、2=待出库、3=已完成、4=已撤销、5=作废。

列表页的仓库、待办人、出库人均按本页主单 ID 批量查询和内存聚合，禁止逐单 N+1 查询。

3. 详情工具

3.1 入参

id、outOrderNo 至少传一个；同时传入时必须指向同一条可见记录。
includeSerials 默认 false。
serialLimit 默认 100、最大 500；只限制返回数量，serialTotal 始终返回完整数量。

3.2 出参

record：主单字段、来源、状态文案、客户、同步状态和关联工单号。
warehouses：出库明细涉及的仓库 ID/名称去重集合。
items：parent_id=0 的物料汇总行，含物料编号、名称、分类、规格、仓库、数量、单价、总额、出库人及时间。
serials：仅 includeSerials=true 返回 SN 子行；另返回 serialTotal/serialTruncated。
processes：schedule_state=2 的已处理记录，按操作时间、ID 正序，状态码与文案同时返回。
address：商城订单地址或主单地址。
logistics：发货方式、快递公司、运单号、配送人和收货信息。
files.application/files.confirmation：申请图片和确认出库图片。服务不持有 OSS 签名密钥，返回文件 ID、文件名及存储对象定位信息，不生成临时访问 URL。
certificate：凭证备注与 file_type=4/in_out_allocation_type=99 的凭证文件。

调拨出库单允许直接查询，并以 sourceType=ALLOCATION 标识。

4. 行级权限

列表和详情使用完全相同的主查询权限条件，业务筛选只能缩小结果：

总部身份（权限组 isagent=0）：不过滤。
代理商身份（权限组 isagent=1）：可见范围为以下条件的并集：
- 主单 agent_id 属于自己、直属下级或 warehouse_agent_auth 授权代管代理；
- 出库明细涉及的仓库，其 warehouse.agent_id 或 warehouse.manager_agent_id 属于上述代理范围；
- 当前用户存在该主单的未删除审核/处理记录。
代理商用户未关联代理商、权限组不存在或配置异常时失败关闭。

详情不存在与无权访问统一抛出 NOT_FOUND_OR_FORBIDDEN，防止通过 ID/单号探测数据。

权限通过主表查询中的关联 EXISTS 条件完成，不先查询大量 ID 再拼接 IN。

5. 测试与验收

列表：分页上限、各类日期/状态/仓库条件、批量聚合和状态文案。
详情：ID/单号参数校验、双条件一致性、调拨单、SN 默认关闭与截断、附件/凭证分组。
权限：总部、代理范围、负责管理仓库、处理人、无代理失败关闭；详情查询必须复用相同过滤器。
构建：固定 TZ=Asia/Shanghai 执行后端测试；不连接生产数据库、不执行部署。

4.9 KiB Raw Blame History Unescape Escape