package com.njcn.rdms.module.project.service.project;

import com.njcn.rdms.framework.common.pojo.PageResult;
import com.njcn.rdms.module.project.controller.admin.project.vo.requirement.ProjectRequirementAllowedTransitionBatchRespVO;
import com.njcn.rdms.module.project.controller.admin.project.vo.requirement.ProjectRequirementBatchReqVO;
import com.njcn.rdms.module.project.controller.admin.project.vo.requirement.ProjectRequirementCloseReqVO;
import com.njcn.rdms.module.project.controller.admin.project.vo.requirement.ProjectRequirementModuleReqVO;
import com.njcn.rdms.module.project.controller.admin.project.vo.requirement.ProjectRequirementModuleRespVO;
import com.njcn.rdms.module.project.controller.admin.project.vo.requirement.ProjectRequirementPageReqVO;
import com.njcn.rdms.module.project.controller.admin.project.vo.requirement.ProjectRequirementRespVO;
import com.njcn.rdms.module.project.controller.admin.project.vo.requirement.ProjectRequirementSaveReqVO;
import com.njcn.rdms.module.project.controller.admin.project.vo.requirement.ProjectRequirementSplitReqVO;
import com.njcn.rdms.module.project.controller.admin.project.vo.requirement.ProjectRequirementStatusActionReqVO;
import com.njcn.rdms.module.project.controller.admin.project.vo.requirement.ProjectRequirementStatusDictRespVO;
import com.njcn.rdms.module.project.controller.admin.project.vo.requirement.ProjectRequirementStatusTransitionRespVO;
import com.njcn.rdms.module.project.controller.admin.project.vo.requirement.ProjectRequirementUpdateReqVO;

import java.util.List;

/**
 * 项目需求 Service 接口
 */
public interface ProjectRequirementService {

    Long createRequirement(ProjectRequirementSaveReqVO createReqVO);

    void updateRequirement(ProjectRequirementUpdateReqVO updateReqVO);

    ProjectRequirementRespVO getRequirement(Long id, Long projectId);

    PageResult<ProjectRequirementRespVO> getRequirementPage(ProjectRequirementPageReqVO pageReqVO);

    PageResult<ProjectRequirementRespVO> getRequirementTree(ProjectRequirementPageReqVO pageReqVO);

    PageResult<ProjectRequirementRespVO> getExecutionRequirementOptions(ProjectRequirementPageReqVO pageReqVO);

    void changeRequirementStatus(ProjectRequirementStatusActionReqVO reqVO);

    void changeRequirementStatusForReview(ProjectRequirementStatusActionReqVO reqVO);

    void deleteRequirement(Long id, Long projectId);

    Long splitRequirement(ProjectRequirementSplitReqVO reqVO);

    void closeRequirement(ProjectRequirementCloseReqVO reqVO);

    List<ProjectRequirementStatusTransitionRespVO> getAllowedTransitions(Long requirementId, Long projectId);

    List<ProjectRequirementAllowedTransitionBatchRespVO> getAllowedTransitionsBatch(ProjectRequirementBatchReqVO reqVO);

    Long createRequirementModule(ProjectRequirementModuleReqVO reqVO);

    void updateRequirementModule(ProjectRequirementModuleReqVO reqVO);

    void deleteRequirementModule(Long moduleId, Long projectId);

    List<ProjectRequirementModuleRespVO> getRequirementModuleTree(Long projectId);

    List<ProjectRequirementStatusDictRespVO> getRequirementStatusDict();

    List<ProjectRequirementStatusDictRespVO> getRequirementTerminalStatusDict();

    /**
     * 校验项目需求可被执行关联。
     * <p>用于执行模块在 create / update 时确认传入的 projectRequirementId 合法。
     * 校验：存在且未软删 + 属于本项目 + 非终态。任一不满足抛 ServiceException。
     * 传入 requirementId 为 null 时直接放行（执行侧已确定 projectRequirementId 可选）。
     */
    void validateUsableForExecution(Long projectId, Long projectRequirementId);

}
