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.assignee.ExecutionAssigneeInactiveReqVO;
import com.njcn.rdms.module.project.controller.admin.project.execution.vo.assignee.ExecutionAssigneeLogPageReqVO;
import com.njcn.rdms.module.project.controller.admin.project.execution.vo.assignee.ExecutionAssigneeLogRespVO;
import com.njcn.rdms.module.project.controller.admin.project.execution.vo.assignee.ExecutionAssigneeRespVO;
import com.njcn.rdms.module.project.controller.admin.project.execution.vo.assignee.ExecutionAssigneeSaveReqVO;

import java.util.List;

/**
 * 执行协办人 Service（B 模型 - 多行周期记录）。
 * <p>
 * 加入：每次 INSERT 一条新的活跃段（不复用旧段）+ 一条 join 日志。
 * 失效：当前活跃段 setRemovedAt + 永久保留 removedReason；写一条 inactive 日志。
 * 负责人转移：在 ProjectExecutionService.changeOwner 内同步写 owner_transfer_in/out 双向事件。
 */
public interface ProjectExecutionAssigneeService {

    /**
     * 获取当前活跃协办人列表（仅 removed_at IS NULL 段）。
     */
    List<ExecutionAssigneeRespVO> getExecutionAssigneeList(Long projectId, Long executionId);

    /**
     * 加入执行协办人。同 userId 当前已活跃则抛 ALREADY_EXISTS；否则 INSERT 新活跃段，写 join 日志。
     */
    Long createExecutionAssignee(Long projectId, Long executionId, ExecutionAssigneeSaveReqVO reqVO);

    /**
     * 失效执行协办人。当前段必须存在且活跃；reason 必填（@NotBlank 已校验，service 不再重复）。
     * 失效后 removedReason 永久保留；写 inactive 日志。
     */
    void inactiveExecutionAssignee(Long projectId, Long executionId, Long assigneeId, ExecutionAssigneeInactiveReqVO reqVO);

    /**
     * 分页查询执行协办人变更历史，按 actionTime DESC, id DESC 排序。
     */
    PageResult<ExecutionAssigneeLogRespVO> getExecutionAssigneeLogPage(Long projectId, Long executionId,
                                                                       ExecutionAssigneeLogPageReqVO reqVO);

    /**
     * 写一条执行协办人变更日志（供 ProjectExecutionServiceImpl.changeOwner 调用）。
     * 只写用户编号与事件语义；昵称由查询阶段通过 AdminUserApi 按当前用户信息回填。
     */
    void writeAssigneeLog(Long executionId, Long userId, String actionType, String reason);

}
