AiDOPWarehouse/server/Plugins/Admin.NET.Plugin.AiDOP/Service/S8/S8TaskFlowService.cs

using Admin.NET.Plugin.AiDOP.Const.S8;
using Admin.NET.Core.Service;
using Admin.NET.Plugin.AiDOP.Entity.S8;
using Admin.NET.Plugin.AiDOP.Infrastructure.S8;
using Admin.NET.Plugin.ApprovalFlow;
using Admin.NET.Plugin.ApprovalFlow.Service;
using Microsoft.Extensions.Logging;

namespace Admin.NET.Plugin.AiDOP.Service.S8;

public class S8TaskFlowService : ITransient
{
    private readonly SqlSugarRepository<AdoS8Exception> _rep;
    private readonly SqlSugarRepository<AdoS8ExceptionTimeline> _timelineRep;
    private readonly IS8UserScopeValidator _userScope;
    private readonly IS8ClaimEligibility _claimEligibility;
    private readonly IS8ExceptionActionAuthorizer _actionAuthorizer;
    private readonly IS8RuleHandlerPoolReader _handlerPool;
    private readonly SqlSugarRepository<ApprovalFlowInstance> _flowInstanceRep;
    private readonly SqlSugarRepository<ApprovalFlowTask> _flowTaskRep;
    private readonly FlowEngineService _flowEngine;
    private readonly UserManager _userManager;
    private readonly S8NotificationLayerResolver _notificationLayerResolver;
    private readonly SysNoticeService _noticeService;
    private readonly ILogger<S8TaskFlowService> _logger;

    public S8TaskFlowService(
        SqlSugarRepository<AdoS8Exception> rep,
        SqlSugarRepository<AdoS8ExceptionTimeline> timelineRep,
        IS8UserScopeValidator userScope,
        IS8ClaimEligibility claimEligibility,
        IS8ExceptionActionAuthorizer actionAuthorizer,
        IS8RuleHandlerPoolReader handlerPool,
        SqlSugarRepository<ApprovalFlowInstance> flowInstanceRep,
        SqlSugarRepository<ApprovalFlowTask> flowTaskRep,
        FlowEngineService flowEngine,
        UserManager userManager,
        S8NotificationLayerResolver notificationLayerResolver,
        SysNoticeService noticeService,
        ILogger<S8TaskFlowService> logger)
    {
        _rep = rep;
        _timelineRep = timelineRep;
        _userScope = userScope;
        _claimEligibility = claimEligibility;
        _actionAuthorizer = actionAuthorizer;
        _handlerPool = handlerPool;
        _flowInstanceRep = flowInstanceRep;
        _flowTaskRep = flowTaskRep;
        _flowEngine = flowEngine;
        _userManager = userManager;
        _notificationLayerResolver = notificationLayerResolver;
        _noticeService = noticeService;
        _logger = logger;
    }

    /// <summary>
    /// 认领。<b>处理人 = 当前登录账号，客户端说了不算。</b>
    ///
    /// <para>旧签名收 <c>assigneeId</c>，意味着任何有认领权限的人都能替别人认领
    /// —— 而「替别人指派」在业务上是另一个动作（<see cref="TransferAsync"/>），
    /// 有自己的权限位 <c>ExceptionAssign</c>。两者混在一条 API 里，
    /// 结果是弱权限位能干强权限位的事。</para>
    ///
    /// <para><b>First Claim Wins</b>：并发认领由<b>一条带前置条件的 UPDATE</b> 裁决，
    /// 不靠先 SELECT 再 UPDATE —— 那两步之间的窗口正是两个人同时认领成功的地方。
    /// 谓词里的 <c>assignee_user_id IS NULL</c> 与状态白名单由数据库在同一行锁内求值，
    /// 影响行数 0 即表示已被别人抢先。</para>
    /// </summary>
    public async Task<AdoS8Exception> ClaimAsync(long id, long tenantId, string? remark)
    {
        var currentUserId = GetCurrentUserId();
        // 认领人必须是本租户的可用账号。当前登录态理论上必然满足，
        // 但这条断言同时挡住「跨租户 scope 解析出错」这类上游故障。
        await _userScope.EnsureActiveUserAsync(tenantId, currentUserId, "认领人");

        var e = await LoadAsync(id, tenantId) ?? throw new S8BizException("异常不存在");
        if (!S8StatusRules.IsAllowedTransition(e.Status, "ASSIGNED"))
            throw new S8BizException($"状态 {e.Status} 不可认领");

        // S8-HANDLER-POOL-1：认领资格 = 动作权限 ∩ 规则责任。
        // 状态与并发那一维由下面的原子 UPDATE 负责，这里不重复判断。
        var eligibility = await _claimEligibility.CheckAsync(tenantId, currentUserId, e);
        if (!eligibility.Allowed)
        {
            _logger.LogInformation(
                "s8_claim_denied exceptionId={Id} tenantId={TenantId} userId={UserId} reason={Reason} rule={Rule}",
                e.Id, tenantId, currentUserId, eligibility.ReasonCode, e.SourceRuleCode);
            throw new S8BizException(eligibility.Message ?? "没有权限执行该操作");
        }

        var fromStatus = e.Status;
        var now = DateTime.Now;

        // ── 原子裁决：整条 UPDATE 就是那把锁 ──
        var affected = await _rep.Context.Updateable<AdoS8Exception>()
            .SetColumns(x => new AdoS8Exception
            {
                Status = "ASSIGNED",
                AssigneeUserId = currentUserId,
                AssignedAt = now,
                UpdatedAt = now
            })
            .Where(x => x.Id == e.Id
                        && x.TenantId == tenantId
                        && !x.IsDeleted
                        && x.Status == fromStatus
                        && x.AssigneeUserId == null)
            .ExecuteCommandAsync();

        if (affected == 0)
        {
            _logger.LogInformation(
                "s8_claim_lost_race exceptionId={Id} tenantId={TenantId} userId={UserId} fromStatus={From}",
                e.Id, tenantId, currentUserId, fromStatus);
            throw new S8BizException("该异常已被其他人员认领");
        }

        await InsertTimelineAsync(e.Id, "CLAIM", "认领", fromStatus, "ASSIGNED", currentUserId, null, remark);

        // 认领走的是原子 UPDATE —— 它只写了库，**没有回写内存里的 e**。
        // 直接拿 e 去派发通知，收件人类型 ASSIGNEE 会读到 null 而解析出 0 人，
        // 且整条链路一路成功、日志里连一条记录都不会留下（本地实测到过这个形态）。
        // 因此先重新加载，再用带上处理人的实体派发。
        var claimed = await LoadAsync(id, tenantId) ?? e;

        // 注：认领仅承接异常，不视为审批流完成。审批流的"通过"在"开始处理"那一步触发。
        await DispatchEventAsync(claimed, S8NotifyEventCode.ExceptionClaimed, "S8异常已分派给你",
            $"{claimed.ExceptionCode} 已被认领。");
        return claimed;
    }

    /// <summary>
    /// 转派 / 指派。与 <see cref="ClaimAsync"/> 语义分离：这里<b>可以</b>指定别人，
    /// 因此它挂的是 <c>ExceptionAssign</c> 权限位，而不是 <c>ExceptionClaim</c>。
    /// 目标必须是<b>当前租户</b>的<b>启用</b>账号，工厂不参与判定。
    /// </summary>
    public async Task<AdoS8Exception> TransferAsync(long id, long tenantId, long newAssigneeUserId, string? remark)
    {
        var allowedStatuses = new HashSet<string> { "ASSIGNED", "IN_PROGRESS" };
        var target = await _userScope.EnsureActiveUserAsync(tenantId, newAssigneeUserId, "转派目标账号");
        var e = await LoadAsync(id, tenantId) ?? throw new S8BizException("异常不存在");

        // S8-HANDLER-POOL-1：转派目标同样受责任池约束。
        //
        // 不留「转给池外账号」的后门：那等于绕过责任池本身 —— 池子写着 A、B 负责，
        // 实际单据却落到 C 手里，而池配置看起来仍然正确。需要转给池外的人时，
        // 正确做法是先把他加进该规则的处理账号池，再转派。
        //
        // 人工提报无来源规则，不受池约束（与认领同一口径）。
        if (!string.IsNullOrWhiteSpace(e.SourceRuleCode)
            && !await _handlerPool.IsMemberAsync(tenantId, e.SourceRuleCode!, target.UserId))
        {
            throw new S8BizException(
                $"{target.DisplayName} 不是该规则的处理人员，无法转派。请先将其加入该规则的处理账号池。");
        }
        if (e.ActiveFlowInstanceId.HasValue)
            throw new S8BizException("审批进行中不可转派");
        if (e.Status == "ESCALATED")
            throw new S8BizException("升级审批中不可转派");
        if (S8StatusRules.IsTerminal(e.Status))
            throw new S8BizException("已关闭不可转派");
        if (!allowedStatuses.Contains(e.Status))
            throw new S8BizException($"状态 {e.Status} 不可转派");

        e.AssigneeUserId = target.UserId;
        e.UpdatedAt = DateTime.Now;

        // S8-SYSUSER-ONLY-1：原「转派同步处理部门 = 新处理人所属部门」已退役。
        // 那条链路是 EmployeeMaster.Department(字符串) → DepartmentMaster，**只有员工主数据才有部门**；
        // SysUser 侧没有任何指向 DepartmentMaster 的关系（SysUser.OrgId 指的是 SysOrg 公司/工厂树，
        // 与 DepartmentMaster 是两棵互不相干的树）。在 SysUser-only 模型下它无法成立，
        // 因此不保留、也不用 SysOrg 硬凑一个近似值 —— 责任部门由建单时确定（规则默认部门 / 人工提报选择），
        // 需要变更由人显式改，不再随处理人静默漂移。
        await _rep.AsTenant().UseTranAsync(async () =>
        {
            await _rep.UpdateAsync(e);
            await InsertTimelineAsync(e.Id, "TRANSFER", "转派", e.Status, e.Status, GetCurrentUserId(), null, remark);
        }, ex => throw ex);

        await DispatchEventAsync(e, S8NotifyEventCode.ExceptionTransferred, "S8异常已转派给你",
            $"{e.ExceptionCode} 已转派给 {target.DisplayName}。");

        // 双线合一：S8 转派 = TB001 任务转办给新处理人。
        await TryTransferIntakeOnTransferAsync(e.Id, target.UserId, remark);

        return e;
    }

    private async Task TryTransferIntakeOnTransferAsync(long exceptionId, long newAssigneeUserId, string? remark)
    {
        try
        {
            var instance = await _flowInstanceRep.AsQueryable()
                .Where(x => x.BizType == "EXCEPTION_REPORT"
                            && x.BizId == exceptionId
                            && x.Status == FlowInstanceStatusEnum.Running)
                .FirstAsync();
            if (instance == null) return;

            var currentUserId = _userManager.UserId;
            var task = await _flowTaskRep.AsQueryable()
                .Where(x => x.InstanceId == instance.Id
                            && x.AssigneeId == currentUserId
                            && x.Status == FlowTaskStatusEnum.Pending)
                .FirstAsync();
            if (task == null) return;

            // S8-SYSUSER-ONLY-1：S8 处理人与 FlowEngine assignee 现在是同一个 ID 空间，
            // 原来的 EmployeeMaster.SysUserId 桥接（以及它「未绑定就静默跳过」的失败模式）已删除。
            await _flowEngine.Transfer(task.Id, newAssigneeUserId, remark ?? "S8 转派（双线合一自动转办）");
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex,
                "S8 转派时自动转办 TB001 任务失败 exceptionId={Id} newAssigneeUserId={AssigneeUserId}",
                exceptionId, newAssigneeUserId);
        }
    }

    public async Task<AdoS8Exception> StartProgressAsync(long id, long tenantId, string? remark)
    {
        var currentUserId = GetCurrentUserId();
        var e = await LoadAsync(id, tenantId) ?? throw new S8BizException("异常不存在");
        if (!S8StatusRules.IsAllowedTransition(e.Status, "IN_PROGRESS"))
            throw new S8BizException($"状态 {e.Status} 不可开始处理");

        var fromStatus = e.Status;
        e.Status = "IN_PROGRESS";
        e.UpdatedAt = DateTime.Now;

        await _rep.AsTenant().UseTranAsync(async () =>
        {
            await _rep.UpdateAsync(e);
            await InsertTimelineAsync(e.Id, "START_PROGRESS", "开始处理", fromStatus, "IN_PROGRESS", currentUserId, null, remark);
        }, ex => throw ex);

        // 双线合一：开始处理 = TB001 异常提报审批通过。
        // 当前用户必须是 TB001 task 的 AssigneeId，FlowEngine 强校验。
        await TryApproveIntakeOnStartProgressAsync(e, currentUserId);

        return e;
    }

    private async Task TryApproveIntakeOnStartProgressAsync(AdoS8Exception e, long currentUserId)
    {
        long? instanceId = null, taskId = null;
        try
        {
            // S8-S1-EXCEPTION-FLOW-SYNC-FIX-1：实例/任务查询同样清数据范围过滤（ApprovalFlowInstance/Task 继承 EntityBaseOrg）。
            // 非超管用户在 DataScope=Self 时被「CreateUserId==当前用户」过滤、Dept/DeptChild 时被 OrgId 过滤，会查不到
            // 由他人（或系统）创建的 flow，双线合一静默失效。ClearFilter() 清全部数据范围过滤；BizType+BizId+assignee 已限定，
            // 无跨 BizType 误伤；ApprovalFlowInstance/Task 无软删与租户过滤。
            var instance = await _flowInstanceRep.AsQueryable()
                .ClearFilter()
                .Where(x => x.BizType == "EXCEPTION_REPORT"
                            && x.BizId == e.Id
                            && x.Status == FlowInstanceStatusEnum.Running)
                .FirstAsync();
            if (instance == null) return;
            instanceId = instance.Id;

            var task = await _flowTaskRep.AsQueryable()
                .ClearFilter()
                .Where(x => x.InstanceId == instance.Id
                            && x.AssigneeId == currentUserId
                            && x.Status == FlowTaskStatusEnum.Pending)
                .FirstAsync();
            if (task == null) return;
            taskId = task.Id;

            await _flowEngine.Approve(task.Id, "S8 已开始处理（双线合一自动同意）");
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex,
                "S8 开始处理时自动同意 TB001 任务失败 exceptionId={Id} exceptionCode={Code} userId={UserId} assigneeId={Assignee} status={Status} instanceId={InstanceId} taskId={TaskId} err={Err}",
                e.Id, e.ExceptionCode, currentUserId, e.AssigneeUserId, e.Status, instanceId, taskId, ex.Message);
        }
    }

    public async Task<AdoS8Exception> UpgradeAsync(long id, long tenantId, string? remark)
    {
        var e = await LoadAsync(id, tenantId) ?? throw new S8BizException("异常不存在");

        if (e.ActiveFlowInstanceId.HasValue)
            throw new S8BizException("该异常已有进行中的审批流程，请等待审批完成");

        if (!S8StatusRules.IsAllowedTransition(e.Status, "ESCALATED"))
            throw new S8BizException($"状态 {e.Status} 不可升级");

        // S8-EXCEPTION-FLOW-TENANT-CONTEXT-1：UpgradeAsync 本身已持有可信 tenantId（人工点击=HTTP 走
        // S8TrustedScopeResolver；S8TimeoutAutoEscalationJob 自动升级=后台 Job 显式传参），统一走
        // 受信任重载，不依赖 _userManager.TenantId（后台 Job 场景下恒为 0）。
        await _flowEngine.StartFlow(new StartFlowInput
        {
            BizType = "EXCEPTION_ESCALATION",
            BizId = e.Id,
            Title = $"异常升级审批 - {e.ExceptionCode}",
            Comment = remark,
            BizData = new Dictionary<string, object>
            {
                ["severity"] = e.Severity,
                ["sceneCode"] = e.SceneCode,
                ["priorityLevel"] = e.PriorityLevel,
            }
        }, tenantId);

        // 状态和时间线由 ExceptionEscalationBizHandler.OnFlowStarted 回调更新
        return await LoadAsync(id, tenantId) ?? e;
    }

    public async Task<AdoS8Exception> RejectAsync(long id, long tenantId, string? remark)
    {
        var e = await LoadAsync(id, tenantId) ?? throw new S8BizException("异常不存在");
        if (!S8StatusRules.IsAllowedTransition(e.Status, "REJECTED"))
            throw new S8BizException($"状态 {e.Status} 不可驳回");

        var from = e.Status;
        e.Status = "REJECTED";
        e.UpdatedAt = DateTime.Now;

        await _rep.AsTenant().UseTranAsync(async () =>
        {
            await _rep.UpdateAsync(e);
            await InsertTimelineAsync(e.Id, "REJECT", "驳回", from, "REJECTED", null, null, remark);
        }, ex => throw ex);

        // 双线合一：S8 驳回 = TB001 流程整体拒绝（取消所有 pending 任务、Instance 终止）。
        await TryRejectIntakeOnRejectAsync(e, remark);

        return e;
    }

    private async Task TryRejectIntakeOnRejectAsync(AdoS8Exception e, string? remark)
    {
        var currentUserId = _userManager.UserId;
        long? instanceId = null, taskId = null;
        try
        {
            // S8-S1-EXCEPTION-FLOW-SYNC-FIX-1：实例/任务查询同样清数据范围过滤（ApprovalFlowInstance/Task 继承 EntityBaseOrg）。
            // 非超管用户在 DataScope=Self 时被「CreateUserId==当前用户」过滤、Dept/DeptChild 时被 OrgId 过滤，会查不到
            // 由他人（或系统）创建的 flow，双线合一静默失效。ClearFilter() 清全部数据范围过滤；BizType+BizId+assignee 已限定，
            // 无跨 BizType 误伤；ApprovalFlowInstance/Task 无软删与租户过滤。
            var instance = await _flowInstanceRep.AsQueryable()
                .ClearFilter()
                .Where(x => x.BizType == "EXCEPTION_REPORT"
                            && x.BizId == e.Id
                            && x.Status == FlowInstanceStatusEnum.Running)
                .FirstAsync();
            if (instance == null) return;
            instanceId = instance.Id;

            var task = await _flowTaskRep.AsQueryable()
                .ClearFilter()
                .Where(x => x.InstanceId == instance.Id
                            && x.AssigneeId == currentUserId
                            && x.Status == FlowTaskStatusEnum.Pending)
                .FirstAsync();
            if (task == null) return;
            taskId = task.Id;

            await _flowEngine.Reject(task.Id, remark ?? "S8 已驳回（双线合一自动拒绝）");
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex,
                "S8 驳回时自动拒绝 TB001 流程失败 exceptionId={Id} exceptionCode={Code} userId={UserId} assigneeId={Assignee} status={Status} instanceId={InstanceId} taskId={TaskId} err={Err}",
                e.Id, e.ExceptionCode, currentUserId, e.AssigneeUserId, e.Status, instanceId, taskId, ex.Message);
        }
    }

    public async Task<AdoS8Exception> SubmitVerificationAsync(
        long id, long tenantId,
        long verifierUserId, string? remark)
    {
        var currentUserId = GetCurrentUserId();
        var e = await LoadAsync(id, tenantId) ?? throw new S8BizException("异常不存在");
        EnsureCurrentUserIsOperator(e.AssigneeUserId, currentUserId, "只有当前处理人才能提交复检");
        var verifier = await _userScope.EnsureActiveUserAsync(tenantId, verifierUserId, "检验人");

        // S8-UAT-APPROVAL-REPAIR-1：检验人必须具备「审核」动作权限。
        //
        // 这不是新加一道门，而是把两条本来就该一致的链对齐：审批流的复核节点按
        // 「该租户被授予 s8:verification:approve 的角色」派发任务，而这里选出来的人
        // 要真的能点「检验通过 / 检验退回」。少了这条校验就会出现本地实测过的错位形态 ——
        // 页面上选了甲当检验人，审批任务却发给乙那一组，甲手里没有任务、乙又过不了
        // S8 自己的 verifier_user_id 校验，两边互相卡住且都不报错。
        var verifierAuth = await _actionAuthorizer.AuthorizeAsync(tenantId, verifier.UserId, S8ExceptionActionCode.Verify);
        if (!verifierAuth.Allowed)
            throw new S8BizException(
                $"{verifier.DisplayName} 没有审核权限，不能作为检验人。请在「异常操作权限」中为其角色授予「审核」，或改选其他账号。");
        if (!S8StatusRules.IsAllowedTransition(e.Status, "PENDING_VERIFICATION"))
            throw new S8BizException($"状态 {e.Status} 不可提交复检");

        var from = e.Status;
        e.Status = "PENDING_VERIFICATION";
        e.VerifierUserId = verifier.UserId;
        e.VerificationAssignedAt = DateTime.Now;
        e.UpdatedAt = DateTime.Now;

        await _rep.AsTenant().UseTranAsync(async () =>
        {
            await _rep.UpdateAsync(e);
            await InsertTimelineAsync(e.Id, "VERIFY_SUBMITTED", "提交复检", from, "PENDING_VERIFICATION",
                currentUserId, null, remark);
        }, ex => throw ex);

        // S8-NOTIFY-RECIPIENT-1：提交复核有真实业务入口（POST {id}/submit-verification），
        // 此前却没有任何通知 —— 检验人不会知道有单子在等他。这里补上，收件人由统一模型解析。
        await DispatchEventAsync(e, S8NotifyEventCode.VerificationSubmitted, "S8异常待你复核",
            $"{e.ExceptionCode} 已提交复核，等待检验。");

        // 双线合一：提交复检 = 启动 EXCEPTION_CLOSURE 流程，指派检验人。
        // 该流程定义复用，作为复检/关闭确认通用审批载体；handler 只做 ActiveFlowInstanceId 维护。
        await TryStartVerificationFlowAsync(e, verifier.UserId, remark);

        return await LoadAsync(id, tenantId) ?? e;
    }

    private async Task TryStartVerificationFlowAsync(AdoS8Exception e, long verifierUserId, string? remark)
    {
        try
        {
            await _flowEngine.StartFlow(new StartFlowInput
            {
                BizType = "EXCEPTION_CLOSURE",
                BizId = e.Id,
                BizNo = e.ExceptionCode,
                Title = $"异常复检 - {e.ExceptionCode}",
                Comment = remark,
                BizData = new Dictionary<string, object>
                {
                    ["sceneCode"] = e.SceneCode ?? string.Empty,
                    ["verifierUserId"] = verifierUserId,
                }
            });
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex,
                "S8 提交复检时启动 EXCEPTION_CLOSURE 流程失败 exceptionId={Id} verifierUserId={VerifierUserId}",
                e.Id, verifierUserId);
        }
    }

    public async Task<AdoS8Exception> ApproveVerificationAsync(
        long id, long tenantId,
        string? remark)
    {
        var currentUserId = GetCurrentUserId();
        var e = await LoadAsync(id, tenantId) ?? throw new S8BizException("异常不存在");
        EnsureCurrentUserIsOperator(e.VerifierUserId, currentUserId, "只有指定检验人才能检验通过");
        if (!S8StatusRules.IsAllowedTransition(e.Status, "CLOSED"))
            throw new S8BizException($"状态 {e.Status} 不可检验通过");

        var from = e.Status;
        e.Status = "CLOSED";
        e.VerifiedAt = DateTime.Now;
        e.VerificationResult = "APPROVED";
        e.VerificationRemark = remark;
        e.ClosedAt = DateTime.Now;
        e.UpdatedAt = DateTime.Now;

        await _rep.AsTenant().UseTranAsync(async () =>
        {
            await _rep.UpdateAsync(e);
            await InsertTimelineAsync(e.Id, "VERIFY_APPROVED", "检验通过", from, "CLOSED",
                currentUserId, null, remark);
        }, ex => throw ex);

        // 双线合一：检验通过 = EXCEPTION_CLOSURE 复检流程审批通过。
        await TryApproveVerificationFlowAsync(e.Id, currentUserId);

        // S8-R03-OVERDUE-CLOSE-NOTICE-1：闭环及时性提醒。
        // 触发条件：closedAt > slaDeadline；与 TimeoutFlag 运行时口径分离，仅对已关闭异常做闭环回顾。
        // 主流程已 commit（含状态机 + Timeline），异常隔离仅 LogWarning，不影响 CloseAsync。
        await TryDispatchOverdueCloseNotificationAsync(e);

        return e;
    }

    /// <summary>
    /// S8-R03-OVERDUE-CLOSE-NOTICE-1：异常关闭后若 closedAt &gt; slaDeadline 触发一条独立"超时关闭"通知。
    /// 复用 <see cref="S8NotificationLayerResolver.DispatchByLayerAsync"/> 分层链路，不写 ApprovalFlowNotifyLog。
    /// 与 <see cref="S8TimeoutAutoEscalationService"/>（未关闭超时升级）语义分离：本钩子仅在已关闭后回顾闭环及时性。
    /// 任何异常仅 LogWarning，不抛回 ApproveVerificationAsync 主流程。
    /// </summary>
    private async Task TryDispatchOverdueCloseNotificationAsync(AdoS8Exception e)
    {
        if (e == null || e.Id <= 0) return;
        if (e.ClosedAt == null || e.SlaDeadline == null) return;
        if (e.ClosedAt.Value <= e.SlaDeadline.Value) return;

        try
        {
            var overdueCloseHours = Math.Round(
                (decimal)(e.ClosedAt.Value - e.SlaDeadline.Value).TotalHours, 1);

            var sceneCode = string.IsNullOrWhiteSpace(e.SceneCode) ? "S8_DEMO_DEFAULT" : e.SceneCode;
            // S8-SEVERITY-FOLLOW-SERIOUS-STANDARDIZE-EXEC-1：派发前 Normalize 落 FOLLOW/SERIOUS。
            var severity = S8SeverityCode.Normalize(e.Severity);

            var content =
                $"异常 {e.ExceptionCode} 已关闭，但关闭时间超过 SLA 截止时间，超时关闭 {overdueCloseHours.ToString("0.#", System.Globalization.CultureInfo.InvariantCulture)} 小时，请关注闭环及时性。";

            await _notificationLayerResolver.DispatchByLayerAsync(new S8NotificationLayerResolver.DispatchByLayerInput
            {
                TenantId = e.TenantId,
                ExceptionId = e.Id,
                ExceptionNo = e.ExceptionCode,
                SceneCode = sceneCode,
                Severity = severity,
                EventCode = S8NotifyEventCode.ExceptionOverdueClosed,
                ExceptionRef = e,
                Title = $"【超时关闭】{e.ExceptionCode}",
                Content = content,
                Status = e.Status,
                SourceRuleCode = e.SourceRuleCode,
                JumpUrl = $"/aidop/s8/exceptions/{e.Id}",
                OverdueClosed = true,
                ClosedAt = e.ClosedAt,
                SlaDeadlineRef = e.SlaDeadline,
                OverdueCloseHours = overdueCloseHours,
            });
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "notify_overdue_close_dispatch_throw exceptionId={Id}", e.Id);
        }
    }

    private async Task TryApproveVerificationFlowAsync(long exceptionId, long currentUserId)
    {
        try
        {
            var instance = await _flowInstanceRep.AsQueryable()
                .Where(x => x.BizType == "EXCEPTION_CLOSURE"
                            && x.BizId == exceptionId
                            && x.Status == FlowInstanceStatusEnum.Running)
                .FirstAsync();
            if (instance == null) return;

            var task = await _flowTaskRep.AsQueryable()
                .Where(x => x.InstanceId == instance.Id
                            && x.AssigneeId == currentUserId
                            && x.Status == FlowTaskStatusEnum.Pending)
                .FirstAsync();
            if (task == null) return;

            await _flowEngine.Approve(task.Id, "S8 检验通过（双线合一自动同意）");
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex,
                "S8 检验通过时自动同意 EXCEPTION_CLOSURE 流程失败 exceptionId={Id} userId={UserId}",
                exceptionId, currentUserId);
        }
    }

    public async Task<AdoS8Exception> RejectVerificationAsync(
        long id, long tenantId,
        string remark)
    {
        var currentUserId = GetCurrentUserId();
        var e = await LoadAsync(id, tenantId) ?? throw new S8BizException("异常不存在");
        EnsureCurrentUserIsOperator(e.VerifierUserId, currentUserId, "只有指定检验人才能检验退回");
        if (!S8StatusRules.IsAllowedTransition(e.Status, "IN_PROGRESS"))
            throw new S8BizException($"状态 {e.Status} 不可检验退回");
        if (string.IsNullOrWhiteSpace(remark))
            throw new S8BizException("检验退回必须填写退回原因");

        var from = e.Status;
        e.Status = "IN_PROGRESS";
        e.VerifiedAt = DateTime.Now;
        e.VerificationResult = "REJECTED";
        e.VerificationRemark = remark;
        e.UpdatedAt = DateTime.Now;

        await _rep.AsTenant().UseTranAsync(async () =>
        {
            await _rep.UpdateAsync(e);
            await InsertTimelineAsync(e.Id, "VERIFY_REJECTED", "检验退回", from, "IN_PROGRESS",
                currentUserId, null, remark);
        }, ex => throw ex);

        // 双线合一：检验退回 = EXCEPTION_CLOSURE 复检流程整体拒绝。
        await TryRejectVerificationFlowAsync(e.Id, currentUserId, remark);

        return e;
    }

    private async Task TryRejectVerificationFlowAsync(long exceptionId, long currentUserId, string? remark)
    {
        try
        {
            var instance = await _flowInstanceRep.AsQueryable()
                .Where(x => x.BizType == "EXCEPTION_CLOSURE"
                            && x.BizId == exceptionId
                            && x.Status == FlowInstanceStatusEnum.Running)
                .FirstAsync();
            if (instance == null) return;

            var task = await _flowTaskRep.AsQueryable()
                .Where(x => x.InstanceId == instance.Id
                            && x.AssigneeId == currentUserId
                            && x.Status == FlowTaskStatusEnum.Pending)
                .FirstAsync();
            if (task == null) return;

            await _flowEngine.Reject(task.Id, remark ?? "S8 检验退回（双线合一自动拒绝）");
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex,
                "S8 检验退回时自动拒绝 EXCEPTION_CLOSURE 流程失败 exceptionId={Id} userId={UserId}",
                exceptionId, currentUserId);
        }
    }

    // S8-TENANT-FACTORY-P0-CLOSURE-1：补充说明同样按可信作用域绑行，禁止裸 Id 写他租户时间线。
    public async Task CommentAsync(long id, long tenantId, string? remark)
    {
        var e = await LoadAsync(id, tenantId)
            ?? throw new S8BizException("异常不存在");
        await InsertTimelineAsync(e.Id, "COMMENT", "补充说明", e.Status, e.Status, null, null, remark);
    }

    private Task<AdoS8Exception?> LoadAsync(long id, long tenantId) =>
        _rep.GetFirstAsync(x => x.Id == id && x.TenantId == tenantId && !x.IsDeleted);

    // 统一复用框架登录上下文，避免业务身份继续信任前端传参。
    private long GetCurrentUserId()
    {
        var currentUserId = _userManager.UserId;
        if (currentUserId <= 0)
            throw new S8BizException("未获取到当前登录用户");

        return currentUserId;
    }

    /// <summary>
    /// S8-NOTIFY-RECIPIENT-1：按事件派发通知，收件人由统一模型解析。
    ///
    /// <para>取代原来的 <c>NotifyUserAsync(exception, sysUserId, title)</c> —— 那是把
    /// 「通知谁」写死在代码里：认领通知处理人本人、转派通知新处理人，管理员无从更改，
    /// 也无法让别人（比如责任池里的其他人）同时知道。现在这两件事都由
    /// <see cref="S8NotificationLayerResolver"/> 走同一条收件人链路，
    /// 与规则建单 / 升级 / 恢复的通知共用一套配置。</para>
    ///
    /// <para>通知失败<b>不阻断业务动作</b>：认领已经成功落库，不能因为发不出消息就回滚。
    /// 但失败必须落日志 —— 静默吞掉会让"通知没收到"变成无从查起的问题。</para>
    /// </summary>
    private async Task DispatchEventAsync(AdoS8Exception exception, string eventCode, string title, string content)
    {
        try
        {
            await _notificationLayerResolver.DispatchByLayerAsync(new S8NotificationLayerResolver.DispatchByLayerInput
            {
                TenantId = exception.TenantId,
                ExceptionId = exception.Id,
                ExceptionNo = exception.ExceptionCode,
                SceneCode = string.IsNullOrWhiteSpace(exception.SceneCode) ? "S8_DEMO_DEFAULT" : exception.SceneCode,
                Severity = S8SeverityCode.Normalize(exception.Severity),
                EventCode = eventCode,
                ExceptionRef = exception,
                Title = title,
                Content = content,
                Status = exception.Status,
                SourceRuleCode = exception.SourceRuleCode,
                JumpUrl = $"/aidop/s8/exceptions/{exception.Id}",
            });
        }
        catch (Exception ex)
        {
            _logger.LogWarning(ex, "s8_notify_dispatch_failed exceptionId={Id} event={Event}", exception.Id, eventCode);
        }
    }

    /// <summary>
    /// 鉴权：当前登录账号必须就是单据上记录的那个人。
    ///
    /// <para>S8-SYSUSER-ONLY-1：原实现要先把 <c>employeeId</c> 经 <c>EmployeeMaster.SysUserId</c>
    /// 解析成账号再比对，于是"未绑定员工主数据"和"你不是这个人"共用同一句报错 ——
    /// 两种完全不同的问题给出同一个提示。现在两边同为 <c>SysUser.Id</c>，直接比较即可，
    /// 不需要查库，也不再有第三种失败模式。</para>
    /// </summary>
    private static void EnsureCurrentUserIsOperator(long? ownerUserId, long currentUserId, string failMessage)
    {
        if (ownerUserId != currentUserId)
            throw new S8BizException(failMessage);
    }

    /// <summary>
    /// 写时间线。<paramref name="operatorUserId"/> <b>只接受 <c>SysUser.Id</c></b>；
    /// 系统自动动作传 null，<b>绝不允许伪造一个 ID</b>（历史上 CLAIM 传的是 EmployeeMaster.RecID，
    /// 导致同一列混装两套 ID 空间，见 <see cref="AdoS8ExceptionTimeline.OperatorUserId"/>）。
    /// </summary>
    private async Task InsertTimelineAsync(long exceptionId, string code, string label, string? from, string? to,
        long? operatorUserId, string? operatorName, string? remark) =>
        await _timelineRep.InsertAsync(new AdoS8ExceptionTimeline
        {
            ExceptionId = exceptionId,
            ActionCode = code,
            ActionLabel = label,
            FromStatus = from,
            ToStatus = to,
            OperatorUserId = operatorUserId,
            OperatorName = operatorName,
            ActionRemark = remark,
            CreatedAt = DateTime.Now
        });
}