60 lines
3.0 KiB
Markdown
60 lines
3.0 KiB
Markdown
# 入库单 MCP 工具设计
|
||
|
||
## 1. 范围与评审结论
|
||
|
||
参考旧系统 `POST /myWarehouseIn/allListByPage` 与 `GET /myWarehouseIn/lookDetail`，新增：
|
||
|
||
| 工具 | 分类 | 用途 |
|
||
|---|---|---|
|
||
| `warehouse.in.list.query` | warehouse/read | 分页查询入库单 |
|
||
| `warehouse.in.detail.query` | warehouse/read | 按主键或入库单号查询详情 |
|
||
|
||
自评审通过，确认采用以下产品取舍：调拨入库单允许直接查询详情；关联出库单仅返回索引，
|
||
不内嵌完整出库信息。工具只读 m2，不新增业务表或 Flyway migration；启动后由
|
||
`ToolSyncService` 自动登记，需由管理员绑定 Scope 后才可调用。
|
||
|
||
## 2. 列表
|
||
|
||
- 单号：入库、调拨、关联出库、商城、送货、装机、取货、撤机单号。
|
||
- 归属：代理、仓库、入库类型、申请人。
|
||
- 状态与物流：订单状态、入库同步状态、物流公司和运单号。
|
||
- 日期：`inDateFrom/inDateTo` 精确过滤 `in_date`；`applyDateFrom/applyDateTo`
|
||
过滤 `apply_date`，结束日期含当天。不会复制旧接口将入库日期改写成申请日期的异常逻辑。
|
||
- 分页：page 默认 1，rows 默认 20、上限 100。
|
||
|
||
返回主单、来源类型、状态文案、涉及仓库、待办人、实际入库人及日期、物流和关联单号。
|
||
本页明细与待办按主单 ID 批量查询，避免 N+1。
|
||
|
||
`sourceType` 的优先级为 `ALLOCATION`、`OUTBOUND_LINKED`、`MALL`、`NORMAL`。
|
||
|
||
## 3. 详情
|
||
|
||
`id`、`inOrderNo` 至少传一个；同时传入时必须匹配同一条可见记录。详情返回：
|
||
|
||
- `record`、`sceneType`、涉及仓库；
|
||
- 按物料定义、物料索引和仓库汇总的 `items`；
|
||
- 可选 `serials` 以及完整 `serialTotal`、`serialTruncated`；
|
||
- `schedule_state=2` 的已处理流程；
|
||
- `file_type=0/1` 的申请、确认入库附件，仅返回 OSS 对象定位，不生成签名 URL；
|
||
- `relatedOutOrder`：仅出库单号和建议调用的 `warehouse.out.detail.query` 工具名。
|
||
|
||
## 4. 权限与安全
|
||
|
||
列表和详情强制复用 `PermissionService.applyWarehouseInRowFilter`：
|
||
|
||
- 总部身份查看全部；
|
||
- 代理身份可见范围是主单所属代理范围、所属或负责仓库涉及、本人参与处理三类并集；
|
||
- 代理范围包含自己、直属下级和 `warehouse_agent_auth` 授权代管代理；
|
||
- 权限组异常或代理用户未关联代理商时失败关闭；
|
||
- 详情不存在与无权访问统一返回 `NOT_FOUND_OR_FORBIDDEN`。
|
||
|
||
权限使用主查询中的 `EXISTS`，所有业务筛选均只能缩小结果。关联出库不提前判断是否可访问，
|
||
避免形成旁路探测；调用方若需要内容，必须再调用出库详情工具并接受其独立鉴权。
|
||
|
||
## 5. 验收
|
||
|
||
- 列表分页、日期校验、仓库过滤、批量富化和状态文案；
|
||
- 详情双条件、调拨单、物料汇总、SN 默认关闭/截断、附件分类、出库索引；
|
||
- 总部、代理范围、仓库负责人、流程参与人和异常配置失败关闭；
|
||
- 固定 `TZ=Asia/Shanghai` 执行全量后端测试，不连接生产数据库、不执行部署。
|