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

import com.njcn.rdms.framework.common.pojo.PageResult;
import com.njcn.rdms.module.project.controller.admin.project.execution.vo.execution.ProjectExecutionOwnerChangeReqVO;
import com.njcn.rdms.module.project.controller.admin.project.execution.vo.execution.ProjectExecutionPageReqVO;
import com.njcn.rdms.module.project.controller.admin.project.execution.vo.execution.ProjectExecutionRespVO;
import com.njcn.rdms.module.project.controller.admin.project.execution.vo.execution.ProjectExecutionCreateReqVO;
import com.njcn.rdms.module.project.controller.admin.project.execution.vo.execution.ProjectExecutionDeleteReqVO;
import com.njcn.rdms.module.project.controller.admin.project.execution.vo.execution.ProjectExecutionUpdateReqVO;
import com.njcn.rdms.module.project.controller.admin.project.execution.vo.execution.ProjectExecutionStatusActionReqVO;
import com.njcn.rdms.module.project.dal.dataobject.project.execution.ProjectExecutionDO;

/**
 * 执行主数据 Service。
 */
public interface ProjectExecutionService {

    Long createExecution(Long projectId, ProjectExecutionCreateReqVO reqVO);

    void updateExecution(Long projectId, ProjectExecutionUpdateReqVO reqVO);

    ProjectExecutionDO getExecution(Long projectId, Long executionId);

    PageResult<ProjectExecutionDO> getExecutionPage(Long projectId, ProjectExecutionPageReqVO reqVO);

    /**
     * 获取执行详情 VO，附带状态生命周期与负责人昵称。
     */
    ProjectExecutionRespVO getExecutionRespVO(Long projectId, Long executionId);

    /**
     * 获取执行分页 VO，附带状态生命周期与负责人昵称（昵称按 ownerId 去重批量查询，避免 N+1）。
     */
    PageResult<ProjectExecutionRespVO> getExecutionRespVOPage(Long projectId, ProjectExecutionPageReqVO reqVO);

    void changeOwner(Long projectId, Long executionId, ProjectExecutionOwnerChangeReqVO reqVO);

    /**
     * 删除执行（软删 + CAS 状态校验 + 三重确认）。
     * <p>仅初始态 pending 可删；权限码 project:execution:delete 推荐挂"项目负责人"角色。
     * <p>不级联软删 rdms_execution_assignee / rdms_task（与项目侧 deleteProject 风格一致，下挂记录通过 deleted=0 自然不可见）。
     */
    void deleteExecution(Long projectId, Long executionId, ProjectExecutionDeleteReqVO reqVO);

    void changeExecutionStatus(Long projectId, Long executionId, ProjectExecutionStatusActionReqVO reqVO);

    /**
     * 任务状态变更回调（事件驱动）。
     * 任务侧在 auto_start / complete / cancel 三个动作的成功落库后调用本方法；pause / resume 不调用。
     * 执行侧据此自行分发响应（如自身 auto_start 联动、完成校验链、向项目 / 需求继续传播等）。
     * 调用规则见 docs/项目/任务状态流转设计.md §6.4 触发表。
     * 当前为预埋接口；具体响应在《执行闭环设计》中落地。
     */
    void onTaskStatusChanged(Long executionId, Long taskId, String fromStatus, String toStatus,
                             String actionCode, String reason);

}
