92 lines
4.9 KiB
Markdown
92 lines
4.9 KiB
Markdown
# 出库单 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` 执行后端测试；不连接生产数据库、不执行部署。
|