namespace Admin.NET.Plugin.ApprovalFlow.Service;

/// <summary>
/// 业务流程回调处理器接口
/// 每种 BizType 实现一个 Handler，注册到 DI 容器
/// </summary>
public interface IFlowBizHandler
{
    /// <summary>
    /// 业务类型编码（与流程定义的 BizType 匹配）
    /// </summary>
    string BizType { get; }

    /// <summary>
    /// 流程发起后回调（可选：更新业务表状态为"审批中"）
    /// </summary>
    Task OnFlowStarted(long bizId, long instanceId) => Task.CompletedTask;

    /// <summary>
    /// 流程结束后回调（必须：更新业务表最终状态）
    /// </summary>
    /// <param name="bizId">业务实体 Id</param>
    /// <param name="instanceId">审批流实例 Id（P4-17 新增，便于业务侧留痕/关联）</param>
    /// <param name="finalStatus">流程最终状态（Approved / Rejected / Cancelled / Terminated）</param>
    /// <param name="lastApproverId">
    /// 最后一位审批人 UserId（P4-17 新增）。
    /// Approved → 最后一个同意节点的操作人；
    /// Rejected → 驳回人（人工驳回）或 null（系统超时自动拒绝）；
    /// Cancelled → null（系统/发起人撤回）；
    /// Terminated → null。
    /// </param>
    Task OnFlowCompleted(long bizId, long instanceId, FlowInstanceStatusEnum finalStatus, long? lastApproverId);

    /// <summary>
    /// 单个节点审批完成回调（可选：按节点推进业务进度）
    /// </summary>
    /// <param name="bizId">业务实体 Id</param>
    /// <param name="instanceId">审批流实例 Id（P4-17 新增）</param>
    /// <param name="nodeId">节点 Id</param>
    /// <param name="nodeName">节点名称</param>
    /// <param name="approverUserId">
    /// 该节点最后一位审批人 UserId（P4-17 新增，系统自动动作时为 null）
    /// </param>
    Task OnNodeCompleted(long bizId, long instanceId, string nodeId, string nodeName, long? approverUserId) => Task.CompletedTask;

    /// <summary>
    /// 获取业务数据用于网关条件表达式求值（可选）
    /// 返回 key-value 字典，key 对应条件表达式中的变量名
    /// 例如: { "amount": 50000, "urgent": 1, "customLevel": 3 }
    /// </summary>
    Task<Dictionary<string, object>> GetBizData(long bizId) => Task.FromResult(new Dictionary<string, object>());
}