AiDOPWarehouse/server/Plugins/Admin.NET.Plugin.ApprovalFlow/Service/FlowTask/FlowTaskService.cs

namespace Admin.NET.Plugin.ApprovalFlow.Service;

/// <summary>
/// 审批任务服务
/// </summary>
[ApiDescriptionSettings(ApprovalFlowConst.GroupName, Order = 90)]
public class FlowTaskService : IDynamicApiController, ITransient
{
    private readonly FlowEngineService _engine;
    private readonly SqlSugarRepository<ApprovalFlowTask> _taskRep;
    private readonly SqlSugarRepository<ApprovalFlowInstance> _instanceRep;
    private readonly UserManager _userManager;

    public FlowTaskService(
        FlowEngineService engine,
        SqlSugarRepository<ApprovalFlowTask> taskRep,
        SqlSugarRepository<ApprovalFlowInstance> instanceRep,
        UserManager userManager)
    {
        _engine = engine;
        _taskRep = taskRep;
        _instanceRep = instanceRep;
        _userManager = userManager;
    }

    // ── 查询 ──

    /// <summary>
    /// 我的待办（分页）
    /// </summary>
    [HttpPost]
    [ApiDescriptionSettings(Name = "MyPendingPage")]
    [DisplayName("我的待办")]
    public async Task<SqlSugarPagedList<TaskPageOutput>> MyPendingPage(TaskPageInput input)
    {
        var userId = _userManager.UserId;
        return await _taskRep.AsQueryable()
            .InnerJoin<ApprovalFlowInstance>((t, i) => t.InstanceId == i.Id)
            .Where((t, i) => t.AssigneeId == userId && t.Status == FlowTaskStatusEnum.Pending)
            .WhereIF(!string.IsNullOrWhiteSpace(input.BizType), (t, i) => i.BizType == input.BizType)
            .OrderByDescending((t, i) => t.CreateTime)
            .Select((t, i) => new TaskPageOutput
            {
                Id = t.Id,
                InstanceId = t.InstanceId,
                NodeId = t.NodeId,
                NodeName = t.NodeName,
                Status = t.Status,
                Title = i.Title,
                BizType = i.BizType,
                BizId = i.BizId,
                BizNo = i.BizNo,
                InitiatorName = i.InitiatorName,
                StartTime = i.StartTime,
                CreateTime = t.CreateTime,
                IsDelegate = t.IsDelegate,
                DelegateForUserName = t.DelegateForUserName,
            })
            .ToPagedListAsync(input.Page, input.PageSize);
    }

    /// <summary>
    /// 我的已办（分页）
    /// </summary>
    [HttpPost]
    [ApiDescriptionSettings(Name = "MyDonePage")]
    [DisplayName("我的已办")]
    public async Task<SqlSugarPagedList<TaskPageOutput>> MyDonePage(TaskPageInput input)
    {
        var userId = _userManager.UserId;
        return await _taskRep.AsQueryable()
            .InnerJoin<ApprovalFlowInstance>((t, i) => t.InstanceId == i.Id)
            .Where((t, i) => t.AssigneeId == userId && t.Status != FlowTaskStatusEnum.Pending)
            .WhereIF(!string.IsNullOrWhiteSpace(input.BizType), (t, i) => i.BizType == input.BizType)
            .OrderByDescending((t, i) => t.ActionTime)
            .Select((t, i) => new TaskPageOutput
            {
                Id = t.Id,
                InstanceId = t.InstanceId,
                NodeId = t.NodeId,
                NodeName = t.NodeName,
                Status = t.Status,
                Comment = t.Comment,
                ActionTime = t.ActionTime,
                Title = i.Title,
                BizType = i.BizType,
                BizId = i.BizId,
                BizNo = i.BizNo,
                InitiatorName = i.InitiatorName,
                StartTime = i.StartTime,
                CreateTime = t.CreateTime,
                IsDelegate = t.IsDelegate,
                DelegateForUserName = t.DelegateForUserName,
            })
            .ToPagedListAsync(input.Page, input.PageSize);
    }

    /// <summary>
    /// 我发起的（分页）
    /// </summary>
    [HttpPost]
    [ApiDescriptionSettings(Name = "MyInitiatedPage")]
    [DisplayName("我发起的")]
    public async Task<SqlSugarPagedList<InstancePageOutput>> MyInitiatedPage(InstancePageInput input)
    {
        var userId = _userManager.UserId;
        var page = await _instanceRep.AsQueryable()
            .Where(i => i.InitiatorId == userId)
            .WhereIF(!string.IsNullOrWhiteSpace(input.BizType), i => i.BizType == input.BizType)
            .WhereIF(input.Status.HasValue, i => i.Status == input.Status!.Value)
            .OrderByDescending(i => i.CreateTime)
            .Select(i => new InstancePageOutput
            {
                Id = i.Id,
                BizType = i.BizType,
                BizId = i.BizId,
                BizNo = i.BizNo,
                Title = i.Title,
                Status = i.Status,
                CurrentNodeId = i.CurrentNodeId,
                StartTime = i.StartTime,
                EndTime = i.EndTime,
                InitiatorName = i.InitiatorName,
            })
            .ToPagedListAsync(input.Page, input.PageSize);

        var runningIds = page.Items.Where(x => x.Status == FlowInstanceStatusEnum.Running).Select(x => x.Id).ToList();
        if (runningIds.Count > 0)
        {
            var pendingAssignees = await _taskRep.AsQueryable()
                .Where(t => runningIds.Contains(t.InstanceId) && t.Status == FlowTaskStatusEnum.Pending)
                .Select(t => new { t.InstanceId, t.AssigneeName })
                .ToListAsync();
            var grouped = pendingAssignees.GroupBy(x => x.InstanceId)
                .ToDictionary(g => g.Key, g => string.Join(", ", g.Select(x => x.AssigneeName).Distinct()));
            foreach (var item in page.Items)
            {
                if (grouped.TryGetValue(item.Id, out var names))
                    item.CurrentAssigneeName = names;
            }
        }

        return page;
    }

    /// <summary>
    /// 待办数量
    /// </summary>
    [HttpGet]
    [ApiDescriptionSettings(Name = "MyPendingCount")]
    [DisplayName("待办数量")]
    public async Task<int> MyPendingCount()
    {
        var userId = _userManager.UserId;
        return await _taskRep.AsQueryable()
            .Where(t => t.AssigneeId == userId && t.Status == FlowTaskStatusEnum.Pending)
            .CountAsync();
    }

    // ── 操作 ──

    /// <summary>
    /// 只能经专用业务入口审批的业务类型 → 对应的引导文案。
    ///
    /// 背景：这些业务在专用服务里额外建立了通用审批链没有的 authority
    /// （租户解析 → 业务单归属校验 → 当前节点守卫 → UseTranAsync 事务边界），
    /// 走通用 flowTask/approve|reject 会把这四层全部绕过（引擎侧 GetPendingTask
    /// 只校验「任务存在 / Pending / 指派人==当前用户」，不校验业务类型与租户）。
    /// 仅隐藏前端按钮不足以闭环——手工 HTTP 仍可直达，故在网关层 fail-closed。
    ///
    /// 这里刻意硬编码 BizType 字符串：ApprovalFlow 插件不引用 AiDOP 插件
    /// （依赖方向为 AiDOP → ApprovalFlow，反向会成环），无法引用业务侧常量。
    ///
    /// <para><b>唯一 Authority Source</b>：某 BizType 的「是否只能走专用入口」以及
    /// 「封堵范围延伸到哪些通用动作」都由本字典的同一条记录表达，不得再另立集合。
    /// 判定一律走 <see cref="DedicatedEntryPolicy"/> 的显式字段，禁止从文案内容、
    /// 字典顺序或 BizType 字面量前缀反推。</para>
    /// </summary>
    private static readonly Dictionary<string, DedicatedEntryPolicy> DedicatedEntryOnlyBizTypes = new()
    {
        ["S5_IQC_INSPBILL"] = new("来料检验单请在「来料检验单详情」页完成审核，不支持在审批中心直接同意/拒绝。",
            BlockFlowMutation: false),
        // S6 过程检验单：N3_QE_DISPOSITION 的处置记录（ado_s6_ipqc_quality_disposition）是由
        // S6ProcessInspectionReview.qe-disposition 在同一事务里 INSERT 后才推进流程的。走通用审批会把
        // 流程直接推到 end 而永不写处置记录 —— 流程显示已闭环、处置轨迹却为空，且事后无法补记。
        // 另：专用 supervisor-return 要求退回意见必填且回退到 N1，通用 Reject 会把实例直接置为终态。
        ["S6_PROCESS_INSPECTION"] = new("过程检验单请在「过程检验」业务页完成主管审核或质量处置，不支持在审批中心直接同意/拒绝。",
            BlockFlowMutation: false),
        // S6 IPQC 过程检验单（源 qms_gcjyd，与上面 Phase1C 链同名不同源）：同款旁路，且破坏面更大。
        // ① N3_QUALITY_DISPOSITION 的处置记录（ado_s6_ipqc_quality_disposition）由
        //    IpqcInspectionDisposition.submit 在同一事务内 INSERT 后才推进流程；
        // ② 同一事务还会把扩展表 ado_s6_ipqc_inspection_flow_state 的 business_status 推到 DISPOSED。
        // 走通用审批两者都不会发生 —— 流程显示已闭环，处置轨迹为空且业务状态永久停在旧值。
        // 另：专用 supervisor-return 要求退回意见必填、经 ReturnToPrev 回到 N1，通用 Reject 直接置实例终态。
        // 2026-09-14 实测：通用 approve 曾真实把一条 IPQC N2 待办推进到 end。
        ["IPQC_INSPECTION"] = new("过程检验单请在「过程检验」业务页完成检验、主管审核或质量处置，不支持在审批中心直接同意/拒绝。",
            BlockFlowMutation: false),
        // S7 成品检验单：本链的 IFlowBizHandler（FqcInspBillFlowBizHandler）三个回调**全是 no-op**，
        // 业务副作用一律由专用 API 在引擎之外、同事务内完成，故通用审批绕过的是全部业务语义：
        // ① N1 通用 approve 会在 submit-result 从未写入 pd/hgsl/bhgsl/clfs 的情况下推到 N2 ——
        //    主管收到一张没有检验结果的单；更严重的是 GW_RESULT 网关读 pd 判 disposition_required，
        //    pd 为 null 时算 0，不合格单会被静默绕过 N3 QE 处置直接结束。
        // ② N2 通用 approve 跳过 TryEnqueueFqcPassOutboxAsync，合格出站 Outbox 永不入队。
        // ③ N2 通用 reject 走 FlowEngine.Reject——实例直接置 Rejected 终态并取消所有待办，
        //    而专用 supervisor-reject 是 ReturnToPrev 回 N1 + 同事务把 qms_fqcbj.FINSPECTSTATUS
        //    复位「检验中」+ 同步 mdp_std_fqc_task.inspect_progress；走通用则单据永久卡死、
        //    检验进度永远停在「检验完成」，且通用 Reject 连退回意见都不要求。
        // ④ N3 通用 approve 推到 end 而 ado_s7_fqc_qe_disposition 永不写入 —— 流程显示闭环、
        //    处置轨迹为空且事后无法补记（与 IPQC_INSPECTION 同款，该形态 2026-09-14 已实证发生过）。
        //
        // BlockFlowMutation=true 的唯一一条：除同意/拒绝外，退回上一步/撤回/转办/加签
        // 四个变更型通用入口也一并封堵。理由同样源于「业务副作用不在引擎里」：
        // ⑤ 通用 ReturnToPrev 绕过专用 supervisor-reject 的强制退回意见、同事务复位
        //    FINSPECTSTATUS、以及 mdp_std_fqc_task.inspect_progress 同步；从 N3 调用还会退到 N2，
        //    产生专用设计从不产生的状态。
        // ⑥ 通用 Withdraw 把实例置 Cancelled 而 OnFlowCompleted 为 no-op，报检单永久停在
        //    「检验中」：重提结果被「流程已结束」拒、重新认领被「负责人已锁定」拒、
        //    重新生成检验单被幂等唯一约束拒 —— 三条恢复路径全部关闭。
        // ⑦ 通用 Transfer / AddSign 把 AssigneeId 原样写入（不校验存在性/租户/角色），
        //    而专用 N2/N3 门禁是「持有本节点待办」而非「持有角色」，于是无
        //    ROLE_S7_FQC_SUPERVISOR / ROLE_S7_FQC_QE 的用户可直接完成主管审核或 QE 处置。
        ["S7_FQC_INSPBILL"] = new("成品检验单请在「FQC检验单详情」页完成检验结果提交、主管审核或质量处置，不支持在审批中心直接同意/拒绝/退回/撤回/转办/加签。",
            BlockFlowMutation: true),
    };

    /// <summary>
    /// 单条 BizType 的专用入口策略。<b>与 BizType 同属一条记录</b>——封堵范围不再由
    /// 另一个集合表达，避免出现第二份 BizType authority source。
    /// </summary>
    /// <param name="Message">命中时对外抛出的引导文案。同一条 BizType 的所有通用入口共用它。</param>
    /// <param name="BlockFlowMutation">
    /// 是否把封堵范围从「同意 / 拒绝」延伸到变更型通用入口
    /// （退回上一步 / 撤回 / 转办 / 加签）。
    /// <para><c>false</c> 表示该 BizType 目前只封堵同意/拒绝，变更型入口保持既有行为——
    /// S5 / S6 / IPQC 三条即如此：它们的绕过理由与 S7 同源，很可能也应纳入，
    /// 但纳入会改变其现有行为，需各自独立评估，不在此顺手扩大。</para>
    /// </param>
    private sealed record DedicatedEntryPolicy(string Message, bool BlockFlowMutation);

    /// <summary>
    /// 通用审批动作前置守卫：按 taskId 从库中反查权威 BizType，命中名单即拒绝。
    ///
    /// 只做「拒绝」不做「放行授权」，故不引入新的租户判定
    /// （ApprovalFlowTask / ApprovalFlowInstance 无 TenantId 列，租户边界仍由
    /// 各业务专用入口的业务表 tenant 谓词负责）。
    /// 任务/实例不存在时不在此抛错，交由引擎沿用既有错误语义。
    /// </summary>
    private async Task EnsureDedicatedEntryOnlyAsync(long taskId)
    {
        var task = await _taskRep.GetByIdAsync(taskId);
        if (task == null) return;
        var instance = await _instanceRep.GetByIdAsync(task.InstanceId);
        if (instance?.BizType == null) return;
        if (DedicatedEntryOnlyBizTypes.TryGetValue(instance.BizType, out var hint))
            throw Oops.Oh(hint.Message);
    }

    /// <summary>
    /// 变更型通用入口（退回上一步 / 转办 / 加签）的前置守卫：按 taskId 反查权威 BizType，
    /// 命中且 <see cref="DedicatedEntryPolicy.BlockFlowMutation"/> 为真即拒绝。
    ///
    /// <para>必须作为动作方法的第一条语句调用——引擎侧这些动作没有 <c>[UnitOfWork]</c>，
    /// 一旦进入就会按「取消同节点待办 → 改 task 状态 → 改 CurrentNodeId → 建新任务」的顺序
    /// 逐步提交，中途失败无法回滚。守卫放在进入引擎之前才能保证 ZERO MUTATION。</para>
    /// </summary>
    private async Task EnsureDedicatedFlowMutationOnlyByTaskAsync(long taskId)
    {
        var task = await _taskRep.GetByIdAsync(taskId);
        if (task == null) return;
        await EnsureDedicatedFlowMutationOnlyByInstanceAsync(task.InstanceId);
    }

    /// <summary>
    /// 同上，但按 instanceId 判定——撤回（Withdraw）的入参只有 instanceId，没有 taskId。
    /// 只做只读反查，不改任何实体。
    ///
    /// <para>判定读的是同一份 <see cref="DedicatedEntryOnlyBizTypes"/> 里该 BizType 记录的
    /// <see cref="DedicatedEntryPolicy.BlockFlowMutation"/> 显式字段，
    /// 不查任何第二个集合、不从文案内容或 BizType 字面量反推。</para>
    /// </summary>
    private async Task EnsureDedicatedFlowMutationOnlyByInstanceAsync(long instanceId)
    {
        var instance = await _instanceRep.GetByIdAsync(instanceId);
        if (instance?.BizType == null) return;
        if (!DedicatedEntryOnlyBizTypes.TryGetValue(instance.BizType, out var policy)) return;
        if (!policy.BlockFlowMutation) return;
        throw Oops.Oh(policy.Message);
    }

    /// <summary>
    /// 同意
    /// </summary>
    [HttpPost]
    [ApiDescriptionSettings(Name = "Approve")]
    [DisplayName("同意")]
    public async Task Approve(TaskActionInput input)
    {
        await EnsureDedicatedEntryOnlyAsync(input.TaskId);
        await _engine.Approve(input.TaskId, input.Comment);
    }

    /// <summary>
    /// 拒绝
    /// </summary>
    [HttpPost]
    [ApiDescriptionSettings(Name = "Reject")]
    [DisplayName("拒绝")]
    public async Task Reject(TaskActionInput input)
    {
        await EnsureDedicatedEntryOnlyAsync(input.TaskId);
        await _engine.Reject(input.TaskId, input.Comment);
    }

    /// <summary>
    /// 转办
    /// </summary>
    [HttpPost]
    [ApiDescriptionSettings(Name = "Transfer")]
    [DisplayName("转办")]
    public async Task Transfer(TaskTransferInput input)
    {
        await EnsureDedicatedFlowMutationOnlyByTaskAsync(input.TaskId);
        await _engine.Transfer(input.TaskId, input.TargetUserId, input.Comment);
    }

    /// <summary>
    /// 撤回
    /// </summary>
    [HttpPost]
    [ApiDescriptionSettings(Name = "Withdraw")]
    [DisplayName("撤回")]
    public async Task Withdraw(TaskWithdrawInput input)
    {
        await EnsureDedicatedFlowMutationOnlyByInstanceAsync(input.InstanceId);
        await _engine.Withdraw(input.InstanceId);
    }

    /// <summary>
    /// 退回上一步
    /// </summary>
    [HttpPost]
    [ApiDescriptionSettings(Name = "ReturnToPrev")]
    [DisplayName("退回上一步")]
    public async Task ReturnToPrev(TaskActionInput input)
    {
        await EnsureDedicatedFlowMutationOnlyByTaskAsync(input.TaskId);
        await _engine.ReturnToPrev(input.TaskId, input.Comment);
    }

    /// <summary>
    /// 加签
    /// </summary>
    [HttpPost]
    [ApiDescriptionSettings(Name = "AddSign")]
    [DisplayName("加签")]
    public async Task AddSign(TaskAddSignInput input)
    {
        await EnsureDedicatedFlowMutationOnlyByTaskAsync(input.TaskId);
        await _engine.AddSign(input.TaskId, input.TargetUserId, input.Comment);
    }

    /// <summary>
    /// 升级
    /// </summary>
    [HttpPost]
    [ApiDescriptionSettings(Name = "Escalate")]
    [DisplayName("升级")]
    public async Task Escalate(TaskActionInput input)
    {
        await _engine.Escalate(input.TaskId, input.Comment);
    }

    /// <summary>
    /// 获取指定任务所属节点的升级配置
    /// </summary>
    [HttpGet]
    [ApiDescriptionSettings(Name = "GetEscalationConfig")]
    [DisplayName("获取升级配置")]
    public async Task<EscalationConfigOutput> GetEscalationConfig([FromQuery] long taskId)
    {
        var task = await _taskRep.GetByIdAsync(taskId);
        if (task == null) return new EscalationConfigOutput { Enabled = false };

        var instance = await _instanceRep.GetByIdAsync(task.InstanceId);
        if (instance == null) return new EscalationConfigOutput { Enabled = false };

        var flowData = System.Text.Json.JsonSerializer.Deserialize<ApprovalFlowItem>(instance.FlowJsonSnapshot ?? "{}");
        var node = flowData?.Nodes?.FirstOrDefault(n => n.Id == task.NodeId);
        var props = node?.Properties;

        return new EscalationConfigOutput
        {
            Enabled = props?.EnableManualEscalation == true
                      && !string.IsNullOrWhiteSpace(props?.EscalationApproverType)
                      && !string.IsNullOrWhiteSpace(props?.EscalationApproverIds),
            EscalationApproverNames = props?.EscalationApproverNames,
        };
    }

    /// <summary>
    /// 催办
    /// </summary>
    [HttpPost]
    [ApiDescriptionSettings(Name = "Urge")]
    [DisplayName("催办")]
    public async Task Urge(TaskUrgeInput input)
    {
        await _engine.Urge(input.InstanceId);
    }

    /// <summary>
    /// 立即触发一次超时任务扫描（等价于 FlowTimeoutJob 的单次执行）
    /// 仅 SuperAdmin / SysAdmin 可调用，用于运维排障与 E2E 自动化验收。
    /// </summary>
    [HttpPost]
    [ApiDescriptionSettings(Name = "TriggerTimeoutScan")]
    [DisplayName("立即扫描超时任务")]
    public async Task<int> TriggerTimeoutScan()
    {
        if (!_userManager.SuperAdmin && !_userManager.SysAdmin)
            throw Oops.Oh("仅超级管理员/系统管理员可触发该操作");

        return await _engine.ScanTimeoutTasks();
    }

    /// <summary>
    /// 批量同意
    /// </summary>
    [HttpPost]
    [ApiDescriptionSettings(Name = "BatchApprove")]
    [DisplayName("批量同意")]
    public async Task<BatchActionResult> BatchApprove(BatchActionInput input)
    {
        var result = new BatchActionResult();
        foreach (var taskId in input.TaskIds)
        {
            try
            {
                await EnsureDedicatedEntryOnlyAsync(taskId);
                await _engine.Approve(taskId, input.Comment);
                result.SuccessCount++;
            }
            catch (Exception ex)
            {
                result.FailCount++;
                result.FailItems.Add(new BatchActionFailItem { TaskId = taskId, Error = ex.Message });
            }
        }
        return result;
    }

    /// <summary>
    /// 批量拒绝
    /// </summary>
    [HttpPost]
    [ApiDescriptionSettings(Name = "BatchReject")]
    [DisplayName("批量拒绝")]
    public async Task<BatchActionResult> BatchReject(BatchActionInput input)
    {
        var result = new BatchActionResult();
        foreach (var taskId in input.TaskIds)
        {
            try
            {
                await EnsureDedicatedEntryOnlyAsync(taskId);
                await _engine.Reject(taskId, input.Comment);
                result.SuccessCount++;
            }
            catch (Exception ex)
            {
                result.FailCount++;
                result.FailItems.Add(new BatchActionFailItem { TaskId = taskId, Error = ex.Message });
            }
        }
        return result;
    }
}