paiban/NPP.SmartSchedue.Api.Contracts/Services/Notification/INotificationService.cs

using System;
using System.Threading.Tasks;
using System.Collections.Generic;
using ZhonTai.Admin.Core.Dto;
using NPP.SmartSchedue.Api.Contracts.Services.Notification.Input;
using NPP.SmartSchedue.Api.Contracts.Services.Notification.Output;
using NPP.SmartSchedue.Api.Contracts.Core.Enums;

namespace NPP.SmartSchedue.Api.Contracts.Services.Notification;

/// <summary>
/// 通知服务接口
/// 决策点6：定时任务，支持定时检查和触发通知
/// 决策点7：模板通知，支持通知内容模板，可替换变量
/// </summary>
public interface INotificationService
{
    #region 通知设置管理
    
    /// <summary>
    /// 查询通知设置
    /// </summary>
    /// <param name="id"></param>
    /// <returns></returns>
    Task<NotificationSettingOutput> GetNotificationSettingAsync(long id);

    /// <summary>
    /// 查询通知设置分页
    /// </summary>
    /// <param name="input"></param>
    /// <returns></returns>
    Task<PageOutput<NotificationSettingOutput>> GetNotificationSettingPageAsync(PageInput<NotificationSettingPageInput> input);

    /// <summary>
    /// 获取通知设置列表（可选过滤，含缓存）
    /// </summary>
    /// <param name="isEnabled">是否启用（可选）</param>
    /// <param name="personnelGroupId">人员组ID（可选）</param>
    /// <returns></returns>
    Task<List<NotificationSettingOutput>> GetNotificationSettingListAsync(bool? isEnabled = null, long? personnelGroupId = null);

    /// <summary>
    /// 创建通知设置
    /// </summary>
    /// <param name="input"></param>
    /// <returns></returns>
    Task<long> CreateNotificationSettingAsync(NotificationSettingCreateInput input);

    /// <summary>
    /// 更新通知设置
    /// </summary>
    /// <param name="input"></param>
    /// <returns></returns>
    Task UpdateNotificationSettingAsync(NotificationSettingUpdateInput input);

    /// <summary>
    /// 删除通知设置
    /// </summary>
    /// <param name="id"></param>
    /// <returns></returns>
    Task DeleteNotificationSettingAsync(long id);

    /// <summary>
    /// 启用/禁用通知设置
    /// </summary>
    /// <param name="id"></param>
    /// <param name="enabled"></param>
    /// <returns></returns>
    Task ToggleNotificationSettingAsync(long id, bool enabled);

    #endregion

    #region 人员组管理
    
    /// <summary>
    /// 查询人员组
    /// </summary>
    /// <param name="id"></param>
    /// <returns></returns>
    Task<PersonnelGroupOutput> GetPersonnelGroupAsync(long id);

    /// <summary>
    /// 查询人员组分页
    /// </summary>
    /// <param name="input"></param>
    /// <returns></returns>
    Task<PageOutput<PersonnelGroupOutput>> GetPersonnelGroupPageAsync(PageInput<PersonnelGroupGetPageInput> input);

    /// <summary>
    /// 创建人员组
    /// </summary>
    /// <param name="input"></param>
    /// <returns></returns>
    Task<long> CreatePersonnelGroupAsync(PersonnelGroupCreateInput input);

    /// <summary>
    /// 更新人员组
    /// </summary>
    /// <param name="input"></param>
    /// <returns></returns>
    Task UpdatePersonnelGroupAsync(PersonnelGroupUpdateInput input);

    /// <summary>
    /// 删除人员组
    /// </summary>
    /// <param name="id"></param>
    /// <returns></returns>
    Task DeletePersonnelGroupAsync(long id);

    /// <summary>
    /// 获取人员组的实际人员列表
    /// 根据决策点4：混合人员组，支持静态+动态规则
    /// </summary>
    /// <param name="personnelGroupId"></param>
    /// <returns></returns>
    Task<List<long>> GetPersonnelGroupMembersAsync(long personnelGroupId);

    #endregion

    #region 通知发送
    
    /// <summary>
    /// 发送通知
    /// 决策点1：支持邮件和系统消息通知
    /// </summary>
    /// <param name="input"></param>
    /// <returns></returns>
    Task<SendNotificationOutput> SendNotificationAsync(SendNotificationInput input);

    /// <summary>
    /// 发送群组通知（邮件发送一封给所有人，系统消息仍然单独发送）
    /// </summary>
    /// <param name="input"></param>
    /// <returns></returns>
    Task<SendNotificationOutput> SendGroupNotificationAsync(SendNotificationInput input);

    /// <summary>
    /// 批量发送通知
    /// </summary>
    /// <param name="inputs"></param>
    /// <returns></returns>
    Task<List<SendNotificationOutput>> BatchSendNotificationAsync(List<SendNotificationInput> inputs);

    /// <summary>
    /// 根据通知设置发送通知
    /// </summary>
    /// <param name="notificationSettingId">通知设置ID</param>
    /// <param name="businessType">业务类型</param>
    /// <param name="businessId">业务ID</param>
    /// <param name="businessData">业务数据</param>
    /// <param name="templateVariables">模板变量（用于替换模板中的占位符）</param>
    /// <returns></returns>
    Task<SendNotificationOutput> SendNotificationBySettingAsync(
        long notificationSettingId,
        string businessType,
        long? businessId = null,
        string businessData = "",
        Dictionary<string, string> templateVariables = null);

    #endregion

    #region 通知模板引擎（决策点7）
    
    /// <summary>
    /// 验证模板语法
    /// </summary>
    /// <param name="template">模板内容</param>
    /// <returns></returns>
    Task<bool> ValidateTemplateAsync(string template);

    #endregion

    #region 通知历史记录（决策点8）
    
    /// <summary>
    /// 查询通知历史记录
    /// </summary>
    /// <param name="id"></param>
    /// <returns></returns>
    Task<NotificationHistoryOutput> GetNotificationHistoryAsync(long id);

    /// <summary>
    /// 查询通知历史记录分页
    /// </summary>
    /// <param name="input"></param>
    /// <returns></returns>
    Task<PageOutput<NotificationHistoryOutput>> GetNotificationHistoryPageAsync(PageInput<NotificationHistoryPageInput> input);

    /// <summary>
    /// 重试失败的通知
    /// </summary>
    /// <param name="notificationHistoryId"></param>
    /// <returns></returns>
    Task<bool> RetryFailedNotificationAsync(long notificationHistoryId);

    /// <summary>
    /// 批量重试失败的通知
    /// </summary>
    /// <param name="notificationHistoryIds"></param>
    /// <returns></returns>
    Task<int> BatchRetryFailedNotificationsAsync(List<long> notificationHistoryIds);

    /// <summary>
    /// 取消通知
    /// </summary>
    /// <param name="notificationHistoryId">通知历史记录ID</param>
    /// <returns></returns>
    Task<bool> CancelNotificationAsync(long notificationHistoryId);

    /// <summary>
    /// 批量取消通知
    /// </summary>
    /// <param name="notificationHistoryIds">通知历史记录ID列表</param>
    /// <returns>成功取消的数量</returns>
    Task<int> BatchCancelNotificationsAsync(List<long> notificationHistoryIds);

    #endregion

    #region 定时任务管理（决策点6）
    
    /// <summary>
    /// 创建定时通知任务
    /// </summary>
    /// <param name="notificationSettingId">通知设置ID</param>
    /// <param name="businessType">业务类型</param>
    /// <param name="businessId">业务ID</param>
    /// <param name="businessData">业务数据</param>
    /// <param name="plannedExecutionTime">计划执行时间</param>
    /// <param name="cronExpression">Cron表达式（可选）</param>
    /// <returns></returns>
    Task<long> CreateScheduledNotificationTaskAsync(
        long notificationSettingId,
        string businessType,
        long? businessId = null,
        string businessData = "",
        DateTime? plannedExecutionTime = null,
        string cronExpression = "");

    /// <summary>
    /// 执行定时通知任务
    /// </summary>
    /// <param name="taskId">任务ID</param>
    /// <returns></returns>
    Task<bool> ExecuteScheduledNotificationTaskAsync(long taskId);

    /// <summary>
    /// 获取待执行的定时任务列表
    /// </summary>
    /// <returns></returns>
    Task<List<long>> GetPendingNotificationTasksAsync();

    /// <summary>
    /// 启用/禁用定时任务
    /// </summary>
    /// <param name="taskId"></param>
    /// <param name="enabled"></param>
    /// <returns></returns>
    Task ToggleNotificationTaskAsync(long taskId, bool enabled);

    #endregion

    #region 通知统计
    
    /// <summary>
    /// 获取通知发送统计信息
    /// </summary>
    /// <param name="startTime">开始时间</param>
    /// <param name="endTime">结束时间</param>
    /// <param name="notificationSettingId">通知设置ID（可选）</param>
    /// <returns></returns>
    Task<Dictionary<string, object>> GetNotificationStatisticsAsync(
        DateTime startTime,
        DateTime endTime,
        long? notificationSettingId = null);

    #endregion
}