feat(wms): 添加钢卷变更日志功能

- 新增钢卷变更日志的Service接口及实现类
- 创建钢卷变更日志的业务对象BO和视图对象VO
- 实现钢卷变更日志的控制器提供CRUD操作接口
- 添加钢卷变更日志的数据库映射和表结构定义
- 开发钢卷变更日志注解和AOP切面自动记录变更
- 定义钢卷变更类型的枚举类支持多种变更场景
- 在钢卷相关业务方法中集成变更日志记录功能
- 创建钢卷变更日志的数据表SQL脚本文件

klp-wms/src/main/java/com/klp/controller/WmsCoilChangeLogController.java

@@ -0,0 +1,99 @@
+package com.klp.controller;
+
+import java.util.List;
+import java.util.Arrays;
+
+import lombok.RequiredArgsConstructor;
+import javax.servlet.http.HttpServletResponse;
+import javax.validation.constraints.*;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.validation.annotation.Validated;
+import com.klp.common.annotation.RepeatSubmit;
+import com.klp.common.annotation.Log;
+import com.klp.common.core.controller.BaseController;
+import com.klp.common.core.domain.PageQuery;
+import com.klp.common.core.domain.R;
+import com.klp.common.core.validate.AddGroup;
+import com.klp.common.core.validate.EditGroup;
+import com.klp.common.enums.BusinessType;
+import com.klp.common.utils.poi.ExcelUtil;
+import com.klp.domain.vo.WmsCoilChangeLogVo;
+import com.klp.domain.bo.WmsCoilChangeLogBo;
+import com.klp.service.IWmsCoilChangeLogService;
+import com.klp.common.core.page.TableDataInfo;
+
+/**
+ * 钢卷变更日志
+ *
+ * @author klp
+ * @date 2026-07-11
+ */
+@Validated
+@RequiredArgsConstructor
+@RestController
+@RequestMapping("/wms/coilChangeLog")
+public class WmsCoilChangeLogController extends BaseController {
+
+    private final IWmsCoilChangeLogService iWmsCoilChangeLogService;
+
+    /**
+     * 查询钢卷变更日志列表
+     */
+    @GetMapping("/list")
+    public TableDataInfo<WmsCoilChangeLogVo> list(WmsCoilChangeLogBo bo, PageQuery pageQuery) {
+        return iWmsCoilChangeLogService.queryPageList(bo, pageQuery);
+    }
+
+    /**
+     * 导出钢卷变更日志列表
+     */
+    @Log(title = "钢卷变更日志", businessType = BusinessType.EXPORT)
+    @PostMapping("/export")
+    public void export(WmsCoilChangeLogBo bo, HttpServletResponse response) {
+        List<WmsCoilChangeLogVo> list = iWmsCoilChangeLogService.queryList(bo);
+        ExcelUtil.exportExcel(list, "钢卷变更日志", WmsCoilChangeLogVo.class, response);
+    }
+
+    /**
+     * 获取钢卷变更日志详细信息
+     *
+     * @param logId 主键
+     */
+    @GetMapping("/{logId}")
+    public R<WmsCoilChangeLogVo> getInfo(@NotNull(message = "主键不能为空")
+                                     @PathVariable Long logId) {
+        return R.ok(iWmsCoilChangeLogService.queryById(logId));
+    }
+
+    /**
+     * 新增钢卷变更日志
+     */
+    @Log(title = "钢卷变更日志", businessType = BusinessType.INSERT)
+    @RepeatSubmit()
+    @PostMapping()
+    public R<Void> add(@Validated(AddGroup.class) @RequestBody WmsCoilChangeLogBo bo) {
+        return toAjax(iWmsCoilChangeLogService.insertByBo(bo));
+    }
+
+    /**
+     * 修改钢卷变更日志
+     */
+    @Log(title = "钢卷变更日志", businessType = BusinessType.UPDATE)
+    @RepeatSubmit()
+    @PutMapping()
+    public R<Void> edit(@Validated(EditGroup.class) @RequestBody WmsCoilChangeLogBo bo) {
+        return toAjax(iWmsCoilChangeLogService.updateByBo(bo));
+    }
+
+    /**
+     * 删除钢卷变更日志
+     *
+     * @param logIds 主键串
+     */
+    @Log(title = "钢卷变更日志", businessType = BusinessType.DELETE)
+    @DeleteMapping("/{logIds}")
+    public R<Void> remove(@NotEmpty(message = "主键不能为空")
+                          @PathVariable Long[] logIds) {
+        return toAjax(iWmsCoilChangeLogService.deleteWithValidByIds(Arrays.asList(logIds), true));
+    }
+}

klp-wms/src/main/java/com/klp/domain/WmsCoilChangeLog.java

@@ -0,0 +1,49 @@
+package com.klp.domain;
+
+import com.baomidou.mybatisplus.annotation.*;
+import com.klp.common.core.domain.BaseEntity;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+
+/**
+ * 钢卷变更日志对象 wms_material_coil_change_log
+ *
+ * @author klp
+ * @date 2026-07-11
+ */
+@Data
+@EqualsAndHashCode(callSuper = true)
+@TableName("wms_coil_change_log")
+public class WmsCoilChangeLog extends BaseEntity {
+
+    private static final long serialVersionUID = 1L;
+
+    /** 主键ID */
+    @TableId(value = "log_id")
+    private Long logId;
+
+    /** 变更类型：UPDATE/INSERT/PROCESS/SPLIT/MERGE/DELETE/ROLLBACK/EXPORT/QUALITY_CHANGE */
+    private String changeType;
+
+    /** 变更前钢卷ID */
+    private Long oldCoilId;
+
+    /** 变更后钢卷ID */
+    private Long newCoilId;
+
+    /** 变更前钢卷号（冗余，方便查看） */
+    private String oldCoilNo;
+
+    /** 变更后钢卷号 */
+    private String newCoilNo;
+
+    /** 变更字段差异 JSON：{"fieldName":{"old":"旧值","new":"新值"},...} */
+    private String changedFields;
+
+    /** 操作描述 */
+    private String operationDesc;
+
+    /** 删除标志（0=正常，1=已删除） */
+    @TableLogic
+    private Integer delFlag;
+}

klp-wms/src/main/java/com/klp/domain/bo/WmsCoilChangeLogBo.java

@@ -0,0 +1,66 @@
+package com.klp.domain.bo;
+
+import com.klp.common.core.domain.BaseEntity;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import javax.validation.constraints.*;
+
+
+/**
+ * 钢卷变更日志业务对象 wms_coil_change_log
+ *
+ * @author klp
+ * @date 2026-07-11
+ */
+
+@Data
+@EqualsAndHashCode(callSuper = true)
+public class WmsCoilChangeLogBo extends BaseEntity {
+
+    /**
+     * 主键ID
+     */
+    private Long logId;
+
+    /**
+     * 变更类型: UPDATE/INSERT/PROCESS/SPLIT/MERGE/DELETE/ROLLBACK/EXPORT/QUALITY_CHANGE
+     */
+    private String changeType;
+
+    /**
+     * 变更前钢卷ID
+     */
+    private Long oldCoilId;
+
+    /**
+     * 变更后钢卷ID（纯删除时为NULL）
+     */
+    private Long newCoilId;
+
+    /**
+     * 变更前钢卷号（冗余，方便查看）
+     */
+    private String oldCoilNo;
+
+    /**
+     * 变更后钢卷号
+     */
+    private String newCoilNo;
+
+    /**
+     * 变更字段差异 JSON: {"fieldName":{"old":"旧值","new":"新值"},...}
+     */
+    private String changedFields;
+
+    /**
+     * 操作描述
+     */
+    private String operationDesc;
+
+    /**
+     * 备注
+     */
+    private String remark;
+
+
+}

klp-wms/src/main/java/com/klp/domain/vo/WmsCoilChangeLogVo.java

@@ -0,0 +1,79 @@
+package com.klp.domain.vo;
+
+import com.alibaba.excel.annotation.ExcelIgnoreUnannotated;
+import com.alibaba.excel.annotation.ExcelProperty;
+import com.klp.common.annotation.ExcelDictFormat;
+import com.klp.common.convert.ExcelDictConvert;
+import lombok.Data;
+
+
+/**
+ * 钢卷变更日志视图对象 wms_coil_change_log
+ *
+ * @author klp
+ * @date 2026-07-11
+ */
+@Data
+@ExcelIgnoreUnannotated
+public class WmsCoilChangeLogVo {
+
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * 主键ID
+     */
+    @ExcelProperty(value = "主键ID")
+    private Long logId;
+
+    /**
+     * 变更类型: UPDATE/INSERT/PROCESS/SPLIT/MERGE/DELETE/ROLLBACK/EXPORT/QUALITY_CHANGE
+     */
+    @ExcelProperty(value = "变更类型: UPDATE/INSERT/PROCESS/SPLIT/MERGE/DELETE/ROLLBACK/EXPORT/QUALITY_CHANGE")
+    private String changeType;
+
+    /**
+     * 变更前钢卷ID
+     */
+    @ExcelProperty(value = "变更前钢卷ID")
+    private Long oldCoilId;
+
+    /**
+     * 变更后钢卷ID（纯删除时为NULL）
+     */
+    @ExcelProperty(value = "变更后钢卷ID", converter = ExcelDictConvert.class)
+    @ExcelDictFormat(readConverterExp = "纯=删除时为NULL")
+    private Long newCoilId;
+
+    /**
+     * 变更前钢卷号（冗余，方便查看）
+     */
+    @ExcelProperty(value = "变更前钢卷号", converter = ExcelDictConvert.class)
+    @ExcelDictFormat(readConverterExp = "冗=余，方便查看")
+    private String oldCoilNo;
+
+    /**
+     * 变更后钢卷号
+     */
+    @ExcelProperty(value = "变更后钢卷号")
+    private String newCoilNo;
+
+    /**
+     * 变更字段差异 JSON: {"fieldName":{"old":"旧值","new":"新值"},...}
+     */
+    @ExcelProperty(value = "变更字段差异")
+    private String changedFields;
+
+    /**
+     * 操作描述
+     */
+    @ExcelProperty(value = "操作描述")
+    private String operationDesc;
+
+    /**
+     * 备注
+     */
+    @ExcelProperty(value = "备注")
+    private String remark;
+
+
+}

klp-wms/src/main/java/com/klp/mapper/WmsCoilChangeLogMapper.java

@@ -0,0 +1,15 @@
+package com.klp.mapper;
+
+import com.klp.domain.WmsCoilChangeLog;
+import com.klp.domain.vo.WmsCoilChangeLogVo;
+import com.klp.common.core.mapper.BaseMapperPlus;
+
+/**
+ * 钢卷变更日志Mapper接口
+ *
+ * @author klp
+ * @date 2026-07-11
+ */
+public interface WmsCoilChangeLogMapper extends BaseMapperPlus<WmsCoilChangeLogMapper, WmsCoilChangeLog, WmsCoilChangeLogVo> {
+
+}

klp-wms/src/main/java/com/klp/service/IWmsCoilChangeLogService.java

@@ -0,0 +1,49 @@
+package com.klp.service;
+
+import com.klp.domain.WmsCoilChangeLog;
+import com.klp.domain.vo.WmsCoilChangeLogVo;
+import com.klp.domain.bo.WmsCoilChangeLogBo;
+import com.klp.common.core.page.TableDataInfo;
+import com.klp.common.core.domain.PageQuery;
+
+import java.util.Collection;
+import java.util.List;
+
+/**
+ * 钢卷变更日志Service接口
+ *
+ * @author klp
+ * @date 2026-07-11
+ */
+public interface IWmsCoilChangeLogService {
+
+    /**
+     * 查询钢卷变更日志
+     */
+    WmsCoilChangeLogVo queryById(Long logId);
+
+    /**
+     * 查询钢卷变更日志列表
+     */
+    TableDataInfo<WmsCoilChangeLogVo> queryPageList(WmsCoilChangeLogBo bo, PageQuery pageQuery);
+
+    /**
+     * 查询钢卷变更日志列表
+     */
+    List<WmsCoilChangeLogVo> queryList(WmsCoilChangeLogBo bo);
+
+    /**
+     * 新增钢卷变更日志
+     */
+    Boolean insertByBo(WmsCoilChangeLogBo bo);
+
+    /**
+     * 修改钢卷变更日志
+     */
+    Boolean updateByBo(WmsCoilChangeLogBo bo);
+
+    /**
+     * 校验并批量删除钢卷变更日志信息
+     */
+    Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);
+}

klp-wms/src/main/java/com/klp/service/impl/WmsCoilChangeLogServiceImpl.java

@@ -0,0 +1,115 @@
+package com.klp.service.impl;
+
+import cn.hutool.core.bean.BeanUtil;
+import com.klp.common.core.page.TableDataInfo;
+import com.klp.common.core.domain.PageQuery;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.toolkit.Wrappers;
+import com.klp.common.utils.StringUtils;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import com.klp.domain.bo.WmsCoilChangeLogBo;
+import com.klp.domain.vo.WmsCoilChangeLogVo;
+import com.klp.domain.WmsCoilChangeLog;
+import com.klp.mapper.WmsCoilChangeLogMapper;
+import com.klp.service.IWmsCoilChangeLogService;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Collection;
+
+/**
+ * 钢卷变更日志Service业务层处理
+ *
+ * @author klp
+ * @date 2026-07-11
+ */
+@RequiredArgsConstructor
+@Service
+public class WmsCoilChangeLogServiceImpl implements IWmsCoilChangeLogService {
+
+    private final WmsCoilChangeLogMapper baseMapper;
+
+    /**
+     * 查询钢卷变更日志
+     */
+    @Override
+    public WmsCoilChangeLogVo queryById(Long logId){
+        return baseMapper.selectVoById(logId);
+    }
+
+    /**
+     * 查询钢卷变更日志列表
+     */
+    @Override
+    public TableDataInfo<WmsCoilChangeLogVo> queryPageList(WmsCoilChangeLogBo bo, PageQuery pageQuery) {
+        LambdaQueryWrapper<WmsCoilChangeLog> lqw = buildQueryWrapper(bo);
+        Page<WmsCoilChangeLogVo> result = baseMapper.selectVoPage(pageQuery.build(), lqw);
+        return TableDataInfo.build(result);
+    }
+
+    /**
+     * 查询钢卷变更日志列表
+     */
+    @Override
+    public List<WmsCoilChangeLogVo> queryList(WmsCoilChangeLogBo bo) {
+        LambdaQueryWrapper<WmsCoilChangeLog> lqw = buildQueryWrapper(bo);
+        return baseMapper.selectVoList(lqw);
+    }
+
+    private LambdaQueryWrapper<WmsCoilChangeLog> buildQueryWrapper(WmsCoilChangeLogBo bo) {
+        Map<String, Object> params = bo.getParams();
+        LambdaQueryWrapper<WmsCoilChangeLog> lqw = Wrappers.lambdaQuery();
+        lqw.eq(StringUtils.isNotBlank(bo.getChangeType()), WmsCoilChangeLog::getChangeType, bo.getChangeType());
+        lqw.eq(bo.getOldCoilId() != null, WmsCoilChangeLog::getOldCoilId, bo.getOldCoilId());
+        lqw.eq(bo.getNewCoilId() != null, WmsCoilChangeLog::getNewCoilId, bo.getNewCoilId());
+        lqw.eq(StringUtils.isNotBlank(bo.getOldCoilNo()), WmsCoilChangeLog::getOldCoilNo, bo.getOldCoilNo());
+        lqw.eq(StringUtils.isNotBlank(bo.getNewCoilNo()), WmsCoilChangeLog::getNewCoilNo, bo.getNewCoilNo());
+        lqw.eq(StringUtils.isNotBlank(bo.getChangedFields()), WmsCoilChangeLog::getChangedFields, bo.getChangedFields());
+        lqw.eq(StringUtils.isNotBlank(bo.getOperationDesc()), WmsCoilChangeLog::getOperationDesc, bo.getOperationDesc());
+        return lqw;
+    }
+
+    /**
+     * 新增钢卷变更日志
+     */
+    @Override
+    public Boolean insertByBo(WmsCoilChangeLogBo bo) {
+        WmsCoilChangeLog add = BeanUtil.toBean(bo, WmsCoilChangeLog.class);
+        validEntityBeforeSave(add);
+        boolean flag = baseMapper.insert(add) > 0;
+        if (flag) {
+            bo.setLogId(add.getLogId());
+        }
+        return flag;
+    }
+
+    /**
+     * 修改钢卷变更日志
+     */
+    @Override
+    public Boolean updateByBo(WmsCoilChangeLogBo bo) {
+        WmsCoilChangeLog update = BeanUtil.toBean(bo, WmsCoilChangeLog.class);
+        validEntityBeforeSave(update);
+        return baseMapper.updateById(update) > 0;
+    }
+
+    /**
+     * 保存前的数据校验
+     */
+    private void validEntityBeforeSave(WmsCoilChangeLog entity){
+        //TODO 做一些数据校验,如唯一约束
+    }
+
+    /**
+     * 批量删除钢卷变更日志
+     */
+    @Override
+    public Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid) {
+        if(isValid){
+            //TODO 做一些业务上的校验,判断是否需要校验
+        }
+        return baseMapper.deleteBatchIds(ids) > 0;
+    }
+}

klp-wms/src/main/java/com/klp/service/impl/WmsCoilPackingDetailServiceImpl.java

@@ -7,6 +7,8 @@ import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
 import com.baomidou.mybatisplus.core.toolkit.Wrappers;
 import com.klp.common.utils.StringUtils;
+import com.klp.wms.annotation.CoilChangeLog;
+import com.klp.wms.enums.CoilChangeType;
 import lombok.RequiredArgsConstructor;
 import org.springframework.stereotype.Service;
 import com.klp.domain.bo.WmsCoilPackingDetailBo;
@@ -120,6 +122,7 @@ public class WmsCoilPackingDetailServiceImpl implements IWmsCoilPackingDetailSer
      */
     @Override
     @Transactional(rollbackFor = Exception.class)
+    @CoilChangeLog(value = "打包入库", changeType = CoilChangeType.UPDATE, coilIdBoField = "coilId")
     public Boolean insertByBo(WmsCoilPackingDetailBo bo) {
         Long packingId = bo.getPackingId();
         if (packingId == null) {
@@ -161,6 +164,7 @@ public class WmsCoilPackingDetailServiceImpl implements IWmsCoilPackingDetailSer
      */
     @Override
     @Transactional(rollbackFor = Exception.class)
+    @CoilChangeLog(value = "打包更新", changeType = CoilChangeType.UPDATE, coilIdBoField = "coilId")
     public Boolean updateByBo(WmsCoilPackingDetailBo bo) {
         Long packingId = bo.getPackingId();
         if (packingId == null) {

klp-wms/src/main/java/com/klp/service/impl/WmsMaterialCoilServiceImpl.java

@@ -16,6 +16,8 @@ import com.baomidou.mybatisplus.core.toolkit.Wrappers;
 import com.klp.common.helper.LoginHelper;
 import com.klp.common.utils.DateUtils;
 import com.klp.common.utils.StringUtils;
+import com.klp.wms.annotation.CoilChangeLog;
+import com.klp.wms.enums.CoilChangeType;
 import com.klp.domain.*;
 import com.klp.domain.bo.*;
 import com.klp.domain.vo.*;
@@ -1850,6 +1852,7 @@ public class WmsMaterialCoilServiceImpl implements IWmsMaterialCoilService {
 
     @Override
     @Transactional(rollbackFor = Exception.class)
+    @CoilChangeLog(value = "质量改判", changeType = CoilChangeType.QUALITY_CHANGE)
     public void updateQualityStatus(Long coilId, String newQuality, String reason) {
         if (coilId == null || StringUtils.isBlank(newQuality)) {
             log.warn("updateQualityStatus 参数不足: coilId={}, newQuality={}", coilId, newQuality);
@@ -1903,6 +1906,7 @@ public class WmsMaterialCoilServiceImpl implements IWmsMaterialCoilService {
      */
     @Override
     @Transactional(rollbackFor = Exception.class)
+    @CoilChangeLog(value = "入场收货", changeType = CoilChangeType.INSERT, coilIdBoField = "coilId")
     public WmsMaterialCoilVo insertByBo(WmsMaterialCoilBo bo) {
         // 检查当前钢卷号是否重复（新增）
         Map<String, Object> duplicateCheck = checkCoilNoDuplicate(null, null, bo.getCurrentCoilNo(), null);
@@ -2056,6 +2060,7 @@ public class WmsMaterialCoilServiceImpl implements IWmsMaterialCoilService {
      */
     @Override
     @Transactional(rollbackFor = Exception.class)
+    @CoilChangeLog(value = "钢卷加工", changeType = CoilChangeType.PROCESS, coilIdBoField = "coilId")
     public String updateByBo(WmsMaterialCoilBo bo, String qrcodeStepType) {
         String result;
         // 判断是否批量更新
@@ -2084,6 +2089,7 @@ public class WmsMaterialCoilServiceImpl implements IWmsMaterialCoilService {
      */
     @Override
     @Transactional(rollbackFor = Exception.class)
+    @CoilChangeLog(value = "简单更新", changeType = CoilChangeType.UPDATE, coilIdBoField = "coilId")
     public Boolean updateSimple(WmsMaterialCoilBo bo) {
         if (bo.getCoilId() == null) {
             throw new RuntimeException("钢卷ID不能为空");
@@ -3279,6 +3285,7 @@ public class WmsMaterialCoilServiceImpl implements IWmsMaterialCoilService {
      * 批量删除钢卷物料表
      */
     @Override
+    @CoilChangeLog(value = "删除", changeType = CoilChangeType.DELETE, coilIdParam = "ids", isBatch = true)
     public Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid) {
         if (isValid) {
             //TODO 做一些业务上的校验,判断是否需要校验
@@ -4010,6 +4017,7 @@ public class WmsMaterialCoilServiceImpl implements IWmsMaterialCoilService {
      * @return
      */
     @Override
+    @CoilChangeLog(value = "发货", changeType = CoilChangeType.EXPORT)
     public int exportCoil(Long coilId) {
         // 检查独占状态
         validateCoilOperationPermission(coilId, "发货");
@@ -4090,6 +4098,7 @@ public class WmsMaterialCoilServiceImpl implements IWmsMaterialCoilService {
      */
     @Override
     @Transactional(rollbackFor = Exception.class)
+    @CoilChangeLog(value = "合卷", changeType = CoilChangeType.MERGE, coilIdBoField = "coilId")
     public Long mergeCoils(WmsMaterialCoilBo bo) {
         if (bo.getNewCoils() == null || bo.getNewCoils().isEmpty()) {
             throw new RuntimeException("合卷操作需要提供参与合卷的钢卷列表");
@@ -4176,6 +4185,7 @@ public class WmsMaterialCoilServiceImpl implements IWmsMaterialCoilService {
      */
     @Override
     @Transactional
+    @CoilChangeLog(value = "发货撤回", changeType = CoilChangeType.UPDATE)
     public int withdrawExportCoil(Long coilId) {
         // 参数校验
         if (coilId == null) {
@@ -4205,6 +4215,7 @@ public class WmsMaterialCoilServiceImpl implements IWmsMaterialCoilService {
      * @return 是否更新成功
      */
     @Override
+    @CoilChangeLog(value = "批量更新发货状态", changeType = CoilChangeType.UPDATE, coilIdParam = "coilIds", isBatch = true)
     public Boolean batchUpdateDeliveryStatus(List<Long> coilIds, Integer status) {
         if (coilIds == null || coilIds.isEmpty()) {
             return false;
@@ -4616,6 +4627,7 @@ public class WmsMaterialCoilServiceImpl implements IWmsMaterialCoilService {
      */
     @Override
     @Transactional(rollbackFor = Exception.class)
+    @CoilChangeLog(value = "回滚", changeType = CoilChangeType.ROLLBACK, coilIdParam = "currentCoilId")
     public Map<String, Object> rollbackCoil(Long currentCoilId) {
         Map<String, Object> result = new HashMap<>();
         result.put("success", false);
@@ -5596,6 +5608,7 @@ public class WmsMaterialCoilServiceImpl implements IWmsMaterialCoilService {
      */
     @Override
     @Transactional(rollbackFor = Exception.class)
+    @CoilChangeLog(value = "创建子卷", changeType = CoilChangeType.SPLIT, coilIdParam = "parentCoilId")
     public WmsMaterialCoilVo createChildCoilInSpecialSplit(Long parentCoilId, WmsMaterialCoilBo childCoilBo, Long pendingActionId) {
         // 1. 查询母卷信息
         WmsMaterialCoil parentCoil = baseMapper.selectById(parentCoilId);
@@ -5921,6 +5934,7 @@ public class WmsMaterialCoilServiceImpl implements IWmsMaterialCoilService {
      */
     @Override
     @Transactional(rollbackFor = Exception.class)
+    @CoilChangeLog(value = "退货", changeType = CoilChangeType.PROCESS)
     public WmsMaterialCoilVo returnCoil(Long coilId) {
         if (coilId == null) {
             throw new RuntimeException("钢卷ID不能为空");
@@ -6200,6 +6214,7 @@ public class WmsMaterialCoilServiceImpl implements IWmsMaterialCoilService {
     }
 
     @Override
+    @CoilChangeLog(value = "修复材质异常", changeType = CoilChangeType.UPDATE)
     public Boolean fixMaterialMismatchCoils(Long coilId) {
         WmsMaterialCoil coil = baseMapper.selectById(coilId);
         if (coil == null) {
@@ -6616,6 +6631,7 @@ public class WmsMaterialCoilServiceImpl implements IWmsMaterialCoilService {
     }
 
     @Override
+    @CoilChangeLog(value = "解锁钢卷", changeType = CoilChangeType.UPDATE)
     public Boolean unlockCoil(Long coilId) {
         if (coilId == null) {
             throw new RuntimeException("钢卷ID不能为空");

klp-wms/src/main/java/com/klp/service/impl/WmsTransferOrderItemServiceImpl.java

@@ -9,6 +9,8 @@ import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
 import com.baomidou.mybatisplus.core.toolkit.Wrappers;
 import com.baomidou.mybatisplus.extension.toolkit.Db;
 import com.klp.common.utils.StringUtils;
+import com.klp.wms.annotation.CoilChangeLog;
+import com.klp.wms.enums.CoilChangeType;
 import com.klp.domain.*;
 import com.klp.domain.bo.WmsMaterialCoilBo;
 import com.klp.domain.vo.WmsMaterialCoilVo;
@@ -529,6 +531,7 @@ public class WmsTransferOrderItemServiceImpl implements IWmsTransferOrderItemSer
      */
     @Override
     @Transactional(rollbackFor = Exception.class)
+    @CoilChangeLog(value = "确认调拨", changeType = CoilChangeType.UPDATE, coilIdBoField = "coilId")
     public Boolean confirmTransfer(WmsTransferOrderItemBo bo) {
         Long transferId = bo.getTransferId();
         Long orderItemId = bo.getOrderItemId();

klp-wms/src/main/java/com/klp/wms/annotation/CoilChangeLog.java

@@ -0,0 +1,34 @@
+package com.klp.wms.annotation;
+
+import com.klp.wms.enums.CoilChangeType;
+
+import java.lang.annotation.*;
+
+/**
+ * 钢卷变更日志注解
+ * <p>
+ * 标注在修改 wms_material_coil 的方法上，AOP 切面自动记录变更前后的差异。
+ *
+ * @author klp
+ * @date 2026-07-11
+ */
+@Target({ElementType.METHOD})
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+public @interface CoilChangeLog {
+
+    /** 操作描述，如"钢卷加工"、"质量改判" */
+    String value();
+
+    /** 变更类型，默认 UPDATE */
+    CoilChangeType changeType() default CoilChangeType.UPDATE;
+
+    /** 方法参数中 coilId 的参数名（直接传 Long coilId 时使用） */
+    String coilIdParam() default "coilId";
+
+    /** BO 对象中 coilId 的字段名（传 BO 对象时使用，如 "coilId" 对应 bo.getCoilId()） */
+    String coilIdBoField() default "";
+
+    /** 是否批量操作（多个 coilId 时每个 ID 各写一条日志） */
+    boolean isBatch() default false;
+}

klp-wms/src/main/java/com/klp/wms/aspect/CoilChangeLogAspect.java

@@ -0,0 +1,341 @@
+package com.klp.wms.aspect;
+
+import cn.hutool.core.bean.BeanUtil;
+import cn.hutool.json.JSONUtil;
+import com.klp.domain.WmsMaterialCoil;
+import com.klp.domain.WmsCoilChangeLog;
+import com.klp.mapper.WmsCoilChangeLogMapper;
+import com.klp.mapper.WmsMaterialCoilMapper;
+import com.klp.wms.annotation.CoilChangeLog;
+import com.klp.wms.enums.CoilChangeType;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.aspectj.lang.ProceedingJoinPoint;
+import org.aspectj.lang.annotation.Around;
+import org.aspectj.lang.annotation.Aspect;
+import org.aspectj.lang.reflect.MethodSignature;
+import org.springframework.stereotype.Component;
+
+import java.lang.reflect.Method;
+import java.util.*;
+
+/**
+ * 钢卷变更日志切面
+ * <p>
+ * 拦截标注了 @CoilChangeLog 的方法，记录变更前后的差异。
+ *
+ * @author klp
+ * @date 2026-07-11
+ */
+@Slf4j
+@Aspect
+@Component
+@RequiredArgsConstructor
+public class CoilChangeLogAspect {
+
+    private final WmsMaterialCoilMapper coilMapper;
+    private final WmsCoilChangeLogMapper changeLogMapper;
+
+    /** 不需要参与差异比较的字段 */
+    private static final Set<String> EXCLUDE_DIFF_FIELDS = new HashSet<>(Arrays.asList(
+        "coilId", "createBy", "createTime", "updateBy", "updateTime",
+        "delFlag", "searchValue", "params"
+    ));
+
+    @Around("@annotation(coilChangeLog)")
+    public Object around(ProceedingJoinPoint joinPoint, CoilChangeLog coilChangeLog) throws Throwable {
+        CoilChangeType changeType = coilChangeLog.changeType();
+
+        // 1. 提取旧卷 ID 列表
+        List<Long> oldCoilIds = extractOldCoilIds(joinPoint, coilChangeLog);
+
+        // 2. 查询旧卷快照
+        Map<Long, Map<String, Object>> oldSnapshots = new LinkedHashMap<>();
+        for (Long coilId : oldCoilIds) {
+            if (coilId != null) {
+                WmsMaterialCoil coil = coilMapper.selectById(coilId);
+                if (coil != null) {
+                    oldSnapshots.put(coilId, beanToSnapshot(coil));
+                }
+            }
+        }
+
+        // 3. 执行目标方法
+        Object result = joinPoint.proceed();
+
+        // 4. 确定新卷 ID 列表
+        List<Long> newCoilIds = resolveNewCoilIds(result, changeType, oldCoilIds);
+
+        // 5. 查询新卷快照并写入日志（try-catch 包裹，不影响主流程）
+        try {
+            if (changeType == CoilChangeType.DELETE) {
+                // 删除：只有旧快照，无新快照
+                for (Long oldId : oldCoilIds) {
+                    Map<String, Object> oldSnapshot = oldSnapshots.get(oldId);
+                    insertLog(changeType, oldId, null, oldSnapshot, null, coilChangeLog.value());
+                }
+            } else if (changeType == CoilChangeType.INSERT) {
+                // 新建：无旧快照，只有新快照
+                for (Long newId : newCoilIds) {
+                    Map<String, Object> newSnapshot = queryCoilSnapshot(newId);
+                    insertLog(changeType, null, newId, null, newSnapshot, coilChangeLog.value());
+                }
+            } else if (changeType.isProcessing()) {
+                // 加工变换：旧卷 → 新卷，一一对应（或 多旧 → 一新）
+                for (int i = 0; i < oldCoilIds.size(); i++) {
+                    Long oldId = oldCoilIds.get(i);
+                    Long newId = (i < newCoilIds.size()) ? newCoilIds.get(i) : null;
+                    Map<String, Object> oldSnapshot = oldSnapshots.get(oldId);
+                    Map<String, Object> newSnapshot = (newId != null) ? queryCoilSnapshot(newId) : null;
+                    insertLog(changeType, oldId, newId, oldSnapshot, newSnapshot, coilChangeLog.value());
+                }
+            } else {
+                // 原地修改：相同 ID
+                for (Long coilId : oldCoilIds) {
+                    Map<String, Object> oldSnapshot = oldSnapshots.get(coilId);
+                    Map<String, Object> newSnapshot = queryCoilSnapshot(coilId);
+                    insertLog(changeType, coilId, coilId, oldSnapshot, newSnapshot, coilChangeLog.value());
+                }
+            }
+        } catch (Exception e) {
+            log.warn("记录钢卷变更日志失败: {}", e.getMessage());
+        }
+
+        return result;
+    }
+
+    // ==================== 参数提取 ====================
+
+    /**
+     * 从方法参数中提取旧卷 ID 列表
+     */
+    private List<Long> extractOldCoilIds(ProceedingJoinPoint joinPoint, CoilChangeLog annotation) {
+        Object[] args = joinPoint.getArgs();
+        MethodSignature signature = (MethodSignature) joinPoint.getSignature();
+        String[] paramNames = signature.getParameterNames();
+
+        List<Long> ids = new ArrayList<>();
+
+        // 优先从 BO 字段提取
+        String boField = annotation.coilIdBoField();
+        if (boField != null && !boField.isEmpty()) {
+            for (Object arg : args) {
+                if (arg != null && !isBasicType(arg)) {
+                    Long id = getFieldValue(arg, boField);
+                    if (id != null) {
+                        // bo.getCoilId() 非空 → 分卷场景：外层就是旧母卷
+                        ids.add(id);
+                    } else {
+                        // bo.getCoilId() 为空 → 合卷场景：newCoils 里的才是旧卷
+                        List<?> newCoils = getFieldValue(arg, "newCoils", List.class);
+                        if (newCoils != null) {
+                            for (Object item : newCoils) {
+                                Long itemId = getFieldValue(item, boField);
+                                if (itemId != null) {
+                                    ids.add(itemId);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            if (!ids.isEmpty()) {
+                return ids;
+            }
+        }
+
+        // 按参数名提取
+        String paramName = annotation.coilIdParam();
+        for (int i = 0; i < paramNames.length; i++) {
+            if (paramName.equals(paramNames[i])) {
+                Object val = args[i];
+                if (val instanceof Long) {
+                    ids.add((Long) val);
+                } else if (val instanceof Collection) {
+                    for (Object item : (Collection<?>) val) {
+                        if (item instanceof Long) {
+                            ids.add((Long) item);
+                        }
+                    }
+                }
+            }
+        }
+
+        return ids;
+    }
+
+    // ==================== 新卷 ID 解析 ====================
+
+    /**
+     * 从方法返回值中解析新卷 ID
+     */
+    private List<Long> resolveNewCoilIds(Object result, CoilChangeType changeType, List<Long> oldCoilIds) {
+        List<Long> newIds = new ArrayList<>();
+
+        if (result == null) {
+            return newIds;
+        }
+
+        if (result instanceof Long) {
+            newIds.add((Long) result);
+        } else if (result instanceof Integer) {
+            newIds.add(((Integer) result).longValue());
+        } else if (result instanceof String) {
+            // 可能是单个 ID 或逗号分隔的 ID 列表
+            String str = (String) result;
+            if (str.contains(",")) {
+                for (String part : str.split(",")) {
+                    try {
+                        newIds.add(Long.parseLong(part.trim()));
+                    } catch (NumberFormatException ignored) {
+                    }
+                }
+            } else {
+                try {
+                    newIds.add(Long.parseLong(str.trim()));
+                } catch (NumberFormatException ignored) {
+                }
+            }
+        } else if (result instanceof Map) {
+            // 尝试从 Map 中提取 coilId 或 newCoilId
+            Map<?, ?> map = (Map<?, ?>) result;
+            Object id = map.get("coilId");
+            if (id == null) {
+                id = map.get("newCoilId");
+            }
+            if (id instanceof Long) {
+                newIds.add((Long) id);
+            }
+        } else {
+            // 尝试反射获取 coilId
+            Long id = getFieldValue(result, "coilId");
+            if (id != null) {
+                newIds.add(id);
+            }
+        }
+
+        // 如果无法解析新 ID，对于非加工类型，使用旧 ID
+        if (newIds.isEmpty() && !changeType.isProcessing() && changeType != CoilChangeType.DELETE) {
+            return oldCoilIds;
+        }
+
+        return newIds;
+    }
+
+    // ==================== 快照与差异 ====================
+
+    /**
+     * 将钢卷实体转为快照 Map（排除无关字段）
+     */
+    private Map<String, Object> beanToSnapshot(WmsMaterialCoil coil) {
+        Map<String, Object> map = BeanUtil.beanToMap(coil, false, true);
+        // 转换为字符串值以便 JSON 序列化
+        Map<String, Object> snapshot = new LinkedHashMap<>();
+        for (Map.Entry<String, Object> entry : map.entrySet()) {
+            if (!EXCLUDE_DIFF_FIELDS.contains(entry.getKey())) {
+                snapshot.put(entry.getKey(), entry.getValue());
+            }
+        }
+        return snapshot;
+    }
+
+    /**
+     * 按 ID 查询钢卷并转为快照
+     */
+    private Map<String, Object> queryCoilSnapshot(Long coilId) {
+        if (coilId == null) {
+            return Collections.emptyMap();
+        }
+        WmsMaterialCoil coil = coilMapper.selectById(coilId);
+        return coil != null ? beanToSnapshot(coil) : Collections.emptyMap();
+    }
+
+    /**
+     * 对比新旧快照，返回变更字段差异 Map
+     */
+    private Map<String, Map<String, Object>> computeDiff(Map<String, Object> oldSnapshot,
+                                                          Map<String, Object> newSnapshot) {
+        Map<String, Map<String, Object>> diff = new LinkedHashMap<>();
+
+        // 检查旧值变更或新增
+        Set<String> allFields = new LinkedHashSet<>();
+        if (oldSnapshot != null) allFields.addAll(oldSnapshot.keySet());
+        if (newSnapshot != null) allFields.addAll(newSnapshot.keySet());
+
+        for (String field : allFields) {
+            if (EXCLUDE_DIFF_FIELDS.contains(field)) {
+                continue;
+            }
+            Object oldVal = (oldSnapshot != null) ? oldSnapshot.get(field) : null;
+            Object newVal = (newSnapshot != null) ? newSnapshot.get(field) : null;
+
+            if (!Objects.equals(oldVal, newVal)) {
+                Map<String, Object> change = new LinkedHashMap<>();
+                change.put("old", oldVal);
+                change.put("new", newVal);
+                diff.put(field, change);
+            }
+        }
+
+        return diff;
+    }
+
+    // ==================== 日志写入 ====================
+
+    private void insertLog(CoilChangeType changeType, Long oldCoilId, Long newCoilId,
+                           Map<String, Object> oldSnapshot, Map<String, Object> newSnapshot,
+                           String operationDesc) {
+        Map<String, Map<String, Object>> diff = computeDiff(oldSnapshot, newSnapshot);
+
+        WmsCoilChangeLog logRecord = new WmsCoilChangeLog();
+        logRecord.setChangeType(changeType.name());
+        logRecord.setOldCoilId(oldCoilId);
+        logRecord.setNewCoilId(newCoilId);
+        logRecord.setOldCoilNo(snapshotValue(oldSnapshot, "currentCoilNo"));
+        logRecord.setNewCoilNo(snapshotValue(newSnapshot, "currentCoilNo"));
+        logRecord.setChangedFields(diff.isEmpty() ? null : JSONUtil.toJsonStr(diff));
+        logRecord.setOperationDesc(operationDesc);
+
+        changeLogMapper.insert(logRecord);
+    }
+
+    private String snapshotValue(Map<String, Object> snapshot, String key) {
+        if (snapshot == null) return null;
+        Object val = snapshot.get(key);
+        return val != null ? String.valueOf(val) : null;
+    }
+
+    // ==================== 反射工具 ====================
+
+    private Long getFieldValue(Object obj, String fieldName) {
+        try {
+            String getter = "get" + Character.toUpperCase(fieldName.charAt(0)) + fieldName.substring(1);
+            Method method = obj.getClass().getMethod(getter);
+            Object val = method.invoke(obj);
+            if (val instanceof Long) {
+                return (Long) val;
+            }
+        } catch (Exception ignored) {
+        }
+        return null;
+    }
+
+    @SuppressWarnings("unchecked")
+    private <T> T getFieldValue(Object obj, String fieldName, Class<T> type) {
+        try {
+            String getter = "get" + Character.toUpperCase(fieldName.charAt(0)) + fieldName.substring(1);
+            Method method = obj.getClass().getMethod(getter);
+            Object val = method.invoke(obj);
+            if (type.isInstance(val)) {
+                return (T) val;
+            }
+        } catch (Exception ignored) {
+        }
+        return null;
+    }
+
+    private boolean isBasicType(Object obj) {
+        return obj instanceof String || obj instanceof Number
+            || obj instanceof Boolean || obj instanceof Date;
+    }
+}

klp-wms/src/main/java/com/klp/wms/enums/CoilChangeType.java

@@ -0,0 +1,44 @@
+package com.klp.wms.enums;
+
+/**
+ * 钢卷变更类型
+ *
+ * @author klp
+ * @date 2026-07-11
+ */
+public enum CoilChangeType {
+
+    /** 普通修改（原地修改字段） */
+    UPDATE,
+
+    /** 新建钢卷 */
+    INSERT,
+
+    /** 加工（旧卷变历史，生成新卷） */
+    PROCESS,
+
+    /** 分卷 */
+    SPLIT,
+
+    /** 合卷 */
+    MERGE,
+
+    /** 删除 */
+    DELETE,
+
+    /** 回滚 */
+    ROLLBACK,
+
+    /** 发货 */
+    EXPORT,
+
+    /** 质量改判 */
+    QUALITY_CHANGE;
+
+    /**
+     * 是否为加工变换类型（旧卷 → 新卷）
+     */
+    public boolean isProcessing() {
+        return this == PROCESS || this == SPLIT || this == MERGE || this == ROLLBACK;
+    }
+}