From ff357f2794996f01d8510f2e683a4331125cfab4 Mon Sep 17 00:00:00 2001
From: ngfrolov <ng.frolov@autodrilling.ru>
Date: Fri, 5 Aug 2022 17:16:11 +0500
Subject: [PATCH] doc AsbCloudApp

---
 AsbCloudApp/Comparators/ComparerIId.cs        |  2 +-
 .../DetectedOperation/DetectedOperationDto.cs |  4 +-
 AsbCloudApp/Data/TimeDto.cs                   |  2 +
 AsbCloudApp/Services/IAuthService.cs          | 35 ++++++++++++++++
 .../Services/IBackgroundWorkerService.cs      | 30 +++++++++++++-
 AsbCloudApp/Services/IClusterService.cs       | 41 +++++++++++++++++++
 AsbCloudApp/Services/IDailyReportService.cs   |  6 ++-
 .../Services/IDetectedOperationService.cs     | 38 +++++++++++++++++
 .../DetectedOperationServiceTest.cs           |  2 +-
 9 files changed, 154 insertions(+), 6 deletions(-)

diff --git a/AsbCloudApp/Comparators/ComparerIId.cs b/AsbCloudApp/Comparators/ComparerIId.cs
index 5ea883ec..7dbf5cb5 100644
--- a/AsbCloudApp/Comparators/ComparerIId.cs
+++ b/AsbCloudApp/Comparators/ComparerIId.cs
@@ -9,7 +9,7 @@ namespace AsbCloudApp.Comparators
     /// </summary>
     public class ComparerIId : IComparer<IId>, IEqualityComparer<IId>
     {
-        private static readonly ComparerIId instance = new ComparerIId();
+        private static readonly ComparerIId instance = new ();
         private ComparerIId() { }
 
         /// <summary>
diff --git a/AsbCloudApp/Data/DetectedOperation/DetectedOperationDto.cs b/AsbCloudApp/Data/DetectedOperation/DetectedOperationDto.cs
index add539e4..62837213 100644
--- a/AsbCloudApp/Data/DetectedOperation/DetectedOperationDto.cs
+++ b/AsbCloudApp/Data/DetectedOperation/DetectedOperationDto.cs
@@ -52,12 +52,12 @@ namespace AsbCloudApp.Data.DetectedOperation
         /// <summary>
         /// название/описание операции
         /// </summary>
-        public WellOperationCategoryDto OperationCategory { get; set; }
+        public WellOperationCategoryDto OperationCategory { get; set; } = null!;
 
         /// <summary>
         /// Пользователь панели оператора
         /// </summary>
-        public string TelemetryUserName { get; set; }
+        public string? TelemetryUserName { get; set; }
 
         /// <summary>
         /// Бурильщик
diff --git a/AsbCloudApp/Data/TimeDto.cs b/AsbCloudApp/Data/TimeDto.cs
index 91d0fc5f..faf99427 100644
--- a/AsbCloudApp/Data/TimeDto.cs
+++ b/AsbCloudApp/Data/TimeDto.cs
@@ -121,6 +121,7 @@ namespace AsbCloudApp.Data
         public int CompareTo(TimeDto other)
             => TotalSeconds - other.TotalSeconds;
 
+        /// <inheritdoc/>
         public override bool Equals(object obj)
         {
             if (ReferenceEquals(this, obj))
@@ -141,6 +142,7 @@ namespace AsbCloudApp.Data
             return false;
         }
 
+        /// <inheritdoc/>
         public override int GetHashCode()
         {
             return base.GetHashCode();
diff --git a/AsbCloudApp/Services/IAuthService.cs b/AsbCloudApp/Services/IAuthService.cs
index 783eb8e0..34030c24 100644
--- a/AsbCloudApp/Services/IAuthService.cs
+++ b/AsbCloudApp/Services/IAuthService.cs
@@ -5,14 +5,49 @@ using System.Threading.Tasks;
 
 namespace AsbCloudApp.Services
 {
+    /// <summary>
+    /// Сервис авторизации
+    /// </summary>
     public interface IAuthService
     {
+        /// <summary>
+        /// Смена пароля пользователю
+        /// </summary>
+        /// <param name="idUser"></param>
+        /// <param name="newPassword"></param>
+        /// <returns></returns>
         int ChangePassword(int idUser, string newPassword);
+
+        /// <summary>
+        /// Смена пароля пользователю
+        /// </summary>
+        /// <param name="userLogin"></param>
+        /// <param name="newPassword"></param>
+        /// <returns></returns>
         int ChangePassword(string userLogin, string newPassword);
+
+        /// <summary>
+        /// Авторизация
+        /// </summary>
+        /// <param name="login"></param>
+        /// <param name="password"></param>
+        /// <param name="token">токен отмены задачи</param>
+        /// <returns></returns>
         Task<UserTokenDto> LoginAsync(string login,
             string password, CancellationToken token = default);
 
+        /// <summary>
+        /// Обновление токена авторизации
+        /// </summary>
+        /// <param name="user"></param>
+        /// <returns></returns>
         string Refresh(ClaimsPrincipal user);
+
+        /// <summary>
+        /// Регистрация нового пользователя
+        /// </summary>
+        /// <param name="userDto"></param>
+        /// <returns></returns>
         int Register(UserRegistrationDto userDto);
     }
 }
\ No newline at end of file
diff --git a/AsbCloudApp/Services/IBackgroundWorkerService.cs b/AsbCloudApp/Services/IBackgroundWorkerService.cs
index c65fd4f5..2ccc47ab 100644
--- a/AsbCloudApp/Services/IBackgroundWorkerService.cs
+++ b/AsbCloudApp/Services/IBackgroundWorkerService.cs
@@ -4,19 +4,47 @@ using System.Threading.Tasks;
 
 namespace AsbCloudApp.Services
 {
+    /// <summary>
+    /// Сервис выстраивает очередь из фоновых задач. Ограничивает количество одновременно выполняющихся задач.
+    /// </summary>
     public interface IBackgroundWorkerService
     {
+        /// <summary>
+        /// Проверка, есть ли задача в очереди
+        /// </summary>
+        /// <param name="id">идентификатор задачи</param>
+        /// <returns></returns>
         bool Contains(string id);
 
         /// <summary>
         /// Добавляет в очередь задач новую задачу
         /// </summary>
-        /// <param name="id">id задачи в очереди</param>
+        /// <param name="id">идентификатор задачи</param>
         /// <param name="func">делегат</param>
         /// <returns>id задачи в очереди</returns>
         string Enqueue(string id, Func<string, CancellationToken, Task> func);
+
+        /// <summary>
+        /// Добавляет в очередь задач новую задачу
+        /// </summary>
+        /// <param name="func"></param>
+        /// <returns></returns>
         string Enqueue(Func<string, CancellationToken, Task> func);
+
+        /// <summary>
+        /// Добавляет в очередь задач новую задачу
+        /// </summary>
+        /// <param name="id">идентификатор задачи</param>
+        /// <param name="func"></param>
+        /// <param name="onError"></param>
+        /// <returns></returns>
         string Enqueue(string id, Func<string, CancellationToken, Task> func, Func<string, Exception, CancellationToken, Task> onError);
+
+        /// <summary>
+        /// Пробуем удалить задачу по идентификатору
+        /// </summary>
+        /// <param name="id"></param>
+        /// <returns></returns>
         bool TryRemove(string id);
     }
 }
\ No newline at end of file
diff --git a/AsbCloudApp/Services/IClusterService.cs b/AsbCloudApp/Services/IClusterService.cs
index 66952f21..5a77d46d 100644
--- a/AsbCloudApp/Services/IClusterService.cs
+++ b/AsbCloudApp/Services/IClusterService.cs
@@ -5,16 +5,57 @@ using System.Threading.Tasks;
 
 namespace AsbCloudApp.Services
 {
+    //TODO: remove unused methods
+
+    /// <summary>
+    /// Сервис информации о кустах
+    /// </summary>
     public interface IClusterService
     {
+        /// <summary>
+        /// список месторождений
+        /// </summary>
+        /// <param name="idCompany"></param>
+        /// <param name="token"></param>
+        /// <returns></returns>
         Task<IEnumerable<DepositDto>> GetDepositsAsync(int idCompany,
             CancellationToken token);
+
+        /// <summary>
+        /// Список кустов с заполненными параметрами бурения
+        /// </summary>
+        /// <param name="idCompany"></param>
+        /// <param name="token"></param>
+        /// <returns></returns>
         Task<IEnumerable<DepositDto>> GetDepositsDrillParamsAsync(int idCompany,
             CancellationToken token = default);
+
+        /// <summary>
+        /// Список кустов месторождения доступных компании
+        /// </summary>
+        /// <param name="idCompany"></param>
+        /// <param name="depositId"></param>
+        /// <param name="token"></param>
+        /// <returns></returns>
         Task<IEnumerable<ClusterDto>> GetClustersAsync(int idCompany,
             int depositId, CancellationToken token);
+
+        /// <summary>
+        /// Список кустов доступных компании
+        /// </summary>
+        /// <param name="idCompany"></param>
+        /// <param name="token"></param>
+        /// <returns></returns>
         Task<IEnumerable<ClusterDto>> GetClustersAsync(int idCompany,
             CancellationToken token);
+
+        /// <summary>
+        /// Список скважин доступных компании
+        /// </summary>
+        /// <param name="idCompany"></param>
+        /// <param name="clusterId"></param>
+        /// <param name="token"></param>
+        /// <returns></returns>
         Task<IEnumerable<WellDto>> GetWellsAsync(int idCompany,
             int clusterId, CancellationToken token);
     }
diff --git a/AsbCloudApp/Services/IDailyReportService.cs b/AsbCloudApp/Services/IDailyReportService.cs
index ba9f58a7..28bc72fc 100644
--- a/AsbCloudApp/Services/IDailyReportService.cs
+++ b/AsbCloudApp/Services/IDailyReportService.cs
@@ -7,8 +7,12 @@ using System.Threading.Tasks;
 
 namespace AsbCloudApp.Services
 {
+    /// <summary>
+    /// Суточный рапорт (сводка)
+    /// </summary>
     public interface IDailyReportService
-    {        
+    {
+
         Task<IEnumerable<DailyReportDto>> GetListAsync(int idWell, DateTime? v1, DateTime? v2, CancellationToken cancellationToken);
         Task<DailyReportDto> GetOrGenerateAsync(int idWell, DateTime date, CancellationToken token);
         Task<int> AddAsync(int idWell, DailyReportDto dto, CancellationToken token = default);
diff --git a/AsbCloudApp/Services/IDetectedOperationService.cs b/AsbCloudApp/Services/IDetectedOperationService.cs
index 3d077443..0a0bd999 100644
--- a/AsbCloudApp/Services/IDetectedOperationService.cs
+++ b/AsbCloudApp/Services/IDetectedOperationService.cs
@@ -9,12 +9,50 @@ using System.Threading.Tasks;
 namespace AsbCloudApp.Services
 {
 #nullable enable
+    /// <summary>
+    /// Сервис автоматически определенных по телеметрии операций
+    /// </summary>
     public interface IDetectedOperationService
     {
+        /// <summary>
+        /// Список названий операций.
+        /// Если указан idWell, то возвращается список названий операций найденных на указанной скважине.
+        /// </summary>
+        /// <param name="idWell"></param>
+        /// <param name="token"></param>
+        /// <returns></returns>
         Task<IEnumerable<WellOperationCategoryDto>?> GetCategoriesAsync(int? idWell, CancellationToken token);
+
+        /// <summary>
+        /// Получить автоматически определенные по телеметрии операции с анализом по бурильщикам
+        /// </summary>
+        /// <param name="request"></param>
+        /// <param name="token"></param>
+        /// <returns></returns>
         Task<DetectedOperationListDto?> GetAsync(DetectedOperationRequest request, CancellationToken token);
+
+        /// <summary>
+        /// Удалить операции
+        /// </summary>
+        /// <param name="request"></param>
+        /// <param name="token"></param>
+        /// <returns></returns>
         Task<int> DeleteAsync(DetectedOperationRequest request, CancellationToken token);
+
+        /// <summary>
+        /// Статистика по операциям
+        /// </summary>
+        /// <param name="request"></param>
+        /// <param name="token"></param>
+        /// <returns></returns>
         Task<IEnumerable<DetectedOperationStatDto>?> GetOperationsStatAsync(DetectedOperationRequest request, CancellationToken token);
+
+        /// <summary>
+        /// Выгрузка в Excel
+        /// </summary>
+        /// <param name="idsWells"></param>
+        /// <param name="token"></param>
+        /// <returns></returns>
         Task<Stream> ExportAsync(IEnumerable<int> idsWells, CancellationToken token);
     }
 #nullable disable
diff --git a/AsbCloudWebApi.Tests/ServicesTests/DetectedOperationServiceTest.cs b/AsbCloudWebApi.Tests/ServicesTests/DetectedOperationServiceTest.cs
index e169049d..03bcff27 100644
--- a/AsbCloudWebApi.Tests/ServicesTests/DetectedOperationServiceTest.cs
+++ b/AsbCloudWebApi.Tests/ServicesTests/DetectedOperationServiceTest.cs
@@ -131,7 +131,7 @@ namespace AsbCloudWebApi.Tests.ServicesTests
             request = new DetectedOperationRequest
             {
                 IdWell = 1,
-                IdCategory = 1
+                IdsCategories = new int[] { 1 },
             };
             AsbCloudInfrastructure.DependencyInjection.MapsterSetup();
         }