排课版本新建、编辑、复制、发布、归档和删除。

周课表视图，支持12节课、单双周和起止周。自动校验教师、行政班、教室、时间段冲突。校验教室容量、教学任务状态和学期范围。 SQLite 开发环境自动升级，MySQL 提供正式 EF Core 迁移。 Vue 已编译为静态文件并随 ASP.NET Core 发布，无需 npm run dev。桌面端和390px移动端页面均已验收。
2026-07-24 14:27:01 +08:00
parent 628944f64d
commit 0b463fa4f2
19 changed files with 2950 additions and 9 deletions
@@ -0,0 +1,406 @@
+using System.ComponentModel.DataAnnotations;
+using Jiaowu.Api.Domain.Academic;
+using Jiaowu.Api.Domain.Identity;
+using Jiaowu.Api.Infrastructure.Persistence;
+using Jiaowu.Api.Infrastructure.Scheduling;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.EntityFrameworkCore;
+
+namespace Jiaowu.Api.Controllers;
+
+[ApiController]
+[Authorize(Roles = ManagementRoles)]
+[Route("api/schedules")]
+public sealed class SchedulesController(AppDbContext db) : ControllerBase
+{
+    private const string ManagementRoles =
+        SystemRoles.SuperAdmin + "," +
+        SystemRoles.AcademicAdmin;
+
+    [HttpGet("plans")]
+    public async Task<ActionResult> GetPlans(
+        Guid? academicTermId,
+        CancellationToken cancellationToken)
+    {
+        var source = db.SchedulePlans.AsNoTracking().AsQueryable();
+        if (academicTermId.HasValue)
+            source = source.Where(x => x.AcademicTermId == academicTermId);
+        return Ok(await source
+            .OrderByDescending(x => x.AcademicTerm!.StartDate)
+            .ThenByDescending(x => x.CreatedAt)
+            .Select(x => new
+            {
+                x.Id,
+                x.Name,
+                x.Version,
+                x.AcademicTermId,
+                TermName = x.AcademicTerm!.Name,
+                x.Status,
+                x.PublishedAt,
+                EntryCount = x.Entries.Count,
+                x.UpdatedAt
+            })
+            .ToListAsync(cancellationToken));
+    }
+
+    [HttpGet("plans/{id:guid}")]
+    public async Task<ActionResult> GetPlan(Guid id, CancellationToken cancellationToken)
+    {
+        var plan = await db.SchedulePlans.AsNoTracking()
+            .Where(x => x.Id == id)
+            .Select(x => new
+            {
+                x.Id,
+                x.Name,
+                x.Version,
+                x.AcademicTermId,
+                TermName = x.AcademicTerm!.Name,
+                x.Status,
+                x.Notes,
+                x.PublishedAt,
+                Entries = x.Entries
+                    .OrderBy(entry => entry.DayOfWeek)
+                    .ThenBy(entry => entry.StartPeriod)
+                    .Select(entry => new
+                    {
+                        entry.Id,
+                        entry.TeachingTaskId,
+                        TaskNumber = entry.TeachingTask!.TaskNumber,
+                        TaskName = entry.TeachingTask.Name,
+                        CourseCode = entry.TeachingTask.Course!.Code,
+                        CourseName = entry.TeachingTask.Course.Name,
+                        TeacherNames = entry.TeachingTask.Teachers
+                            .OrderByDescending(item => item.IsPrimary)
+                            .Select(item => item.Teacher!.Name),
+                        ClassNames = entry.TeachingTask.Classes
+                            .Select(item => item.AdministrativeClass!.Name),
+                        entry.ClassroomId,
+                        ClassroomName = entry.Classroom!.Name,
+                        BuildingName = entry.Classroom.Building!.Name,
+                        CampusName = entry.Classroom.Building.Campus!.Name,
+                        entry.DayOfWeek,
+                        entry.StartPeriod,
+                        entry.PeriodCount,
+                        entry.StartWeek,
+                        entry.EndWeek,
+                        entry.WeekPattern,
+                        entry.Notes
+                    })
+            })
+            .FirstOrDefaultAsync(cancellationToken);
+        return plan is null ? NotFound() : Ok(plan);
+    }
+
+    [HttpPost("plans")]
+    public async Task<ActionResult> CreatePlan(
+        SchedulePlanRequest request,
+        CancellationToken cancellationToken)
+    {
+        if (!await db.AcademicTerms.AnyAsync(
+                x => x.Id == request.AcademicTermId && x.IsEnabled,
+                cancellationToken))
+            return ValidationProblem("所选学期不存在或已停用。");
+        var plan = new SchedulePlan
+        {
+            AcademicTermId = request.AcademicTermId,
+            Name = request.Name.Trim(),
+            Version = request.Version.Trim(),
+            Notes = Normalize(request.Notes)
+        };
+        db.SchedulePlans.Add(plan);
+        return await SaveAsync(plan.Id, true, cancellationToken);
+    }
+
+    [HttpPut("plans/{id:guid}")]
+    public async Task<ActionResult> UpdatePlan(
+        Guid id,
+        SchedulePlanRequest request,
+        CancellationToken cancellationToken)
+    {
+        var plan = await db.SchedulePlans.FindAsync([id], cancellationToken);
+        if (plan is null) return NotFound();
+        if (plan.Status != SchedulePlanStatus.Draft)
+            return ConflictProblem("已发布或已归档的排课版本不可直接修改。");
+        if (!await db.AcademicTerms.AnyAsync(
+                x => x.Id == request.AcademicTermId && x.IsEnabled,
+                cancellationToken))
+            return ValidationProblem("所选学期不存在或已停用。");
+        plan.AcademicTermId = request.AcademicTermId;
+        plan.Name = request.Name.Trim();
+        plan.Version = request.Version.Trim();
+        plan.Notes = Normalize(request.Notes);
+        return await SaveAsync(id, false, cancellationToken);
+    }
+
+    [HttpPost("plans/{id:guid}/clone")]
+    public async Task<ActionResult> ClonePlan(
+        Guid id,
+        CloneSchedulePlanRequest request,
+        CancellationToken cancellationToken)
+    {
+        var source = await db.SchedulePlans.AsNoTracking()
+            .Include(x => x.Entries)
+            .FirstOrDefaultAsync(x => x.Id == id, cancellationToken);
+        if (source is null) return NotFound();
+        var copy = new SchedulePlan
+        {
+            AcademicTermId = source.AcademicTermId,
+            Name = request.Name.Trim(),
+            Version = request.Version.Trim(),
+            Notes = source.Notes,
+            Entries = source.Entries.Select(entry => new ScheduleEntry
+            {
+                TeachingTaskId = entry.TeachingTaskId,
+                ClassroomId = entry.ClassroomId,
+                DayOfWeek = entry.DayOfWeek,
+                StartPeriod = entry.StartPeriod,
+                PeriodCount = entry.PeriodCount,
+                StartWeek = entry.StartWeek,
+                EndWeek = entry.EndWeek,
+                WeekPattern = entry.WeekPattern,
+                Notes = entry.Notes
+            }).ToList()
+        };
+        db.SchedulePlans.Add(copy);
+        return await SaveAsync(copy.Id, true, cancellationToken);
+    }
+
+    [HttpDelete("plans/{id:guid}")]
+    public async Task<ActionResult> DeletePlan(Guid id, CancellationToken cancellationToken)
+    {
+        var plan = await db.SchedulePlans.FindAsync([id], cancellationToken);
+        if (plan is null) return NotFound();
+        if (plan.Status != SchedulePlanStatus.Draft)
+            return ConflictProblem("仅草稿排课版本可以删除。");
+        db.SchedulePlans.Remove(plan);
+        return await SaveAsync(id, false, cancellationToken);
+    }
+
+    [HttpPost("plans/{id:guid}/publish")]
+    public async Task<ActionResult> PublishPlan(Guid id, CancellationToken cancellationToken)
+    {
+        var plan = await db.SchedulePlans
+            .Include(x => x.Entries)
+            .ThenInclude(x => x.TeachingTask)
+            .ThenInclude(x => x!.Teachers)
+            .Include(x => x.Entries)
+            .ThenInclude(x => x.TeachingTask)
+            .ThenInclude(x => x!.Classes)
+            .FirstOrDefaultAsync(x => x.Id == id, cancellationToken);
+        if (plan is null) return NotFound();
+        if (plan.Status != SchedulePlanStatus.Draft)
+            return ConflictProblem("只有草稿排课版本可以发布。");
+        if (plan.Entries.Count == 0)
+            return ConflictProblem("排课版本中至少需要一条课表安排。");
+
+        var conflict = ScheduleConflictDetector.FindConflict(plan.Entries.ToList());
+        if (conflict is not null) return ConflictProblem(conflict);
+
+        await using var transaction = await db.Database.BeginTransactionAsync(cancellationToken);
+        var previous = await db.SchedulePlans
+            .Where(x =>
+                x.Id != plan.Id &&
+                x.AcademicTermId == plan.AcademicTermId &&
+                x.Status == SchedulePlanStatus.Published)
+            .ToListAsync(cancellationToken);
+        foreach (var oldPlan in previous) oldPlan.Status = SchedulePlanStatus.Archived;
+        plan.Status = SchedulePlanStatus.Published;
+        plan.PublishedAt = DateTime.UtcNow;
+        await db.SaveChangesAsync(cancellationToken);
+        await transaction.CommitAsync(cancellationToken);
+        return NoContent();
+    }
+
+    [HttpPost("plans/{planId:guid}/entries")]
+    public async Task<ActionResult> CreateEntry(
+        Guid planId,
+        ScheduleEntryRequest request,
+        CancellationToken cancellationToken)
+    {
+        var plan = await DraftPlanAsync(planId, cancellationToken);
+        if (plan is null) return NotFound();
+        var validation = await ValidateEntryAsync(plan, null, request, cancellationToken);
+        if (validation is not null) return validation;
+        var entry = CreateEntryEntity(planId, request);
+        db.ScheduleEntries.Add(entry);
+        return await SaveAsync(entry.Id, true, cancellationToken);
+    }
+
+    [HttpPut("plans/{planId:guid}/entries/{entryId:guid}")]
+    public async Task<ActionResult> UpdateEntry(
+        Guid planId,
+        Guid entryId,
+        ScheduleEntryRequest request,
+        CancellationToken cancellationToken)
+    {
+        var plan = await DraftPlanAsync(planId, cancellationToken);
+        if (plan is null) return NotFound();
+        var entry = await db.ScheduleEntries
+            .FirstOrDefaultAsync(
+                x => x.Id == entryId && x.SchedulePlanId == planId,
+                cancellationToken);
+        if (entry is null) return NotFound();
+        var validation = await ValidateEntryAsync(plan, entryId, request, cancellationToken);
+        if (validation is not null) return validation;
+        entry.TeachingTaskId = request.TeachingTaskId;
+        entry.ClassroomId = request.ClassroomId;
+        entry.DayOfWeek = request.DayOfWeek;
+        entry.StartPeriod = request.StartPeriod;
+        entry.PeriodCount = request.PeriodCount;
+        entry.StartWeek = request.StartWeek;
+        entry.EndWeek = request.EndWeek;
+        entry.WeekPattern = request.WeekPattern;
+        entry.Notes = Normalize(request.Notes);
+        return await SaveAsync(entryId, false, cancellationToken);
+    }
+
+    [HttpDelete("plans/{planId:guid}/entries/{entryId:guid}")]
+    public async Task<ActionResult> DeleteEntry(
+        Guid planId,
+        Guid entryId,
+        CancellationToken cancellationToken)
+    {
+        if (await DraftPlanAsync(planId, cancellationToken) is null) return NotFound();
+        var entry = await db.ScheduleEntries
+            .FirstOrDefaultAsync(
+                x => x.Id == entryId && x.SchedulePlanId == planId,
+                cancellationToken);
+        if (entry is null) return NotFound();
+        db.ScheduleEntries.Remove(entry);
+        return await SaveAsync(entryId, false, cancellationToken);
+    }
+
+    private async Task<SchedulePlan?> DraftPlanAsync(
+        Guid id,
+        CancellationToken cancellationToken) =>
+        await db.SchedulePlans.FirstOrDefaultAsync(
+            x => x.Id == id && x.Status == SchedulePlanStatus.Draft,
+            cancellationToken);
+
+    private async Task<ActionResult?> ValidateEntryAsync(
+        SchedulePlan plan,
+        Guid? entryId,
+        ScheduleEntryRequest request,
+        CancellationToken cancellationToken)
+    {
+        if (request.StartWeek > request.EndWeek)
+            return ValidationProblem("开始周不能晚于结束周。");
+        if (request.StartPeriod + request.PeriodCount - 1 > 12)
+            return ValidationProblem("结束节次不能超过第 12 节。");
+
+        var task = await db.TeachingTasks.AsNoTracking()
+            .Include(x => x.Teachers)
+            .Include(x => x.Classes)
+            .ThenInclude(x => x.AdministrativeClass)
+            .ThenInclude(x => x!.Students)
+            .FirstOrDefaultAsync(x => x.Id == request.TeachingTaskId, cancellationToken);
+        if (task is null ||
+            task.Status != TeachingTaskStatus.Published ||
+            task.AcademicTermId != plan.AcademicTermId)
+            return ValidationProblem("只能安排同一学期内已发布的教学任务。");
+        if (request.StartWeek < task.StartWeek || request.EndWeek > task.EndWeek)
+            return ValidationProblem("排课周次必须位于教学任务的授课周次内。");
+
+        var classroom = await db.Classrooms.AsNoTracking()
+            .FirstOrDefaultAsync(
+                x => x.Id == request.ClassroomId && x.IsEnabled,
+                cancellationToken);
+        if (classroom is null) return ValidationProblem("所选教室不存在或已停用。");
+        var studentCount = task.Classes.Sum(x =>
+            x.AdministrativeClass!.Students.Count(student =>
+                student.Status == StudentStatus.Active));
+        if (studentCount > classroom.Capacity)
+            return ConflictProblem(
+                $"教室容量不足：教学班有 {studentCount} 名学生，教室仅容纳 {classroom.Capacity} 人。");
+
+        var candidates = await db.ScheduleEntries.AsNoTracking()
+            .Where(x =>
+                x.SchedulePlanId == plan.Id &&
+                x.Id != entryId &&
+                x.DayOfWeek == request.DayOfWeek &&
+                x.StartWeek <= request.EndWeek &&
+                x.EndWeek >= request.StartWeek &&
+                x.StartPeriod < request.StartPeriod + request.PeriodCount &&
+                request.StartPeriod < x.StartPeriod + x.PeriodCount)
+            .Include(x => x.TeachingTask)
+            .ThenInclude(x => x!.Teachers)
+            .Include(x => x.TeachingTask)
+            .ThenInclude(x => x!.Classes)
+            .ToListAsync(cancellationToken);
+        var proposed = CreateEntryEntity(plan.Id, request);
+        proposed.TeachingTask = task;
+        foreach (var candidate in candidates)
+        {
+            if (!ScheduleConflictDetector.TimeOverlaps(candidate, proposed)) continue;
+            var reason = ScheduleConflictDetector.ConflictReason(candidate, proposed);
+            if (reason is not null)
+                return ConflictProblem(
+                    $"与“{candidate.TeachingTask!.Name}”发生{reason}冲突。");
+        }
+        return null;
+    }
+
+    private static ScheduleEntry CreateEntryEntity(Guid planId, ScheduleEntryRequest request) =>
+        new()
+        {
+            SchedulePlanId = planId,
+            TeachingTaskId = request.TeachingTaskId,
+            ClassroomId = request.ClassroomId,
+            DayOfWeek = request.DayOfWeek,
+            StartPeriod = request.StartPeriod,
+            PeriodCount = request.PeriodCount,
+            StartWeek = request.StartWeek,
+            EndWeek = request.EndWeek,
+            WeekPattern = request.WeekPattern,
+            Notes = Normalize(request.Notes)
+        };
+
+    private async Task<ActionResult> SaveAsync(
+        Guid id,
+        bool created,
+        CancellationToken cancellationToken)
+    {
+        try
+        {
+            await db.SaveChangesAsync(cancellationToken);
+            return created ? Created(string.Empty, new { id }) : NoContent();
+        }
+        catch (DbUpdateException)
+        {
+            return ConflictProblem("排课版本重复，或关联数据已失效。");
+        }
+    }
+
+    private ActionResult ConflictProblem(string detail) =>
+        Conflict(new ProblemDetails
+        {
+            Title = "排课冲突",
+            Detail = detail,
+            Status = StatusCodes.Status409Conflict
+        });
+
+    private static string? Normalize(string? value) =>
+        string.IsNullOrWhiteSpace(value) ? null : value.Trim();
+}
+
+public sealed record SchedulePlanRequest(
+    Guid AcademicTermId,
+    [Required, MaxLength(120)] string Name,
+    [Required, MaxLength(30)] string Version,
+    [MaxLength(500)] string? Notes);
+
+public sealed record CloneSchedulePlanRequest(
+    [Required, MaxLength(120)] string Name,
+    [Required, MaxLength(30)] string Version);
+
+public sealed record ScheduleEntryRequest(
+    Guid TeachingTaskId,
+    Guid ClassroomId,
+    [Range(1, 7)] int DayOfWeek,
+    [Range(1, 12)] int StartPeriod,
+    [Range(1, 6)] int PeriodCount,
+    [Range(1, 30)] int StartWeek,
+    [Range(1, 30)] int EndWeek,
+    WeekPattern WeekPattern,
+    [MaxLength(500)] string? Notes);