3.3 KiB
3.3 KiB
入库单 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； 调拨派生入库单的申请附件（fileType=0）与审批流图片（fileType=3）挂在调拨单维度 （aggregate_id=调拨单id, in_out_allocation_type=2），详情按allocationOrderNo回查合并： 前者并入files.application，后者在files.allocationAudit；relatedOutOrder：仅出库单号和建议调用的warehouse.out.detail.query工具名。
4. 权限与安全
列表和详情强制复用 PermissionService.applyWarehouseInRowFilter：
- 总部身份查看全部；
- 代理身份可见范围是主单所属代理范围、所属或负责仓库涉及、本人参与处理三类并集；
- 代理范围包含自己、直属下级和
warehouse_agent_auth授权代管代理； - 权限组异常或代理用户未关联代理商时失败关闭；
- 详情不存在与无权访问统一返回
NOT_FOUND_OR_FORBIDDEN。
权限使用主查询中的 EXISTS，所有业务筛选均只能缩小结果。关联出库不提前判断是否可访问，
避免形成旁路探测；调用方若需要内容，必须再调用出库详情工具并接受其独立鉴权。
5. 验收
- 列表分页、日期校验、仓库过滤、批量富化和状态文案；
- 详情双条件、调拨单、物料汇总、SN 默认关闭/截断、附件分类、出库索引；
- 总部、代理范围、仓库负责人、流程参与人和异常配置失败关闭；
- 固定
TZ=Asia/Shanghai执行全量后端测试，不连接生产数据库、不执行部署。