package cn.iocoder.yudao.module.archive.service.document;

import cn.iocoder.yudao.framework.common.pojo.PageResult;
import cn.iocoder.yudao.module.archive.api.document.dto.ArchiveDocumentCreateReqDTO;
import cn.iocoder.yudao.module.archive.controller.admin.document.vo.ArchiveDocumentPageReqVO;
import cn.iocoder.yudao.module.archive.controller.admin.document.vo.ArchiveDocumentSaveReqVO;
import cn.iocoder.yudao.module.archive.dal.dataobject.document.ArchiveDocumentDO;

import java.util.List;

/**
 * 档案 Service 接口
 *
 * @author 超级管理员
 */
public interface ArchiveDocumentService {

    /** 档案附件的业务记录类型（{@code system_storage_attachment.record_type}） */
    String DOCUMENT_RECORD_TYPE = "archive_document";

    /**
     * 创建档案
     *
     * @param createReqVO 创建信息
     * @return 档案编号
     */
    Long createDocument(ArchiveDocumentSaveReqVO createReqVO);

    /**
     * 更新档案（借出中的档案不允许修改）
     *
     * @param updateReqVO 更新信息
     */
    void updateDocument(ArchiveDocumentSaveReqVO updateReqVO);

    /**
     * 删除档案（借出中或存在未归还借阅单时不允许删除）
     *
     * @param id 档案编号
     */
    void deleteDocument(Long id);

    /**
     * 获得档案（含敏感档案权限校验）
     *
     * @param id 档案编号
     * @return 档案
     */
    ArchiveDocumentDO getDocument(Long id);

    /**
     * 获得档案（跳过敏感档案权限校验，供模块内部与 RPC 调用使用）
     *
     * @param id 档案编号
     * @return 档案
     */
    ArchiveDocumentDO getDocumentWithoutPermissionCheck(Long id);

    /**
     * 获得档案分页
     *
     * @param reqVO 查询条件
     * @return 档案分页
     */
    PageResult<ArchiveDocumentDO> getDocumentPage(ArchiveDocumentPageReqVO reqVO);

    /**
     * 获得档案列表（导出用，不分页）
     *
     * @param reqVO 查询条件
     * @return 档案列表
     */
    List<ArchiveDocumentDO> getDocumentList(ArchiveDocumentPageReqVO reqVO);

    /**
     * 按来源单据归档（幂等失败语义：重复归档抛「重复归档」异常，并回显已生成的档案编号）
     *
     * @param reqDTO 归档信息
     * @return 档案编号
     */
    Long archiveBySource(ArchiveDocumentCreateReqDTO reqDTO);

    /**
     * 判断来源单据是否已归档
     *
     * @param sourceType 来源类型
     * @param sourceId   来源单据编号
     * @return 是否已归档
     */
    Boolean isArchived(Integer sourceType, Long sourceId);

    /**
     * 按来源单据获得档案
     *
     * @param sourceType 来源类型
     * @param sourceId   来源单据编号
     * @return 档案
     */
    ArchiveDocumentDO getBySource(Integer sourceType, Long sourceId);

    /**
     * 条件更新档案状态为「借出中」（仅当当前为「在库」时生效）
     *
     * @param documentId 档案编号
     * @return 是否更新成功；false 表示档案已被其它流程借出或状态异常
     */
    boolean updateDocumentStatusToBorrowed(Long documentId);

    /**
     * 条件更新档案状态为「在库」（仅当当前为「借出中」时生效）
     *
     * @param documentId 档案编号
     * @return 是否更新成功
     */
    boolean updateDocumentStatusToInStock(Long documentId);

}