shanxia2.0/docs/crm-migration/reference/java/contract/service/ICrmContractService.java

package org.dromara.crm.service;

import org.dromara.common.mybatis.core.page.PageQuery;
import org.dromara.common.mybatis.core.page.TableDataInfo;
import org.dromara.crm.domain.bo.CrmContractBo;
import org.dromara.crm.domain.vo.CrmContractVo;

import java.time.LocalDate;
import java.util.Collection;
import java.util.List;
import java.util.Map;

/**
 * 合同管理Service接口
 *
 * @author AI Assistant
 * @date 2025-10-04
 */
public interface ICrmContractService {

    /**
     * 查询合同列表(分页)
     */
    TableDataInfo<CrmContractVo> queryPageList(CrmContractBo bo, PageQuery pageQuery);

    /**
     * 查询合同列表
     */
    List<CrmContractVo> queryList(CrmContractBo bo);

    /**
     * 查询合同详情
     */
    CrmContractVo queryById(Long id);

    /**
     * 新增合同
     */
    Boolean insertByBo(CrmContractBo bo);

    /**
     * 修改合同
     */
    Boolean updateByBo(CrmContractBo bo);

    /**
     * 校验并批量删除合同
     */
    Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);

    /**
     * 提交审批
     */
    Boolean submitApproval(Long id, List<Long> approverIds, String remark);

    /**
     * 批量提交审批
     *
     * @param ids        合同ID列表
     * @param approverIds 审批人ID列表
     * @param remark     备注
     * @return 成功数量
     */
    int batchSubmitApproval(List<Long> ids, List<Long> approverIds, String remark);

    /**
     * 保存合同模板内容
     *
     * @param id              合同ID
     * @param templateContent 模板内容(富文本HTML)
     * @param settlementClauseDrafts 第五条结算方式草稿（JSON）
     * @return 是否成功
     */
    Boolean saveTemplate(Long id, String templateContent, String settlementClauseDrafts);

    /**
     * 获取合同模板内容
     *
     * @param id 合同ID
     * @return 模板内容(富文本HTML)
     */
    String getTemplate(Long id);

    /**
     * 撤回审批
     */
    Boolean withdrawApproval(Long id, String remark);

    /**
     * 开始执行合同
     */
    Boolean startExecute(Long id, String remark);

    /**
     * 完成合同
     */
    Boolean finishContract(Long id, String remark);

    /**
     * 作废合同
     */
    Boolean invalidContract(Long id, String invalidReason, String remark);

    /**
     * 上传合同文件
     */
    Boolean uploadFile(Long id, String fileUrl);

    /**
     * 上传合同扫描件（支持多个附件）
     *
     * @param id     合同ID
     * @param ossIds 附件ossId列表（逗号分隔）- 兼容旧格式
     * @return 是否成功
     */
    Boolean uploadAttachments(Long id, String ossIds);

    /**
     * 上传合同扫描件（支持多个附件，带分类）
     *
     * @param id         合同ID
     * @param attachments 附件列表（包含ossId和category）
     * @return 是否成功
     */
    Boolean uploadAttachmentsWithCategory(Long id, java.util.List<java.util.Map<String, Object>> attachments);

    /**
     * 合同统计概览
     */
    Map<String, Object> statisticsOverview(Long ownerUserId, String beginTime, String endTime);

    /**
     * 合同状态分布
     */
    List<Map<String, Object>> statisticsByStatus();

    /**
     * 合同类型分布
     */
    List<Map<String, Object>> statisticsByType();

    /**
     * 合同趋势分析
     */
    List<Map<String, Object>> statisticsTrend(String type, String beginTime, String endTime);

    /**
     * 即将到期合同
     */
    List<CrmContractVo> queryExpiring(Integer days);

    /**
     * 更新合同回款金额
     *
     * @param contractId 合同ID
     */
    Boolean updateReceivedAmount(Long contractId);

    /**
     * 合同续签
     *
     * @param parentContractId 原合同ID
     * @param bo               新合同信息
     * @return 新合同ID
     */
    Long renewContract(Long parentContractId, CrmContractBo bo);

    /**
     * 从商机创建合同
     *
     * @param opportunityId 商机ID
     * @param bo            合同信息
     * @return 是否成功
     */
    Boolean createFromOpportunity(Long opportunityId, CrmContractBo bo);

    /**
     * 从报价单创建合同
     *
     * @param quoteId 报价单ID
     * @param bo      合同信息
     * @return 是否成功
     */
    Boolean createFromQuote(Long quoteId, CrmContractBo bo);

    /**
     * 从模板创建合同
     *
     * @param templateId 模板ID
     * @param bo         合同信息
     * @return 是否成功
     */
    Boolean createFromTemplate(Long templateId, CrmContractBo bo);

    /**
     * 合同签订标记
     *
     * @param id             合同ID
     * @param actualSignDate 实际签订日期
     * @param contractFile   合同文件
     * @param remark         备注
     * @return 是否成功
     */
    Boolean signContract(Long id, java.time.LocalDate actualSignDate, String contractFile, String remark);

    /**
     * 批量分配负责人
     *
     * @param ids         合同ID列表
     * @param ownerUserId 新负责人ID
     * @param remark      备注
     * @return 是否成功
     */
    Boolean batchAssignOwner(Collection<Long> ids, Long ownerUserId, String remark);

    /**
     * 下载合同PDF
     *
     * @param id 合同ID
     * @return 合同文件路径
     */
    String downloadContractPdf(Long id);

    /**
     * 更新合同开票金额
     *
     * @param contractId 合同ID
     * @return 是否成功
     */
    Boolean updateInvoiceAmount(Long contractId);

    /**
     * 生成合同编号
     *
     * @param supplierId 供方主体ID，如果为null则使用默认编码"SX"
     * @param signDate 签订日期，如果为null则使用当前日期
     * @return 合同编号
     */
    String generateContractNo(Long supplierId, LocalDate signDate);
}