feat: add start term update and cron schedule update

ApiDto/Common/CronUpdateSkip.cs

@@ -0,0 +1,24 @@
+using System;
+
+namespace Mirea.Api.Dto.Common;
+
+/// <summary>
+/// Represents a date or date range to skip during cron update scheduling.
+/// </summary>
+public class CronUpdateSkip
+{
+    /// <summary>
+    /// Gets or sets the start date of the skip range.
+    /// </summary>
+    public DateOnly? Start { get; set; }
+
+    /// <summary>
+    /// Gets or sets the end date of the skip range.
+    /// </summary>
+    public DateOnly? End { get; set; }
+
+    /// <summary>
+    /// Gets or sets a specific date to skip.
+    /// </summary>
+    public DateOnly? Date { get; set; }
+}

ApiDto/Responses/Configuration/CronUpdateScheduleResponse.cs

@@ -0,0 +1,23 @@
+using System;
+using System.Collections.Generic;
+using System.ComponentModel.DataAnnotations;
+
+namespace Mirea.Api.Dto.Responses.Configuration;
+
+/// <summary>
+/// Represents the response containing the cron update schedule and the next scheduled task dates.
+/// </summary>
+public class CronUpdateScheduleResponse
+{
+    /// <summary>
+    /// Gets or sets the cron expression representing the update schedule.
+    /// </summary>
+    [Required]
+    public required string Cron { get; set; }
+
+    /// <summary>
+    /// Gets or sets the list of next scheduled task dates based on the cron expression.
+    /// </summary>
+    [Required]
+    public required List<DateTime> NextStart { get; set; }
+}

Endpoint/Common/MapperDto/CronUpdateSkipConverter.cs

@@ -0,0 +1,19 @@
+using Mirea.Api.Endpoint.Common.Services;
+using Mirea.Api.Endpoint.Configuration.Model.GeneralSettings;
+using System.Collections.Generic;
+using System.Linq;
+
+namespace Mirea.Api.Endpoint.Common.MapperDto;
+
+public static class CronUpdateSkipConverter
+{
+    public static List<Dto.Common.CronUpdateSkip> ConvertToDto(this IEnumerable<ScheduleSettings.CronUpdateSkip> pairPeriod) =>
+        pairPeriod.Select(x => new Dto.Common.CronUpdateSkip()
+        {
+            Start = x.Start,
+            End = x.End,
+            Date = x.Date
+        }).ToList();
+    public static List<ScheduleSettings.CronUpdateSkip> ConvertFromDto(this IEnumerable<Dto.Common.CronUpdateSkip> pairPeriod) =>
+        pairPeriod.Select(x => x.Get()).ToList();
+}

Endpoint/Controllers/V1/Configuration/ScheduleController.cs

@@ -0,0 +1,132 @@
+using Asp.Versioning;
+using Cronos;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+using Mirea.Api.DataAccess.Persistence;
+using Mirea.Api.Dto.Common;
+using Mirea.Api.Dto.Responses.Configuration;
+using Mirea.Api.Endpoint.Common.Exceptions;
+using Mirea.Api.Endpoint.Common.MapperDto;
+using Mirea.Api.Endpoint.Common.Services;
+using Mirea.Api.Endpoint.Configuration.Model;
+using Mirea.Api.Endpoint.Configuration.Model.GeneralSettings;
+using System;
+using System.Collections.Generic;
+using System.ComponentModel.DataAnnotations;
+using System.Linq;
+
+namespace Mirea.Api.Endpoint.Controllers.V1.Configuration;
+
+[ApiVersion("1.0")]
+public class ScheduleController(ILogger<ScheduleController> logger, IOptionsSnapshot<GeneralConfig> config, UberDbContext dbContext) : ConfigurationBaseController
+{
+    /// <summary>
+    /// Retrieves the cron update schedule and calculates the next scheduled tasks based on the provided depth.
+    /// </summary>
+    /// <param name="depth">The depth of the next tasks to retrieve.</param>
+    /// <returns>Cron expression and the list of next scheduled task dates.</returns>
+    [HttpGet("CronUpdateSchedule")]
+    public ActionResult<CronUpdateScheduleResponse> CronUpdateSchedule([FromQuery][Range(0, 5)] int depth = 2)
+    {
+        var cronExpression = CronExpression.Parse(config.Value.ScheduleSettings!.CronUpdateSchedule);
+        var nextTasks = config.Value.ScheduleSettings!.CronUpdateSkipDateList.GetNextTask(cronExpression, depth);
+
+        return new CronUpdateScheduleResponse()
+        {
+            Cron = config.Value.ScheduleSettings!.CronUpdateSchedule,
+            NextStart = nextTasks.Select(x => DateTime.SpecifyKind(x.DateTime, DateTimeKind.Local)).ToList()
+        };
+    }
+
+    /// <summary>
+    /// Updates the cron update schedule with the provided cron expression.
+    /// </summary>
+    /// <param name="cron">The cron expression to set as the new schedule.</param>
+    /// <returns>Cron expression and the list of next scheduled task dates.</returns>
+    /// <exception cref="ControllerArgumentException">Thrown if the provided cron expression is invalid.</exception>
+    [HttpPost("CronUpdateSchedule")]
+    public ActionResult<CronUpdateScheduleResponse> CronUpdateSchedule([FromBody] string cron)
+    {
+        cron = cron.Trim();
+        if (!CronExpression.TryParse(cron, CronFormat.Standard, out _))
+            throw new ControllerArgumentException("Incorrect cron value.");
+
+        if (config.Value.ScheduleSettings!.CronUpdateSchedule == cron)
+            return Ok(CronUpdateSchedule());
+
+        config.Value.ScheduleSettings!.CronUpdateSchedule = cron;
+        config.Value.SaveSetting();
+
+        return Ok(CronUpdateSchedule());
+    }
+
+    /// <summary>
+    /// Retrieves the start term date from the configuration.
+    /// </summary>
+    /// <returns>Start term date.</returns>
+    [HttpGet("StartTerm")]
+    public ActionResult<DateOnly> StartTerm() =>
+        config.Value.ScheduleSettings!.StartTerm;
+
+    /// <summary>
+    /// Updates the start term date in the configuration.
+    /// </summary>
+    /// <param name="startTerm">The new start term date to set.</param>
+    /// <param name="force">If true, forces an update by deleting all existing lessons.</param>
+    /// <returns>Success or failure.</returns>
+    /// <exception cref="ControllerArgumentException">Thrown if the start term date is more than 6 months in the past or future.</exception>
+    [HttpPost("StartTerm")]
+    public ActionResult StartTerm([FromBody] DateOnly startTerm, [FromQuery] bool force = false)
+    {
+        var differentByTime = DateTime.Now - startTerm.ToDateTime(new TimeOnly(0, 0, 0));
+        if (differentByTime > TimeSpan.FromDays(190) || differentByTime.Multiply(-1) > TimeSpan.FromDays(190))
+            throw new ControllerArgumentException("The semester can't start more than 6 months from now, and it can't have started more than 6 months ago either.");
+
+        config.Value.ScheduleSettings!.StartTerm = startTerm;
+        config.Value.SaveSetting();
+
+        if (!force)
+            return Ok();
+
+        logger.LogWarning("A force update is being performed at the beginning of the semester (all classes will be deleted).");
+
+        dbContext.Lessons.RemoveRange(dbContext.Lessons.ToList());
+        dbContext.SaveChanges();
+
+        return Ok();
+    }
+
+    /// <summary>
+    /// Retrieves the list of cron update skip dates filtered by the current date.
+    /// </summary>
+    /// <returns>Cron update skip dates.</returns>
+    [HttpGet("CronUpdateSkip")]
+    public ActionResult<List<CronUpdateSkip>> CronUpdateSkip() =>
+        config.Value.ScheduleSettings!.CronUpdateSkipDateList.Filter(DateTime.Now).ConvertToDto();
+
+    /// <summary>
+    /// Updates the list of cron update skip dates in the configuration.
+    /// </summary>
+    /// <param name="cronUpdateDate">The list of cron update skip dates to set.</param>
+    /// <returns>Success or failure.</returns>
+    /// <exception cref="ControllerArgumentException">Thrown if the provided list of cron update skip dates is invalid.</exception>
+    [HttpPost("CronUpdateSkip")]
+    public ActionResult CronUpdateSkip([FromBody] List<CronUpdateSkip> cronUpdateDate)
+    {
+        List<ScheduleSettings.CronUpdateSkip> result;
+        try
+        {
+            result = cronUpdateDate.ConvertFromDto();
+        }
+        catch (ArgumentException ex)
+        {
+            throw new ControllerArgumentException(ex.Message);
+        }
+
+        config.Value.ScheduleSettings!.CronUpdateSkipDateList = result.Filter(DateTime.Now);
+        config.Value.SaveSetting();
+
+        return Ok();
+    }
+}