AiDOPWarehouse/server/Plugins/Admin.NET.Plugin.AiDOP/Const/S8/S8NotificationCatalog.cs

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

/// <summary>
/// S8-NOTIFY-RECIPIENT-1：通知事件码。
///
/// <para><b>每一条都对应一个真实存在的派发点</b>（见 <c>TriggerHint</c>）。
/// 刻意不造没有业务入口的事件 —— 配了却永远不触发的通知，比没有通知更难排查。</para>
/// </summary>
public static class S8NotifyEventCode
{
    /// <summary>规则命中建单 / 人工提报建单。</summary>
    public const string ExceptionCreated = "EXCEPTION_CREATED";

    /// <summary>被认领。</summary>
    public const string ExceptionClaimed = "EXCEPTION_CLAIMED";

    /// <summary>被转派。</summary>
    public const string ExceptionTransferred = "EXCEPTION_TRANSFERRED";

    /// <summary>提交复核（等待审核）。</summary>
    public const string VerificationSubmitted = "VERIFICATION_SUBMITTED";

    /// <summary>超时自动升级。</summary>
    public const string EscalationTriggered = "ESCALATION_TRIGGERED";

    /// <summary>检测到恢复。</summary>
    public const string ExceptionRecovered = "EXCEPTION_RECOVERED";

    /// <summary>超时关闭（闭环及时性回顾）。</summary>
    public const string ExceptionOverdueClosed = "EXCEPTION_OVERDUE_CLOSED";
}

/// <summary>
/// 收件人类型。<b>第一版只有四类，全部能真实解析出 SysUserId</b>。
///
/// <para><b>Supervisor 刻意缺席</b>：系统里不存在组织主管关系
/// （<c>SysOrg.DirectorId</c> 与 <c>SysUser.ManagerUserId</c> 实测填充率均为 0）。
/// 给一个永远解析为空的选项，等于让管理员配一条永远发不出去的通知。</para>
/// </summary>
public static class S8RecipientType
{
    /// <summary>该规则的处理账号池（复用 P1-C 的 Rule Handler Pool，不复制第二份人员配置）。</summary>
    public const string HandlerPool = "HANDLER_POOL";

    /// <summary>当前处理人（<c>assignee_user_id</c>）。</summary>
    public const string Assignee = "ASSIGNEE";

    /// <summary>
    /// 当前实际审核人。
    /// <para><b>不是新建的 Reviewer Pool</b> —— 它解析的是<b>当前事实</b>：
    /// 优先取单据上的 <c>verifier_user_id</c>（提交复核时手选、真正能点通过/退回的人）；
    /// 尚未提交复核时回落到审批流节点解析出的审批人。</para>
    /// </summary>
    public const string Reviewer = "REVIEWER";

    /// <summary>
    /// 该规则的<b>升级账号池</b>（S8-RESPONSIBILITY-POOL-1）。
    /// <para>取代 <c>exception_type.escalate_role_code</c> 成为升级通知的收件来源：
    /// 旧字段按异常类型跨租户查，实测会把 B 租户的配置用到 A 租户的异常上。</para>
    /// </summary>
    public const string EscalationPool = "ESCALATION_POOL";

    /// <summary>指定账号（多选 SysUser）。</summary>
    public const string SpecificUser = "SPECIFIC_USER";
}

/// <summary>
/// 事件元信息。
/// <para><b><paramref name="TriggerHint"/> 是给业务用户看的「什么时候会发生」</b>，
/// 不是给开发看的派发点标注 —— 通知设置页会直接展示它。
/// 原先几个事件写的是 <c>POST {id}/claim</c> 这样的接口路径，
/// 与「业务用户不需要理解技术实现」相悖。</para>
/// </summary>
public sealed record S8NotifyEventDefinition(string Code, string DisplayName, string TriggerHint, int OrderNo);

/// <summary>
/// 事件与收件人类型目录。后端派发、配置校验、前端 UI 三方共用同一份，
/// 避免出现「页面能配、后端根本不派发」或反之。
/// </summary>
public static class S8NotificationCatalog
{
    public static readonly IReadOnlyList<S8NotifyEventDefinition> Events = new List<S8NotifyEventDefinition>
    {
        new(S8NotifyEventCode.ExceptionCreated, "异常产生", "规则命中建单 / 人工提报", 10),
        new(S8NotifyEventCode.ExceptionClaimed, "认领成功", "处理人认领异常时", 20),
        new(S8NotifyEventCode.ExceptionTransferred, "转派", "异常被转派给其他处理人时", 30),
        new(S8NotifyEventCode.VerificationSubmitted, "提交复核", "处理人提交复核时", 40),
        new(S8NotifyEventCode.EscalationTriggered, "超时升级", "超时自动升级作业", 50),
        new(S8NotifyEventCode.ExceptionRecovered, "异常恢复", "调度器检测到恢复", 60),
        new(S8NotifyEventCode.ExceptionOverdueClosed, "超时关闭", "检验通过后闭环及时性回顾", 70),
    };

    public static readonly IReadOnlyList<string> RecipientTypes = new[]
    {
        S8RecipientType.HandlerPool,
        S8RecipientType.Assignee,
        S8RecipientType.Reviewer,
        S8RecipientType.EscalationPool,
        S8RecipientType.SpecificUser,
    };

    /// <summary>
    /// S8-RESPONSIBILITY-POOL-1：事件 → 收件人的<b>默认推导</b>。
    ///
    /// <para><b>为什么是推导而不是让人配</b>：规则已经知道处理池、复核池、升级池、
    /// 当前处理人、选定复核人是谁。再让业务用户去选 <c>HANDLER_POOL</c> / <c>ASSIGNEE</c>
    /// 这类技术枚举，等于把内部实现搬到页面上，还多出一处会与责任池不一致的配置。
    /// 业务用户只需要回答「这件事要不要提醒」，对象由责任关系自动决定。</para>
    ///
    /// <para><b>每一条都对应真实派发点</b>：<c>EXCEPTION_CREATED</c>（调度器建单）·
    /// <c>EXCEPTION_CLAIMED</c> / <c>EXCEPTION_TRANSFERRED</c> / <c>VERIFICATION_SUBMITTED</c>
    /// （<c>S8TaskFlowService</c>）· <c>ESCALATION_TRIGGERED</c>（超时升级作业）·
    /// <c>EXCEPTION_RECOVERED</c>（调度器判定恢复）· <c>EXCEPTION_OVERDUE_CLOSED</c>（闭环及时性回顾）。
    /// <b>「复核通过」「复核退回」刻意缺席</b>：代码里没有这两个派发点，
    /// 凭空加进目录只会配出永远不触发的通知 —— 比没有通知更难排查。</para>
    ///
    /// <para><b>转派通知的对象是「新处理人」</b>：转派完成时 <c>assignee_user_id</c>
    /// 已经是新的人，因此 <c>ASSIGNEE</c> 解析出来的就是他，不需要额外的收件人类型。</para>
    /// </summary>
    public static readonly IReadOnlyDictionary<string, string> DefaultRecipientByEvent =
        new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
        {
            [S8NotifyEventCode.ExceptionCreated] = S8RecipientType.HandlerPool,
            [S8NotifyEventCode.ExceptionClaimed] = S8RecipientType.Assignee,
            [S8NotifyEventCode.ExceptionTransferred] = S8RecipientType.Assignee,
            [S8NotifyEventCode.VerificationSubmitted] = S8RecipientType.Reviewer,
            [S8NotifyEventCode.EscalationTriggered] = S8RecipientType.EscalationPool,
            [S8NotifyEventCode.ExceptionRecovered] = S8RecipientType.Assignee,
            [S8NotifyEventCode.ExceptionOverdueClosed] = S8RecipientType.Assignee,
        };

    /// <summary>事件的默认收件人类型；未知事件返回 <c>null</c>（调用方不得猜）。</summary>
    public static string? ResolveDefaultRecipientType(string? eventCode) =>
        !string.IsNullOrWhiteSpace(eventCode)
        && DefaultRecipientByEvent.TryGetValue(eventCode!, out var t) ? t : null;

    /// <summary>收件人类型的业务文案（页面只读展示，不出现技术枚举）。</summary>
    public static string DescribeRecipientType(string? type) => type switch
    {
        S8RecipientType.HandlerPool => "处理人员",
        S8RecipientType.Assignee => "当前处理人",
        S8RecipientType.Reviewer => "当前复核人",
        S8RecipientType.EscalationPool => "升级人员",
        S8RecipientType.SpecificUser => "指定账号",
        _ => "未配置",
    };

    /// <summary>
    /// 租户级默认配置的 <c>rule_code</c> 哨兵值。
    /// <para>人工提报的异常没有来源规则，它的通知只能落在租户级默认上。
    /// 用显式常量而不是 NULL：NULL 在唯一索引里的比较语义容易让人配出两条"默认"。</para>
    /// </summary>
    public const string TenantDefaultRuleCode = "*";

    private static readonly HashSet<string> EventSet =
        Events.Select(e => e.Code).ToHashSet(StringComparer.OrdinalIgnoreCase);
    private static readonly HashSet<string> TypeSet =
        RecipientTypes.ToHashSet(StringComparer.OrdinalIgnoreCase);

    public static bool IsKnownEvent(string? code) => !string.IsNullOrWhiteSpace(code) && EventSet.Contains(code!);
    public static bool IsKnownRecipientType(string? t) => !string.IsNullOrWhiteSpace(t) && TypeSet.Contains(t!);
}