refactor: 单据审核改为审批配置状态机（新增:audit接口/审核人字段/DB变更脚本）

liu

3 天以前 7d2ee3cef2e0d68ba6400bc5957640d2771bbf4c

 yudao-module-crm/src/main/java/cn/iocoder/yudao/module/crm/service/contract/CrmContractServiceImpl.java

@@ -4,18 +4,19 @@
import cn.hutool.core.collection.ListUtil;
import cn.hutool.core.lang.Assert;
import cn.hutool.core.util.ObjUtil;
import cn.hutool.core.util.StrUtil;
import cn.iocoder.yudao.framework.common.pojo.PageResult;
import cn.iocoder.yudao.framework.common.util.number.MoneyUtils;
import cn.iocoder.yudao.framework.common.util.object.BeanUtils;
import cn.iocoder.yudao.framework.common.util.object.ObjectUtils;
import cn.iocoder.yudao.module.bpm.api.task.BpmProcessInstanceApi;
import cn.iocoder.yudao.module.bpm.api.task.dto.BpmProcessInstanceCreateReqDTO;
import cn.iocoder.yudao.module.crm.controller.admin.contract.vo.contract.CrmContractPageReqVO;
import cn.iocoder.yudao.module.crm.controller.admin.contract.vo.contract.CrmContractSaveReqVO;
import cn.iocoder.yudao.module.crm.controller.admin.contract.vo.contract.CrmContractTransferReqVO;
import cn.iocoder.yudao.module.crm.dal.dataobject.contract.CrmContractConfigDO;
import cn.iocoder.yudao.module.crm.dal.dataobject.contract.CrmContractDO;
import cn.iocoder.yudao.module.crm.dal.dataobject.contract.CrmContractProductDO;
import cn.iocoder.yudao.module.crm.dal.dataobject.quotation.CrmSaleQuotationDO;
import cn.iocoder.yudao.module.crm.dal.dataobject.quotation.CrmSaleQuotationProductDO;
import cn.iocoder.yudao.module.crm.dal.mysql.contract.CrmContractMapper;
import cn.iocoder.yudao.module.crm.dal.mysql.contract.CrmContractProductMapper;
import cn.iocoder.yudao.module.crm.dal.redis.no.CrmNoRedisDAO;
@@ -25,18 +26,21 @@
import cn.iocoder.yudao.module.crm.framework.permission.core.annotations.CrmPermission;
import cn.iocoder.yudao.module.crm.service.business.CrmBusinessService;
import cn.iocoder.yudao.module.crm.service.contact.CrmContactService;
import cn.iocoder.yudao.module.crm.api.customer.CrmCustomerApi;
import cn.iocoder.yudao.module.crm.service.customer.CrmCustomerService;
import cn.iocoder.yudao.module.crm.service.permission.CrmPermissionService;
import cn.iocoder.yudao.module.crm.service.permission.bo.CrmPermissionCreateReqBO;
import cn.iocoder.yudao.module.crm.service.permission.bo.CrmPermissionTransferReqBO;
import cn.iocoder.yudao.module.crm.service.product.CrmProductService;
import cn.iocoder.yudao.module.crm.service.quotation.CrmSaleQuotationService;
import cn.iocoder.yudao.module.crm.service.receivable.CrmReceivableService;
import cn.iocoder.yudao.module.erp.api.sale.ErpSaleOrderApi;
import cn.iocoder.yudao.module.erp.api.sale.dto.ErpSaleOrderCreateReqDTO;
import cn.iocoder.yudao.module.erp.api.sale.dto.ErpSaleOrderRespDTO;
import cn.iocoder.yudao.module.mdm.api.item.MdmItemApi;
import cn.iocoder.yudao.module.mdm.api.item.dto.MdmItemRespDTO;
import cn.iocoder.yudao.module.system.api.approval.ApprovalConfigApi;
import cn.iocoder.yudao.module.system.api.user.AdminUserApi;
import cn.iocoder.yudao.module.system.api.user.dto.AdminUserRespDTO;
import com.mzt.logapi.context.LogRecordContext;
import com.mzt.logapi.service.impl.DiffParseFunction;
import com.mzt.logapi.starter.annotation.LogRecord;
@@ -49,15 +53,19 @@

import java.math.BigDecimal;
import java.time.LocalDateTime;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;

import static cn.iocoder.yudao.framework.common.exception.util.ServiceExceptionUtil.exception;
import static cn.iocoder.yudao.framework.common.util.collection.CollectionUtils.*;
import static cn.iocoder.yudao.module.crm.enums.ErrorCodeConstants.*;
import static cn.iocoder.yudao.module.crm.enums.LogRecordConstants.*;
import static cn.iocoder.yudao.module.crm.util.CrmAuditStatusUtils.convertBpmResultToAuditStatus;
import static cn.iocoder.yudao.framework.security.core.util.SecurityFrameworkUtils.getLoginUserId;

/**
 * CRM 合同 Service 实现类
@@ -70,9 +78,11 @@
public class CrmContractServiceImpl implements CrmContractService {

    /**
     * BPM 合同审批流程标识
     * CRM 合同审批的业务类型编码
     *
     * 与 system_approval_config.biz_type 对应，审批人在「系统管理 - 审批配置」中维护。
     */
    public static final String BPM_PROCESS_DEFINITION_KEY = "crm-contract-audit";
    private static final String CONTRACT_APPROVE_BIZ_TYPE = "contract_approve";

    @Resource
    private CrmContractMapper contractMapper;
@@ -85,9 +95,9 @@
    @Resource
    private CrmPermissionService crmPermissionService;
    @Resource
    private CrmProductService productService;
    @Resource
    private CrmCustomerService customerService;
    @Resource
    private CrmCustomerApi customerApi;
    @Resource
    private CrmBusinessService businessService;
    @Resource
@@ -100,11 +110,14 @@
    @Resource
    private AdminUserApi adminUserApi;
    @Resource
    private BpmProcessInstanceApi bpmProcessInstanceApi;
    private ApprovalConfigApi approvalConfigApi;
    @Resource
    private ErpSaleOrderApi saleOrderApi;
    @Resource
    private MdmItemApi mdmItemApi;
    @Resource
    @Lazy // 延迟加载，避免循环依赖（quotation 内部引用了 contractService）
    private CrmSaleQuotationService crmSaleQuotationService;

    @Override
    @Transactional(rollbackFor = Exception.class)
@@ -122,7 +135,9 @@
        }

        // 2.1 插入合同
        CrmContractDO contract = BeanUtils.toBean(createReqVO, CrmContractDO.class).setNo(no);
        CrmContractDO contract = BeanUtils.toBean(createReqVO, CrmContractDO.class)
                .setNo(no)
                .setAuditStatus(CrmAuditStatusEnum.DRAFT.getStatus()); // 默认为未提交状态
        calculateTotalPrice(contract, contractProducts);
        contractMapper.insert(contract);
        // 2.2 插入合同关联商品
@@ -219,7 +234,7 @@

    private List<CrmContractProductDO> validateContractProducts(List<CrmContractSaveReqVO.Product> list) {
        // 1. 校验物料存在且启用
        List<Long> itemIds = convertSet(list, CrmContractSaveReqVO.Product::getItemId);
        Set<Long> itemIds = convertSet(list, CrmContractSaveReqVO.Product::getItemId);
        Map<Long, MdmItemRespDTO> itemMap = mdmItemApi.getItemMap(itemIds);
        // 2. 转化为 CrmContractProductDO 列表
        return convertList(list, o -> BeanUtils.toBean(o, CrmContractProductDO.class, item -> {
@@ -254,6 +269,11 @@

        // 2.1 删除合同
        contractMapper.deleteById(id);
        // 2.2 删除合同时，解除关联的报价单引用
        CrmSaleQuotationDO quotation = crmSaleQuotationService.getByContractId(id);
        if (quotation != null) {
            crmSaleQuotationService.clearContractReference(quotation.getId());
        }
        // 2.2 删除数据权限
        crmPermissionService.deletePermission(CrmBizTypeEnum.CRM_CONTRACT.getType(), id);

@@ -267,6 +287,20 @@
            throw exception(CONTRACT_NOT_EXISTS);
        }
        return contract;
    }

    /**
     * 获取用户昵称
     *
     * @param userId 用户编号
     * @return 昵称，用户不存在时返回 null
     */
    private String getUserNickname(Long userId) {
        if (userId == null) {
            return null;
        }
        AdminUserRespDTO user = adminUserApi.getUser(userId);
        return user == null ? null : user.getNickname();
    }

    @Override
@@ -307,39 +341,53 @@
    @Transactional(rollbackFor = Exception.class)
    @LogRecord(type = CRM_CONTRACT_TYPE, subType = CRM_CONTRACT_SUBMIT_SUB_TYPE, bizNo = "{{#id}}",
            success = CRM_CONTRACT_SUBMIT_SUCCESS)
    public void submitContract(Long id, Long userId) {
        // 1. 校验合同是否在审批
    public void submitContract(Long id) {
        // 1. 校验存在 + 可提交状态（未提交 / 审核不通过）
        CrmContractDO contract = validateContractExists(id);
        if (ObjUtil.notEqual(contract.getAuditStatus(), CrmAuditStatusEnum.DRAFT.getStatus())) {
            throw exception(CONTRACT_SUBMIT_FAIL_NOT_DRAFT);
        if (ObjUtil.notEqual(contract.getAuditStatus(), CrmAuditStatusEnum.DRAFT.getStatus())
                && ObjUtil.notEqual(contract.getAuditStatus(), CrmAuditStatusEnum.REJECT.getStatus())) {
            throw exception(CONTRACT_SUBMIT_FAIL_NOT_EDITABLE);
        }

        // 2. 创建合同审批流程实例
        String processInstanceId = bpmProcessInstanceApi.createProcessInstance(userId, new BpmProcessInstanceCreateReqDTO()
                .setProcessDefinitionKey(BPM_PROCESS_DEFINITION_KEY).setBusinessKey(String.valueOf(id)));
        // 2. 校验审批配置已启用且配置了有效审批人（未配置时抛出带明确提示的业务异常）
        approvalConfigApi.validateApprovalEnabledAndGetApprovers(CONTRACT_APPROVE_BIZ_TYPE);

        // 3. 更新合同工作流编号
        contractMapper.updateById(new CrmContractDO().setId(id).setProcessInstanceId(processInstanceId)
                .setAuditStatus(CrmAuditStatusEnum.PROCESS.getStatus()));
        // 3. 状态置为审批中，并清空上一轮审核结果，避免残留「审核不通过」的原因
        contractMapper.submitAndResetAuditInfo(id, CrmAuditStatusEnum.PROCESS.getStatus());

        // 3. 记录日志
        // 4. 记录日志
        LogRecordContext.putVariable("contractName", contract.getName());
    }

    @Override
    public void updateContractAuditStatus(Long id, Integer bpmResult) {
        // 1.1 校验合同是否存在
        CrmContractDO contract = validateContractExists(id);
        // 1.2 只有审批中，可以更新审批结果
        if (ObjUtil.notEqual(contract.getAuditStatus(), CrmAuditStatusEnum.PROCESS.getStatus())) {
            log.error("[updateContractAuditStatus][contract({}) 不处于审批中，无法更新审批结果({})]",
                    contract.getId(), bpmResult);
            throw exception(CONTRACT_UPDATE_AUDIT_STATUS_FAIL_NOT_PROCESS);
        }
    public Set<Long> getContractApproverUserIds() {
        return approvalConfigApi.getApproverUserIds(CONTRACT_APPROVE_BIZ_TYPE);
    }

        // 2. 更新合同审批结果
        Integer auditStatus = convertBpmResultToAuditStatus(bpmResult);
        contractMapper.updateById(new CrmContractDO().setId(id).setAuditStatus(auditStatus));
    @Override
    @Transactional(rollbackFor = Exception.class)
    public void auditContract(Long id, Boolean pass, String reviewRemark) {
        // 1. 校验存在
        CrmContractDO contract = validateContractExists(id);
        // 2. 校验处于审批中状态
        if (ObjUtil.notEqual(contract.getAuditStatus(), CrmAuditStatusEnum.PROCESS.getStatus())) {
            throw exception(CONTRACT_AUDIT_FAIL_NOT_PROCESS);
        }
        // 3. 校验当前登录用户是该业务类型的审批人（或签：任一人均可审核）
        Long userId = getLoginUserId();
        approvalConfigApi.validateApprover(CONTRACT_APPROVE_BIZ_TYPE, userId);
        // 4. 审核不通过：必须填写原因，状态置为审核不通过，退回提交人修改后可重新提交
        if (!Boolean.TRUE.equals(pass)) {
            if (StrUtil.isBlank(reviewRemark)) {
                throw exception(CONTRACT_AUDIT_REJECT_REASON_REQUIRED);
            }
            contractMapper.auditContract(id, CrmAuditStatusEnum.REJECT.getStatus(),
                    userId, getUserNickname(userId), reviewRemark);
            return;
        }
        // 5. 审核通过：记录审核人与审核意见，状态置为审核通过
        contractMapper.auditContract(id, CrmAuditStatusEnum.APPROVE.getStatus(),
                userId, getUserNickname(userId), reviewRemark);
    }

    // ======================= 查询相关 =======================
@@ -376,8 +424,10 @@
                return PageResult.empty();
            }
        }
        // 2. 查询分页
        return contractMapper.selectPage(pageReqVO, userId, config);
        // 2. 获取用户有权限的客户 ID 列表
        List<Long> permittedCustomerIds = customerApi.getPermittedCustomerIds();
        // 3. 查询分页
        return contractMapper.selectPage(pageReqVO, userId, config, permittedCustomerIds);
    }

    @Override
@@ -461,14 +511,15 @@
        createReqDTO.setContractNo(contract.getNo());
        createReqDTO.setSaleUserId(contract.getOwnerUserId());
        createReqDTO.setOrderTime(LocalDateTime.now().toString());
        createReqDTO.setDiscountPercent(contract.getDiscountPercent());
        createReqDTO.setDiscountPercent(contract.getDiscountPercent() != null ? contract.getDiscountPercent() : BigDecimal.ZERO);
        createReqDTO.setDepositPrice(contract.getDepositPrice() != null ? contract.getDepositPrice() : BigDecimal.ZERO);
        createReqDTO.setRemark("由合同【" + contract.getNo() + "】自动生成");

        // 5. 构建订单项
        List<ErpSaleOrderCreateReqDTO.Item> items = contractProducts.stream()
                .map(cp -> {
                    ErpSaleOrderCreateReqDTO.Item item = new ErpSaleOrderCreateReqDTO.Item();
                    item.setItemId(cp.getItemId());
                    item.setProductId(cp.getItemId());
                    item.setProductPrice(cp.getContractPrice());
                    item.setCount(cp.getCount());
                    return item;
@@ -493,4 +544,21 @@
        return orderId;
    }

    @Override
    public void updateContractStatus(Long id, Integer status) {
        contractMapper.updateById(new CrmContractDO()
                .setId(id)
                .setAuditStatus(status));
    }

    @Override
    public void updateContractStatusByOrderId(Long orderId, Integer status) {
        CrmContractDO contract = contractMapper.selectByOrderId(orderId);
        if (contract != null) {
            contractMapper.updateById(new CrmContractDO()
                    .setId(contract.getId())
                    .setAuditStatus(status));
        }
    }

}