Display_D_HP/TeamAAS-VM/Interfaces/ISystemDatabaseService.cs

/* 伪代码计划（详细步骤）：
   1. 在文件顶部以注释形式写明生成注释的目的与范围（中文说明）。
   2. 为接口 ISystemDatabaseService 添加完整的 XML 文档注释：
      - 在接口声明上添加总体描述（接口职责、线程/异步约定、与数据库交互的总体行为描述）。
      - 为每个方法添加 <summary>，<param>，<returns>（如适用）和 <remarks>（必要时）。
      - 对于带有可为空参数的方法（如 ResetProductionAsync、GetTotalProductionAsync），在 <param> 中说明 null 的语义。
      - 对于返回集合的方法，说明集合可能为空或包含元素。
      - 对于认证方法，说明失败时返回 null 或抛出异常的约定（与现有签名保持一致）。
   3. 保持原有 using 和 namespace 不变，确保注释符合 C# XML 注释格式并使用中文表述。
   4. 保证代码风格和缩进与项目一致（4 空格缩进），使用 C# 注释约定 (///)。
*/

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using TeamAAS_VP.Models;

namespace TeamAAS_VP.Interfaces
{
    /// <summary>
    /// 提供与系统数据库交互的抽象服务接口。
    /// 包含用户管理、用户认证与产能（生产）记录的增删改查与统计方法。
    /// 所有方法均为异步方法以支持非阻塞 IO 操作。
    /// </summary>
    public interface ISystemDatabaseService
    {
        // User CRUD

        /// <summary>
        /// 将新的用户记录添加到数据库中。
        /// </summary>
        /// <param name="user">要添加的用户对象。应包含必要的字段（例如用户名、密码摘要等）。</param>
        /// <returns>
        /// 一个包含已保存用户信息的 <see cref="User"/> 实例（通常带有数据库生成的 Id）。
        /// </returns>
        /// <remarks>
        /// 实现者应负责对重复用户名或验证失败的情况进行处理（例如抛出异常或按项目约定返回特定结果）。
        /// </remarks>
        Task<User> AddUserAsync(User user);

        /// <summary>
        /// 更新现有用户的数据库记录。
        /// </summary>
        /// <param name="user">包含更新后信息的用户对象，必须包含有效的用户 Id。</param>
        /// <returns>更新后的 <see cref="User"/> 对象。</returns>
        /// <remarks>如果指定用户不存在，实现可以抛出异常或按约定返回 null。</remarks>
        Task<User> UpdateUserAsync(User user);

        /// <summary>
        /// 删除指定 Id 的用户记录。
        /// </summary>
        /// <param name="userId">要删除的用户的数据库 Id。</param>
        /// <returns>若删除成功返回 true；如果用户不存在或删除失败返回 false。</returns>
        Task<bool> DeleteUserAsync(int userId);

        /// <summary>
        /// 根据用户 Id 获取用户信息。
        /// </summary>
        /// <param name="userId">要查询的用户 Id。</param>
        /// <returns>找到则返回对应的 <see cref="User"/> 对象；不存在时返回 null。</returns>
        Task<User> GetUserByIdAsync(int userId);

        /// <summary>
        /// 获取系统中所有用户的集合。
        /// </summary>
        /// <returns>
        /// 一个用户集合；如果没有用户，返回的集合可为空或为空集合，具体由实现决定（建议返回空集合而非 null）。
        /// </returns>
        Task<IEnumerable<User>> GetAllUsersAsync();

        // User authentication

        /// <summary>
        /// 使用用户名和密码（或密码摘要）对用户进行认证。
        /// </summary>
        /// <param name="username">要认证的用户名。</param>
        /// <param name="password">用于认证的密码或密码摘要。</param>
        /// <returns>
        /// 认证成功时返回对应的 <see cref="User"/> 对象（可包含用户的身份信息或权限）；认证失败时返回 null。
        /// </returns>
        /// <remarks>实现者应确保密码比较使用安全方式（例如散列和抗时序攻击的比较）。</remarks>
        Task<User> AuthenticateUserAsync(string username, string password);

        // Remember user helpers

        /// <summary>
        /// 将指定用户名标记为“记住”，并取消其他用户的记住标志。
        /// </summary>
        /// <param name="username">要记住的用户名。</param>
        /// <returns>完成记住用户操作的任务。</returns>
        /// <remarks>
        /// 实现者应负责确保此操作的原子性与一致性。
        /// </remarks>
        Task SetRememberUserAsync(string username);

        /// <summary>
        /// 清除所有用户的“记住”标志。
        /// </summary>
        /// <returns>完成清除操作的任务。</returns>
        /// <remarks>
        /// 实现者应负责确保此操作不会影响当前在线用户的会话。
        /// </remarks>
        Task ClearRememberUserAsync();

        /// <summary>
        /// 获取当前被标记为记住的用户（如果存在）。
        /// </summary>
        /// <returns>被记住的用户或 null。</returns>
        /// <remarks>
        /// 实现者应确保此方法高效执行并尽量减少资源消耗。
        /// </remarks>
        Task<User> GetRememberedUserAsync();

        // Current user / session helpers

        /// <summary>
        /// 将指定用户设为当前用户（会写入一条登录记录，标记为成功）
        /// </summary>
        /// <param name="userId">要设为当前用户的用户 Id。</param>
        /// <returns>完成设为当前用户操作的任务。</returns>
        /// <remarks>
        /// 实现者应确保此操作为线程安全，并正确处理可能的并发访问。
        /// </remarks>
        Task SetCurrentUserAsync(int userId);

        /// <summary>
        /// 将指定用户设为当前用户（会写入一条登录记录，标记为成功）
        /// </summary>
        /// <param name="user"></param>
        /// <returns></returns>
        Task SetCurrentUserAsync(User user);

        /// <summary>
        /// 获取当前（最近一次成功登录的）用户。
        /// </summary>
        /// <returns>返回最近一次成功登录的 <see cref="User"/>，找不到则返回 null。</returns>
        Task<User> GetCurrentUserAsync();

        /// <summary>
        /// 获取当前用户
        /// </summary>
        /// <returns></returns>
        User GetCurrentUser();

        /// <summary>
        /// 记录一条用户登录记录（成功或失败）。
        /// </summary>
        /// <param name="record">登录记录对象，不能为空。</param>
        /// <returns>完成记录登录操作的任务。</returns>
        /// <remarks>
        /// 实现者应负责确保记录的持久化，并处理可能的异常情况。
        /// </remarks>
        Task RecordUserLoginAsync(UserLoginRecord record);

        /// <summary>
        /// 获取指定用户最近的一条登录记录（如果有）。
        /// </summary>
        /// <param name="userId">用户 Id。</param>
        /// <returns>最近的一条 <see cref="UserLoginRecord"/> 或 null。</returns>
        /// <remarks>
        /// 如果用户没有登录记录，返回 null 而非抛出异常。
        /// </remarks>
        Task<UserLoginRecord> GetLastUserLoginRecordAsync(int userId);

        // Production records

        //生产计数更改事件

        /// <summary>
        /// 将一条生产记录写入数据库。
        /// </summary>
        /// <param name="record">要记录的 <see cref="ProductionRecord"/> 实例，包含产品名、分类、数量和时间等信息。</param>
        /// <returns>完成写入操作的任务。</returns>
        Task RecordProductionAsync(ProductionRecord record);

        /// <summary>
        /// 清除产能计数。
        /// </summary>
        /// <param name="productName">
        /// 要清除计数的产品名称。传入 null 表示清除所有产品的计数。
        /// </param>
        /// <returns>完成清除操作的任务。</returns>
        Task ResetProductionAsync(string productName = null);

        /// <summary>
        /// 获取指定产品在可选分类集合下的总产能（对 Quantity 求和）。
        /// </summary>
        /// <param name="productName">要统计的产品名称，不能为空或空字符串。</param>
        /// <param name="categories">
        /// 可选的分类集合；如果传入 null 或为空集合，则统计所有分类。
        /// </param>
        /// <returns>指定条件下的总产能数量（int）。</returns>
        Task<int> GetTotalProductionAsync(string productName, IEnumerable<string> categories = null);

        /// <summary>
        /// 按指定粒度获取产能统计结果。
        /// </summary>
        /// <param name="query">包含时间范围、分组粒度（例如按天/按周/按月）、产品名称和分类过滤等条件的查询对象。</param>
        /// <returns>
        /// 满足查询条件的分组统计结果集合，每项为 <see cref="ProductionStatResult"/>。
        /// 如果没有匹配项，可以返回空集合（建议不返回 null）。
        /// </returns>
        Task<IEnumerable<ProductionStatResult>> GetProductionStatsAsync(ProductionStatQuery query);

        /// <summary>
        /// 获取所有已知分类相加起来的今天的产能
        /// </summary>
        /// <param name="productName"></param>
        /// <returns></returns>
        Task<int> GetTodayProductionAsync(string productName);

        /// <summary>
        /// 获取所有已知分类相加起来的当前时间往前的一个小时的产能
        /// </summary>
        /// <param name="productName"></param>
        /// <returns></returns>
        Task<int> GetLastHourProductionAsync(string productName);

        /// <summary>
        /// 获取当前月的产能
        /// </summary>
        /// <param name="productName"></param>
        /// <returns></returns>
        Task<int> GetCurrentMonthProductionAsync(string productName);

        /// <summary>
        /// 获取当前周的产能
        /// </summary>
        /// <param name="productName"></param>
        /// <returns></returns>
        Task<int> GetCurrentWeekProductionAsync(string productName);

        /// <summary>
        /// 获取指定产品名称的总产能
        /// </summary>
        /// <param name="productName"></param>
        /// <returns></returns>
        Task<int> GetOverallProductionAsync(string productName);

        /// <summary>
        /// 获取指定产品的所有已知分类。
        /// </summary>
        /// <param name="productName">要查询分类的产品名称。</param>
        /// <returns>
        /// 一个字符串集合，包含该产品的所有分类名称；如果没有分类，返回空集合或 null（建议返回空集合）。
        /// </returns>
        Task<IEnumerable<string>> GetProductCategoriesAsync(string productName);

        /// <summary>
        /// 获取指定产品名称的所有记录按照分类的产能统计
        /// </summary>
        /// <param name="productName"></param>
        /// <returns></returns>
        Task<Dictionary<string, int>> GetProductionByCategoriesAsync(string productName);

        /// <summary>
        /// 获取指定产品名称的一个月内按照每天统计对应的类别和数量
        /// </summary>
        /// <param name="productName"></param>
        /// <returns></returns>
        Task<Dictionary<DateTime, Dictionary<string, int>>> GetMonthlyProductionByDayAndCategoryAsync(string productName);

        /// <summary>
        /// 获取指定产品名称的一个星期内按照每天统计对应的类别和数量
        /// </summary>
        /// <param name="productName"></param>
        /// <returns></returns>
        Task<Dictionary<int, Dictionary<string, int>>> GetWeeklyProductionByDayAndCategoryAsync(string productName);

        /// <summary>
        /// 获取指定产品名称的当天内按照每小时统计对应的类别和数量
        /// </summary>
        /// <param name="productName"></param>
        /// <returns></returns>
        Task<Dictionary<int, Dictionary<string, int>>> GetDailyProductionByHourAndCategoryAsync(string productName);


        // Alarm records

        /// <summary>
        /// 将一条报警记录写入数据库。
        /// </summary>
        /// <param name="alarm">要记录的 <see cref="AlarmRecord"/> 对象。</param>
        /// <returns>完成写入操作的任务。</returns>
        Task RecordAlarmAsync(Models.AlarmRecord alarm);

        /// <summary>
        /// 查询报警记录，按时间范围和可选的编号或来源过滤。
        /// </summary>
        /// <param name="start">起始时间（含）。</param>
        /// <param name="end">结束时间（不含）。</param>
        /// <param name="code">可选的报警编号过滤，传入 null 表示不过滤。</param>
        /// <param name="source">可选的报警来源过滤，传入 null 表示不过滤。</param>
        /// <returns>满足条件的报警记录集合。</returns>
        Task<IEnumerable<Models.AlarmRecord>> QueryAlarmsAsync(DateTime start, DateTime end, string code = null, string source = null);

        // Lock results

        /// <summary>
        /// 记录单次锁付结果（波形数据 WaveDatas 不存入数据库）
        /// </summary>
        /// <param name="result">要存储的 LockResult 对象</param>
        Task RecordLockResultAsync(LockResult result);

        /// <summary>
        /// 分页查询锁付结果。
        /// 返回符合时间范围及可选过滤条件的记录集合和总记录数。
        /// </summary>
        /// <param name="start">起始时间（含）</param>
        /// <param name="end">结束时间（不含）</param>
        /// <param name="pageIndex">页号（从 1 开始）</param>
        /// <param name="pageSize">每页大小</param>
        /// <param name="productNumber">可选的产品编号过滤</param>
        /// <param name="screwNumber">可选的螺丝编号（Number）过滤</param>
        /// <param name="lockPassed">可选的是否通过过滤</param>
        /// <returns>返回一个元组，包含记录集合和总记录数</returns>
        Task<(IEnumerable<LockResult> Items, int TotalCount)> QueryLockResultsAsync(DateTime start, DateTime end, int pageIndex, int pageSize, string productNumber = null, string productName = null, int? screwNumber = null, bool? lockPassed = null);

        /// <summary>
        /// 查询所有符合条件的锁付结果（不分页）。
        /// </summary>
        /// <param name="start">起始时间（含）</param>
        /// <param name="end">结束时间（不含）</param>
        /// <param name="productNumber">可选的产品编号过滤</param>
        /// <param name="screwNumber">可选的螺丝编号过滤</param>
        /// <param name="lockPassed">可选的是否通过过滤</param>
        /// <returns>符合条件的锁付结果集合。</returns>
        Task<IEnumerable<LockResult>> QueryAllLockResultsAsync(DateTime start, DateTime end, string productNumber = null, string productName = null, int? screwNumber = null, bool? lockPassed = null);

        /// <summary>
        /// 记录一次螺丝供料器批次更换记录
        /// </summary>
        /// <param name="record"></param>
        /// <returns></returns>
        Task RecordScrewFeederBatchAsync(ScrewFeederBatchRecord record);

        /// <summary>
        /// 查询螺丝供料器批次记录。
        /// 可按时间段、批次号精确匹配及供料器编号过滤。所有参数均为可选，传入 null 表示不作为过滤条件。
        /// </summary>
        /// <param name="start">可选：起始时间（包含）</param>
        /// <param name="end">可选：结束时间（包含）</param>
        /// <param name="batchNumber">可选：批次号（精确匹配）</param>
        /// <param name="feederNumber">可选：供料器编号</param>
        /// <returns>满足条件的记录集合（按 ChangeTime 降序）。</returns>
        Task<IEnumerable<ScrewFeederBatchRecord>> QueryScrewFeederBatchRecordsAsync(DateTime? start = null, DateTime? end = null, string batchNumber = null, int? feederNumber = null);

        /// <summary>
        /// 获取指定供料器编号的最新一条批次更换记录
        /// </summary>
        /// <param name="feederNumber"></param>
        /// <returns></returns>
        Task<ScrewFeederBatchRecord> GetLatestScrewFeederBatchRecordAsync(int feederNumber);

        /// <summary>
        /// 记录产品拍照结果（含图片路径、机器人位置、像素与绝对坐标等）。
        /// </summary>
        /// <param name="record"></param>
        /// <returns></returns>
        Task RecordPhotoCaptureAsync(PhotoCaptureRecord record);

        /// <summary>
        /// 查询拍照记录，支持按配方名、产品序列号和时间段过滤（所有参数可选）。
        /// </summary>
        /// <param name="recipeName"></param>
        /// <param name="cameraName"></param>
        /// <param name="productSN"></param>
        /// <param name="start"></param>
        /// <param name="end"></param>
        /// <returns></returns>
        Task<IEnumerable<PhotoCaptureRecord>> QueryPhotoCapturesAsync(string recipeName = null, string cameraName = null, string productSN = null, DateTime? start = null, DateTime? end = null);

        /// <summary>
        /// 记录披头更换记录。
        /// </summary>
        /// <param name="record"></param>
        /// <returns></returns>
        Task RecordHeadChangeAsync(HeadChangeRecord record);

        /// <summary>
        /// 查询披头更换记录，可按时间段或披头批号过滤（所有参数可选）。
        /// </summary>
        /// <param name="start"></param>
        /// <param name="end"></param>
        /// <param name="headBatchNumber"></param>
        /// <returns></returns>
        Task<IEnumerable<HeadChangeRecord>> QueryHeadChangeRecordsAsync(DateTime? start = null, DateTime? end = null, string headBatchNumber = null);

        /// <summary>
        /// 获取最新的一条披头更换记录（按 ChangeTime 降序）。
        /// </summary>
        /// <returns></returns>
        Task<HeadChangeRecord> GetLatestHeadChangeRecordAsync();

        /// <summary>
        /// 对最新披头的锁付次数进行递增并返回更新后的次数（如果不存在最新记录，则创建一条新的记录并返回 1）。
        /// </summary>
        /// <param name="operatorName"></param>
        /// <returns></returns>
        Task<int> IncrementLatestHeadLockCountAsync(string operatorName = null);

        /// <summary>
        /// 记录喷嘴更换记录。
        /// </summary>
        /// <param name="record"></param>
        /// <returns></returns>
        Task RecordNozzleChangeAsync(NozzleChangeRecord record);

        /// <summary>
        /// 查询喷嘴更换记录，可按时间段或喷嘴批号过滤（所有参数可选）。
        /// </summary>
        /// <param name="start"></param>
        /// <param name="end"></param>
        /// <param name="nozzleBatchNumber"></param>
        /// <returns></returns>
        Task<IEnumerable<NozzleChangeRecord>> QueryNozzleChangeRecordsAsync(DateTime? start = null, DateTime? end = null, string nozzleBatchNumber = null);

        /// <summary>
        /// 获取最新的一条喷嘴更换记录（按 ChangeTime 降序）。
        /// </summary>
        /// <returns></returns>
        Task<NozzleChangeRecord> GetLatestNozzleChangeRecordAsync();

        /// <summary>
        /// 吸嘴的锁付次数进行递增并返回更新后的次数（如果不存在最新记录，则创建一条新的记录并返回 1）。
        /// </summary>
        /// <param name="operatorName"></param>
        /// <returns></returns>
        Task<int> IncrementLatestNozzleLockCountAsync(string operatorName = null);
    }
}