feat(mcp): 新增仓库单据处理人改派写工具 warehouse.order.handler.update(REQ-20261107-0002)

- 平台首个 kind=write 工具,研发/运维专用 scope 门禁,无行级权限
- 按单号改派出库/入库/调拨/划转单当前待办处理人:UPDATE 流程物理表
  warehouse_out_audit_process / warehouse_in_audit_process / warehouse_allocati_process
  的 schedule_state=1 待办行 user_id/user_name,补 modify_id/modify_time
- 调拨/划转按 warehouse_allocation.op_type(0/2) 一致性校验;并行待办行全部改派
- 新处理人按手机号查 m0 user(soft_delete=0 精确匹配);服务身份 Token 拒绝
- 新增 WarehouseAllocatiProcess 实体+Mapper,WarehouseAllocation 补 orderState 列
- 525 tests 全绿(+10)
This commit is contained in:
my_local_kimi_dev2
2026-11-07 16:28:22 +08:00
parent 1a7a761a66
commit 52ffe8eac2
10 changed files with 771 additions and 2 deletions
@@ -0,0 +1,45 @@
package me.iiv.agent.entity.m2;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Getter;
import lombok.Setter;
import lombok.ToString;
import java.io.Serializable;
import java.util.Date;
/** 调拨/采购/划转流程物理表 warehouse_allocati_process(m2):老系统拼写少一个 on,勿与视图 warehouse_allocation_process 混淆。 */
@Getter
@Setter
@ToString
@TableName("warehouse_allocati_process")
public class WarehouseAllocatiProcess implements Serializable {
@TableId(value = "id", type = IdType.AUTO)
private Long id;
private Long createId;
private Date createTime;
private Long modifyId;
private Date modifyTime;
private Integer softDelete;
private Long warehouseAllocationId;
private Long warehouseOutId;
private String warehouseOutName;
/** 办理类型(0:调拨;1:采购) */
private Integer opType;
private Long userId;
private String userName;
private Date operationTime;
/** 待办状态(0:无需待办;1:待办;2:已办) */
private Integer scheduleState;
/** 审核状态(0:审核驳回/驳回;1:审核通过/出库确认) */
private Integer auditState;
private Integer auditLevel;
private String memo;
/** 操作主题(0:审核通过;1:审核驳回;2:撤销入库;3:转出确认;4:出库确认驳回;5:驳回修改提交;6:入库确认;7:出库确认;8:发起人撤销) */
private Integer operationTheme;
/** 操作类型(0:审批流操作;1:确认入库操作;2:确认出库操作;3:本人修改;4:驳回或修改操作) */
private Integer operationType;
}
@@ -23,4 +23,5 @@ public class WarehouseAllocation implements Serializable {
@TableField("allocation_order_no")
private String allocationOrderNo;
private Integer opType;
private Integer orderState;
}
@@ -10,7 +10,7 @@ import lombok.ToString;
import java.io.Serializable;
import java.util.Date;
/** 入库单审批/处理流程(m2,只读)。 */
/** 入库单审批/处理流程(m2):WarehouseOrderAdminTools 改派处理人时会 UPDATE 待办行。 */
@Getter
@Setter
@ToString
@@ -18,6 +18,8 @@ import java.util.Date;
public class WarehouseInAuditProcess implements Serializable {
@TableId(value = "id", type = IdType.AUTO)
private Long id;
private Long modifyId;
private Date modifyTime;
private Integer softDelete;
private Long warehouseInId;
private Long warehouseId;
@@ -10,7 +10,7 @@ import lombok.ToString;
import java.io.Serializable;
import java.util.Date;
/** 出库单审批/处理记录(m2,只读)。 */
/** 出库单审批/处理记录(m2):WarehouseOrderAdminTools 改派处理人时会 UPDATE 待办行。 */
@Getter
@Setter
@ToString
@@ -18,6 +18,8 @@ import java.util.Date;
public class WarehouseOutAuditProcess implements Serializable {
@TableId(value = "id", type = IdType.AUTO)
private Long id;
private Long modifyId;
private Date modifyTime;
private Integer softDelete;
private Long warehouseOutId;
private Long warehouseId;
@@ -0,0 +1,7 @@
package me.iiv.agent.mapper.m2;
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import me.iiv.agent.entity.m2.WarehouseAllocatiProcess;
public interface WarehouseAllocatiProcessMapper extends BaseMapper<WarehouseAllocatiProcess> {
}
@@ -0,0 +1,300 @@
package me.iiv.agent.mcp.tool;
import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
import me.iiv.agent.entity.m0.User;
import me.iiv.agent.entity.m2.WarehouseAllocatiProcess;
import me.iiv.agent.entity.m2.WarehouseAllocation;
import me.iiv.agent.entity.m2.WarehouseIn;
import me.iiv.agent.entity.m2.WarehouseInAuditProcess;
import me.iiv.agent.entity.m2.WarehouseOut;
import me.iiv.agent.entity.m2.WarehouseOutAuditProcess;
import me.iiv.agent.mapper.m0.UserMapper;
import me.iiv.agent.mapper.m2.WarehouseAllocatiProcessMapper;
import me.iiv.agent.mapper.m2.WarehouseAllocationMapper;
import me.iiv.agent.mapper.m2.WarehouseInAuditProcessMapper;
import me.iiv.agent.mapper.m2.WarehouseInMapper;
import me.iiv.agent.mapper.m2.WarehouseOutAuditProcessMapper;
import me.iiv.agent.mapper.m2.WarehouseOutMapper;
import me.iiv.agent.mcp.McpCallContextHolder;
import me.iiv.agent.mcp.McpErrorCode;
import me.iiv.agent.mcp.ToolCallException;
import me.iiv.agent.mcp.ToolObject;
import me.iiv.agent.mcp.XqTool;
import me.iiv.agent.security.AuthContextHolder;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Component;
import org.springframework.util.StringUtils;
import java.util.ArrayList;
import java.util.Date;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
/**
* 仓库单据处理人改派工具(REQ-20261107-0002,设计文档 doc/warehouse-order-handler-update-mcp-design.md)。
* 运维/研发专用:按单号把出库/入库/调拨/划转单的当前待办处理人改派给他人,
* 不做行级权限,访问控制完全靠专用 scope 门禁。平台首个 kind=write 工具。
* 改派语义 = UPDATE 流程物理表(warehouse_out_audit_process / warehouse_in_audit_process /
* warehouse_allocati_process)中 schedule_state=1 待办行的 user_id/user_name。
*/
@Component
public class WarehouseOrderAdminTools implements ToolObject {
private static final Logger log = LoggerFactory.getLogger(WarehouseOrderAdminTools.class);
private static final Map<Integer, String> OUT_ORDER_STATE_TEXT = Map.of(
0, "待审核", 1, "被驳回", 2, "待出库", 3, "已完成", 4, "已撤销", 5, "作废");
private static final Map<Integer, String> IN_ORDER_STATE_TEXT = Map.of(
0, "待审核", 1, "被驳回", 2, "待入库", 3, "已完成", 4, "已撤销", 5, "作废");
private static final Map<Integer, String> ALLOCATION_ORDER_STATE_TEXT = Map.of(
0, "待审核", 1, "被驳回", 2, "待出库", 3, "待入库", 4, "已完成", 5, "已撤销", 6, "作废");
final WarehouseOutMapper outMapper;
final WarehouseInMapper inMapper;
final WarehouseAllocationMapper allocationMapper;
final WarehouseOutAuditProcessMapper outAuditProcessMapper;
final WarehouseInAuditProcessMapper inAuditProcessMapper;
final WarehouseAllocatiProcessMapper allocatiProcessMapper;
final UserMapper userMapper;
public WarehouseOrderAdminTools(WarehouseOutMapper outMapper,
WarehouseInMapper inMapper,
WarehouseAllocationMapper allocationMapper,
WarehouseOutAuditProcessMapper outAuditProcessMapper,
WarehouseInAuditProcessMapper inAuditProcessMapper,
WarehouseAllocatiProcessMapper allocatiProcessMapper,
UserMapper userMapper) {
this.outMapper = outMapper;
this.inMapper = inMapper;
this.allocationMapper = allocationMapper;
this.outAuditProcessMapper = outAuditProcessMapper;
this.inAuditProcessMapper = inAuditProcessMapper;
this.allocatiProcessMapper = allocatiProcessMapper;
this.userMapper = userMapper;
}
@XqTool(category = "admin", kind = "write")
@Tool(name = "warehouse.order.handler.update", description = "【写操作·研发/运维专用】按单号改派仓库单据的当前待办处理人,"
+ "覆盖出库单(orderType=out)、入库单(in)、调拨单(allocation)、划转单(transfer)。"
+ "机制:把该单流程物理表中 schedule_state=1 的待办行 user_id/user_name 改成新处理人,"
+ "并行多条待办行全部改派;不动主表、不重推审批流、不发消息通知。"
+ "新处理人按手机号在 m0 user 表精确匹配(soft_delete=0)。"
+ "无行级权限校验,任何单据都可改;访问控制靠 scope 绑定,每次调用写审计日志。"
+ "单据无待办处理人(已完成/已撤销/作废)时返回错误并附 orderStateText。"
+ "返回 before/after 明细(changedRows)与 changedCount。")
public Map<String, Object> warehouseOrderHandlerUpdate(
@ToolParam(description = "单据类型:out=出库单 in=入库单 allocation=调拨单 transfer=划转单") String orderType,
@ToolParam(description = "单据编号(精确匹配,如 OUT20261001001)") String orderNo,
@ToolParam(description = "新处理人手机号(m0 user.mobile 精确匹配)") String newHandlerMobile,
@ToolParam(required = false, description = "改派原因,写入审计日志") String memo) {
String type = normalizeOrderType(orderType);
String docNo = requireText(orderNo, "orderNo");
String mobile = requireText(newHandlerMobile, "newHandlerMobile");
User caller = AuthContextHolder.get().getUser();
if (caller == null) {
throw new ToolCallException(McpErrorCode.PERMISSION_DENIED,
"该工具要求用户身份 Token 调用(改派人需可追溯),服务身份 Token 不可用");
}
OrderRef order = locateOrder(type, docNo);
User newHandler = locateUserByMobile(mobile);
List<ProcessRow> pendingRows = pendingRows(type, order.docId());
if (pendingRows.isEmpty()) {
throw new ToolCallException(McpErrorCode.NOT_FOUND_OR_FORBIDDEN,
"该单据当前无待办处理人(orderState=" + order.orderStateText()
+ ",已完成/已撤销/作废的单据不能改派)");
}
Date now = new Date();
int updated = reassign(type, order.docId(), newHandler, caller.getId(), now);
List<Map<String, Object>> changedRows = new ArrayList<>();
for (ProcessRow row : pendingRows) {
Map<String, Object> change = new LinkedHashMap<>();
change.put("processId", row.processId());
change.put("oldUserId", row.userId());
change.put("oldUserName", row.userName());
change.put("newUserId", newHandler.getId());
change.put("newUserName", newHandler.getName());
changedRows.add(change);
}
String requestId = McpCallContextHolder.currentOrCreateRequestId();
log.info("warehouse.order.handler.update 改派完成 requestId={} orderType={} orderNo={} "
+ "newHandler={}({}) changedCount={} memo={} caller={}",
requestId, type, docNo, newHandler.getId(), newHandler.getName(),
updated, memo, caller.getId());
Map<String, Object> result = new LinkedHashMap<>();
result.put("orderType", type);
result.put("orderNo", docNo);
result.put("orderId", order.docId());
result.put("orderState", order.orderState());
result.put("orderStateText", order.orderStateText());
result.put("changedRows", changedRows);
result.put("changedCount", updated);
result.put("requestId", requestId);
return result;
}
private static String normalizeOrderType(String orderType) {
String type = orderType == null ? "" : orderType.trim().toLowerCase();
return switch (type) {
case "out", "in", "allocation", "transfer" -> type;
default -> throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT,
"orderType 必须是 out / in / allocation / transfer");
};
}
private static String requireText(String value, String param) {
if (!StringUtils.hasText(value)) {
throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT, param + " 不能为空");
}
return value.trim();
}
/** 按单号定位单据(soft_delete=0 精确匹配),并做调拨/划转 op_type 一致性校验。 */
private OrderRef locateOrder(String type, String orderNo) {
return switch (type) {
case "out" -> {
WarehouseOut order = single(outMapper.selectList(new LambdaQueryWrapper<WarehouseOut>()
.eq(WarehouseOut::getSoftDelete, 0)
.eq(WarehouseOut::getOutOrderNo, orderNo)), "出库单", orderNo);
yield new OrderRef(order.getId(), order.getOrderState(),
text(OUT_ORDER_STATE_TEXT, order.getOrderState()));
}
case "in" -> {
WarehouseIn order = single(inMapper.selectList(new LambdaQueryWrapper<WarehouseIn>()
.eq(WarehouseIn::getSoftDelete, 0)
.eq(WarehouseIn::getInOrderNo, orderNo)), "入库单", orderNo);
yield new OrderRef(order.getId(), order.getOrderState(),
text(IN_ORDER_STATE_TEXT, order.getOrderState()));
}
default -> {
WarehouseAllocation order = single(allocationMapper.selectList(
new LambdaQueryWrapper<WarehouseAllocation>()
.eq(WarehouseAllocation::getSoftDelete, 0)
.eq(WarehouseAllocation::getAllocationOrderNo, orderNo)),
"调拨/划转单", orderNo);
int expectedOpType = "allocation".equals(type) ? 0 : 2;
Integer opType = order.getOpType();
if (opType == null || opType != expectedOpType) {
String actual = opType == null ? "未知" : switch (opType) {
case 0 -> "调拨单(orderType=allocation)";
case 1 -> "采购单(本工具不支持,仅支持调拨/划转)";
default -> "划转单(orderType=transfer)";
};
throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT,
"单号 " + orderNo + " 实际是" + actual + ",与 orderType=" + type + " 不一致");
}
yield new OrderRef(order.getId(), order.getOrderState(),
text(ALLOCATION_ORDER_STATE_TEXT, order.getOrderState()));
}
};
}
private static <T> T single(List<T> rows, String docTypeText, String orderNo) {
if (rows.isEmpty()) {
throw new ToolCallException(McpErrorCode.NOT_FOUND_OR_FORBIDDEN,
docTypeText + "单号 " + orderNo + " 不存在");
}
if (rows.size() > 1) {
throw new ToolCallException(McpErrorCode.DATA_INTEGRITY_ERROR,
docTypeText + "单号 " + orderNo + " 命中多条记录,请携带 request_id 联系运维排查");
}
return rows.get(0);
}
/** 新处理人:m0 user 表按手机号精确匹配且 soft_delete=0(王恒拍板口径)。 */
private User locateUserByMobile(String mobile) {
List<User> users = userMapper.selectList(new LambdaQueryWrapper<User>()
.eq(User::getSoftDelete, 0)
.eq(User::getMobile, mobile));
if (users.isEmpty()) {
throw new ToolCallException(McpErrorCode.INVALID_ARGUMENT,
"手机号 " + mobile + " 未匹配到有效用户(user 表 soft_delete=0)");
}
if (users.size() > 1) {
throw new ToolCallException(McpErrorCode.DATA_INTEGRITY_ERROR,
"手机号 " + mobile + " 命中多个有效用户,请携带 request_id 联系运维排查");
}
return users.get(0);
}
/** 当前待办行:流程物理表 schedule_state=1 且 soft_delete=0。 */
private List<ProcessRow> pendingRows(String type, Long docId) {
return switch (type) {
case "out" -> outAuditProcessMapper.selectList(new LambdaQueryWrapper<WarehouseOutAuditProcess>()
.eq(WarehouseOutAuditProcess::getSoftDelete, 0)
.eq(WarehouseOutAuditProcess::getScheduleState, 1)
.eq(WarehouseOutAuditProcess::getWarehouseOutId, docId)
.orderByAsc(WarehouseOutAuditProcess::getId)).stream()
.map(row -> new ProcessRow(row.getId(), row.getUserId(), row.getUserName()))
.toList();
case "in" -> inAuditProcessMapper.selectList(new LambdaQueryWrapper<WarehouseInAuditProcess>()
.eq(WarehouseInAuditProcess::getSoftDelete, 0)
.eq(WarehouseInAuditProcess::getScheduleState, 1)
.eq(WarehouseInAuditProcess::getWarehouseInId, docId)
.orderByAsc(WarehouseInAuditProcess::getId)).stream()
.map(row -> new ProcessRow(row.getId(), row.getUserId(), row.getUserName()))
.toList();
default -> allocatiProcessMapper.selectList(new LambdaQueryWrapper<WarehouseAllocatiProcess>()
.eq(WarehouseAllocatiProcess::getSoftDelete, 0)
.eq(WarehouseAllocatiProcess::getScheduleState, 1)
.eq(WarehouseAllocatiProcess::getWarehouseAllocationId, docId)
.orderByAsc(WarehouseAllocatiProcess::getId)).stream()
.map(row -> new ProcessRow(row.getId(), row.getUserId(), row.getUserName()))
.toList();
};
}
/** 并行多条待办行全部改派,并补 modify_id/modify_time。返回影响行数。 */
private int reassign(String type, Long docId, User newHandler, Long callerUserId, Date now) {
return switch (type) {
case "out" -> outAuditProcessMapper.update(null,
new LambdaUpdateWrapper<WarehouseOutAuditProcess>()
.eq(WarehouseOutAuditProcess::getSoftDelete, 0)
.eq(WarehouseOutAuditProcess::getScheduleState, 1)
.eq(WarehouseOutAuditProcess::getWarehouseOutId, docId)
.set(WarehouseOutAuditProcess::getUserId, newHandler.getId())
.set(WarehouseOutAuditProcess::getUserName, newHandler.getName())
.set(WarehouseOutAuditProcess::getModifyId, callerUserId)
.set(WarehouseOutAuditProcess::getModifyTime, now));
case "in" -> inAuditProcessMapper.update(null,
new LambdaUpdateWrapper<WarehouseInAuditProcess>()
.eq(WarehouseInAuditProcess::getSoftDelete, 0)
.eq(WarehouseInAuditProcess::getScheduleState, 1)
.eq(WarehouseInAuditProcess::getWarehouseInId, docId)
.set(WarehouseInAuditProcess::getUserId, newHandler.getId())
.set(WarehouseInAuditProcess::getUserName, newHandler.getName())
.set(WarehouseInAuditProcess::getModifyId, callerUserId)
.set(WarehouseInAuditProcess::getModifyTime, now));
default -> allocatiProcessMapper.update(null,
new LambdaUpdateWrapper<WarehouseAllocatiProcess>()
.eq(WarehouseAllocatiProcess::getSoftDelete, 0)
.eq(WarehouseAllocatiProcess::getScheduleState, 1)
.eq(WarehouseAllocatiProcess::getWarehouseAllocationId, docId)
.set(WarehouseAllocatiProcess::getUserId, newHandler.getId())
.set(WarehouseAllocatiProcess::getUserName, newHandler.getName())
.set(WarehouseAllocatiProcess::getModifyId, callerUserId)
.set(WarehouseAllocatiProcess::getModifyTime, now));
};
}
private static String text(Map<Integer, String> texts, Integer code) {
return code == null ? null : texts.getOrDefault(code, "未知");
}
private record OrderRef(Long docId, Integer orderState, String orderStateText) {
}
private record ProcessRow(Long processId, Long userId, String userName) {
}
}