package com.malk.service.aliwork;

import com.malk.server.aliwork.YDAuth;

import java.util.List;
import java.util.Map;

/**
 * 宜搭流程原子接口（Client 层）
 *
 * <p>与宜搭开放平台流程 / 审批 API 1:1 对齐，规则同 {@link YDClient_Form}。</p>
 *
 * <p>注意：部分 endpoint URL 可能因宜搭文档版本差异（v1.0 / v2.0 / yida_vpc 旧格式）需要在
 * 实施时对照官方文档最终确认。已在方法 javadoc 的 {@code @apiNote} 中标注推荐路径。</p>
 *
 * @apiNote 官方文档总入口 https://open.dingtalk.com/document/orgapp/yida-overview
 */
public interface YDClient_Process {

    // ================================================================
    //  流程实例生命周期
    // ================================================================

    /**
     * 发起流程
     *
     * @apiNote POST /v1.0/yida/processes/instances/start
     *          https://open.dingtalk.com/document/orgapp/initiate-a-process
     *
     * @param auth              鉴权上下文
     * @param processCode       流程编码（必填）
     * @param formUuid          流程表单 UUID（必填）
     * @param formDataJson      流程表单数据 JSON（必填）
     * @param body_ext 可选:
     *   - noExecuteExpression (Boolean): 默认 true（跳过消息通知）；false 触发业务规则
     *   - deptId (Long): 发起人所在部门 ID
     *   - originatorUserId (String): 指定发起人
     *   - outResult (String): 外部结果参数
     * @return processInstanceId
     */
    String startProcess(YDAuth auth, String processCode, String formUuid, String formDataJson, Map<String, Object> body_ext);

    /**
     * 终止流程
     *
     * @apiNote POST /v1.0/yida/processes/instances/terminate
     *
     * @param auth                鉴权上下文
     * @param processInstanceId   流程实例 ID（必填）
     * @param body_ext 可选:
     *   - operator (String): 操作人 userId
     *   - noExecuteExpression (Boolean)
     *   - reason (String): 终止原因
     * @return 是否成功
     */
    Boolean terminateProcess(YDAuth auth, String processInstanceId, Map<String, Object> body_ext);

    /**
     * 撤回流程（发起人撤回未审批完成的流程）
     *
     * @apiNote POST /v1.0/yida/processes/instances/revoke
     *
     * @param auth                鉴权上下文
     * @param processInstanceId   流程实例 ID
     * @param body_ext 可选:
     *   - operator (String)
     *   - reason (String)
     */
    Boolean revokeProcess(YDAuth auth, String processInstanceId, Map<String, Object> body_ext);

    /**
     * 流程节点跳转
     *
     * @apiNote POST /v1.0/yida/processes/instances/redirect
     *
     * @param auth                鉴权上下文
     * @param processInstanceId   流程实例 ID
     * @param targetActivityId    目标节点 activityId（必填）
     * @param body_ext 可选:
     *   - operator (String)
     *   - isReturn (Boolean): true=回退到前节点；false=前跳
     *   - nextOperatorUserIds (List<String>): 跳转后指定新处理人
     */
    Boolean redirectProcess(YDAuth auth, String processInstanceId, String targetActivityId, Map<String, Object> body_ext);

    // ================================================================
    //  审批任务动作
    // ================================================================

    /**
     * 同意审批任务
     *
     * @apiNote POST /v1.0/yida/processes/tasks/agree
     *
     * @param auth                鉴权上下文
     * @param processInstanceId   流程实例 ID（必填）
     * @param taskId              任务 ID（必填）
     * @param comment             审批意见（必填）
     * @param body_ext 可选:
     *   - operator (String)
     *   - outResult (String)
     *   - noExecuteExpression (Boolean)
     *   - attachments (List<Map>): 附件
     *   - fileUrls (List<String>): 兼容旧版附件格式
     */
    Boolean agreeTask(YDAuth auth, String processInstanceId, String taskId, String comment, Map<String, Object> body_ext);

    /**
     * 拒绝审批任务
     *
     * @apiNote POST /v1.0/yida/processes/tasks/disagree
     *
     * @param auth                鉴权上下文
     * @param processInstanceId   流程实例 ID
     * @param taskId              任务 ID
     * @param comment             审批意见
     * @param body_ext 可选:
     *   - operator (String)
     *   - nextOperatorUserIds (List<String>): 拒绝后指定下一个审批人（部分流程开启此能力）
     *   - outResult (String)
     */
    Boolean disagreeTask(YDAuth auth, String processInstanceId, String taskId, String comment, Map<String, Object> body_ext);

    /**
     * 转交审批任务
     *
     * @apiNote POST /v1.0/yida/processes/tasks/redirect
     *
     * @param auth                鉴权上下文
     * @param processInstanceId   流程实例 ID
     * @param taskId              任务 ID
     * @param toUserId            转交目标 userId（必填）
     * @param comment             转交说明
     * @param body_ext 可选:
     *   - operator (String)
     */
    Boolean redirectTask(YDAuth auth, String processInstanceId, String taskId, String toUserId, String comment, Map<String, Object> body_ext);

    /**
     * 抄送任务
     *
     * @apiNote POST /v1.0/yida/processes/tasks/cc
     *
     * @param auth                鉴权上下文
     * @param processInstanceId   流程实例 ID
     * @param taskId              任务 ID
     * @param toUserIds           抄送 userId 列表（必填）
     * @param comment             抄送说明
     * @param body_ext 可选参数
     */
    Boolean ccTask(YDAuth auth, String processInstanceId, String taskId, List<String> toUserIds, String comment, Map<String, Object> body_ext);

    /**
     * 任务评论（不做同意/拒绝动作，仅加评论）
     *
     * @apiNote POST /v1.0/yida/processes/tasks/comment
     *
     * @param auth                鉴权上下文
     * @param processInstanceId   流程实例 ID
     * @param taskId              任务 ID
     * @param comment             评论内容
     * @param body_ext 可选:
     *   - operator (String)
     *   - atUserIds (List<String>): @ 的用户
     */
    Boolean commentTask(YDAuth auth, String processInstanceId, String taskId, String comment, Map<String, Object> body_ext);

    // ================================================================
    //  流程与任务查询
    // ================================================================

    /**
     * 查询流程实例详情
     *
     * @apiNote GET /v1.0/yida/processes/instances/{processInstanceId}
     *
     * @param auth                鉴权上下文
     * @param processInstanceId   流程实例 ID（必填）
     * @param body_ext 可选参数
     * @return 流程完整信息（含已走节点）
     */
    Map<String, Object> getProcess(YDAuth auth, String processInstanceId, Map<String, Object> body_ext);

    /**
     * 分页查询流程实例
     *
     * @apiNote POST /v1.0/yida/processes/instances
     *
     * @param auth              鉴权上下文
     * @param formUuid          流程表单 UUID
     * @param processCode       流程编码
     * @param searchFieldJson   搜索条件 JSON（可为 "{}"）
     * @param currentPage       当前页
     * @param pageSize          每页条数
     * @param body_ext 可选:
     *   - originatorId (String): 发起人过滤
     *   - instanceStatus (String): RUNNING/NEW/PAUSED/TERMINATED/COMPLETED/ERROR/CANCELED
     *   - approvedResult (String): agree/disagree
     *   - createFromTimeGMT (String)
     *   - createToTimeGMT (String)
     *   - modifiedFromTimeGMT (String)
     *   - modifiedToTimeGMT (String)
     *   - taskId (String)
     * @return 分页 Map
     */
    Map<String, Object> searchProcesses(YDAuth auth, String formUuid, String processCode, String searchFieldJson,
                                        Integer currentPage, Integer pageSize, Map<String, Object> body_ext);

    /**
     * 查询流程实例 ID 列表（轻量）
     *
     * @apiNote POST /v1.0/yida/processes/instanceIds
     *
     * @param auth              鉴权上下文
     * @param formUuid          流程表单 UUID
     * @param processCode       流程编码
     * @param searchFieldJson   搜索条件 JSON
     * @param currentPage       当前页
     * @param pageSize          每页条数
     * @param body_ext          同 searchProcesses
     * @return 流程 ID 列表
     */
    List<String> listProcessIds(YDAuth auth, String formUuid, String processCode, String searchFieldJson,
                                Integer currentPage, Integer pageSize, Map<String, Object> body_ext);

    /**
     * 查询审批操作记录
     *
     * @apiNote GET /v1.0/yida/processes/operationRecords
     *
     * @param auth                鉴权上下文
     * @param processInstanceId   流程实例 ID（必填）
     * @param body_ext            可选参数
     * @return 操作记录列表
     */
    List<Map<String, Object>> listApprovalRecords(YDAuth auth, String processInstanceId, Map<String, Object> body_ext);
}
