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

liu

3 天以前 7d2ee3cef2e0d68ba6400bc5957640d2771bbf4c

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

@@ -4,21 +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.bpm.dal.dataobject.definition.BpmProcessDefinitionInfoDO;
import cn.iocoder.yudao.module.bpm.service.definition.BpmCategoryService;
import cn.iocoder.yudao.module.bpm.service.definition.BpmProcessDefinitionService;
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;
@@ -28,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;
@@ -60,13 +61,11 @@
import java.util.Map;
import java.util.Set;

import org.flowable.engine.repository.ProcessDefinition;

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 实现类
@@ -79,14 +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";

    /**
     * BPM 合同审批分类编码
     */
    private static final String CONTRACT_APPROVE_CATEGORY_CODE = "contract_approve";
    private static final String CONTRACT_APPROVE_BIZ_TYPE = "contract_approve";

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

    @Override
    @Transactional(rollbackFor = Exception.class)
@@ -274,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);

@@ -287,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
@@ -327,114 +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, String processDefinitionKey, 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. 校验分类和流程定义是否存在
        validateContractApproveCategoryAndProcessDefinition();
        // 2. 校验审批配置已启用且配置了有效审批人（未配置时抛出带明确提示的业务异常）
        approvalConfigApi.validateApprovalEnabledAndGetApprovers(CONTRACT_APPROVE_BIZ_TYPE);

        // 3. 校验传入的流程定义 Key 是否属于该分类且处于激活状态
        ProcessDefinition processDefinition = bpmProcessDefinitionService.getActiveProcessDefinition(processDefinitionKey);
        if (processDefinition == null) {
            throw exception(CONTRACT_BPM_PROCESS_DEFINITION_NOT_EXISTS);
        }
        // 3. 状态置为审批中，并清空上一轮审核结果，避免残留「审核不通过」的原因
        contractMapper.submitAndResetAuditInfo(id, CrmAuditStatusEnum.PROCESS.getStatus());

        // 4. 创建合同审批流程实例
        String processInstanceId = bpmProcessInstanceApi.createProcessInstance(userId, new BpmProcessInstanceCreateReqDTO()
                .setProcessDefinitionKey(processDefinitionKey).setBusinessKey(String.valueOf(id)));

        // 5. 更新合同工作流编号
        contractMapper.updateById(new CrmContractDO().setId(id).setProcessInstanceId(processInstanceId)
                .setAuditStatus(CrmAuditStatusEnum.PROCESS.getStatus()));

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

    /**
     * 校验 BPM 合同审批分类和流程定义是否存在
     */
    private void validateContractApproveCategoryAndProcessDefinition() {
        // 1. 校验分类是否存在
        List<String> codes = Collections.singletonList(CONTRACT_APPROVE_CATEGORY_CODE);
        Map<String, ?> categoryMap = bpmCategoryService.getCategoryMap(codes);
        if (!categoryMap.containsKey(CONTRACT_APPROVE_CATEGORY_CODE)) {
            throw exception(CONTRACT_BPM_PROCESS_DEFINITION_NOT_EXISTS);
        }

        // 2. 校验分类下是否有可用的流程定义
        List<BpmProcessDefinitionInfoDO> definitionInfoList = bpmProcessDefinitionService
                .getProcessDefinitionInfoListByCategory(CONTRACT_APPROVE_CATEGORY_CODE);
        if (CollUtil.isEmpty(definitionInfoList)) {
            throw exception(CONTRACT_BPM_PROCESS_DEFINITION_NOT_EXISTS);
        }

        // 3. 校验是否有激活状态的流程定义
        Set<String> processDefinitionIds = convertSet(definitionInfoList, BpmProcessDefinitionInfoDO::getProcessDefinitionId);
        List<ProcessDefinition> processDefinitions = bpmProcessDefinitionService.getProcessDefinitionList(processDefinitionIds);
        boolean hasActiveDefinition = processDefinitions.stream()
                .anyMatch(pd -> !pd.isSuspended());
        if (!hasActiveDefinition) {
            throw exception(CONTRACT_BPM_PROCESS_DEFINITION_NOT_EXISTS);
        }
    @Override
    public Set<Long> getContractApproverUserIds() {
        return approvalConfigApi.getApproverUserIds(CONTRACT_APPROVE_BIZ_TYPE);
    }

    @Override
    public List<Map<String, Object>> getContractApproveProcessDefinitionList() {
        // 1. 校验分类和流程定义是否存在
        validateContractApproveCategoryAndProcessDefinition();

        // 2. 获取分类下的流程定义信息
        List<BpmProcessDefinitionInfoDO> definitionInfoList = bpmProcessDefinitionService
                .getProcessDefinitionInfoListByCategory(CONTRACT_APPROVE_CATEGORY_CODE);

        // 3. 获取流程定义详情
        Set<String> processDefinitionIds = convertSet(definitionInfoList, BpmProcessDefinitionInfoDO::getProcessDefinitionId);
        List<ProcessDefinition> processDefinitions = bpmProcessDefinitionService.getProcessDefinitionList(processDefinitionIds);

        // 4. 过滤：只保留激活状态，且相同 key 只保留最新版本
        Map<String, ProcessDefinition> latestVersionMap = new HashMap<>();
        for (ProcessDefinition pd : processDefinitions) {
            if (pd.isSuspended()) {
                continue;
            }
            ProcessDefinition existing = latestVersionMap.get(pd.getKey());
            if (existing == null || pd.getVersion() > existing.getVersion()) {
                latestVersionMap.put(pd.getKey(), pd);
            }
        }

        // 5. 返回流程定义列表
        List<Map<String, Object>> result = new ArrayList<>();
        for (ProcessDefinition pd : latestVersionMap.values()) {
            Map<String, Object> item = new HashMap<>();
            item.put("id", pd.getId());
            item.put("key", pd.getKey());
            item.put("name", pd.getName());
            item.put("version", pd.getVersion());
            result.add(item);
        }
        return result;
    }

    @Override
    public void updateContractAuditStatus(Long id, Integer bpmResult) {
        // 1.1 校验合同是否存在
    @Transactional(rollbackFor = Exception.class)
    public void auditContract(Long id, Boolean pass, String reviewRemark) {
        // 1. 校验存在
        CrmContractDO contract = validateContractExists(id);
        // 1.2 只有审批中，可以更新审批结果
        // 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);
            throw exception(CONTRACT_AUDIT_FAIL_NOT_PROCESS);
        }

        // 2. 更新合同审批结果
        Integer auditStatus = convertBpmResultToAuditStatus(bpmResult);
        contractMapper.updateById(new CrmContractDO().setId(id).setAuditStatus(auditStatus));
        // 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);
    }

    // ======================= 查询相关 =======================
@@ -471,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