选课批次：时间窗口、退课截止、学分上限、开放/关闭。

教学班投放：容量、班级范围、全校开放。学生选退课：容量、重复课程、学分上限、课表冲突校验。教学班实时名单。校级、学院级、学生角色分级操作。 SQLite 本地增量升级及演示数据。 MySQL 正式 EF Core 迁移。 Vue 已编译进 wwwroot，单服务运行无需 npm run dev。学生端和管理端均完成桌面、手机响应式检查。
2026-07-24 15:17:26 +08:00
parent bcc4d33bd5
commit 151a22554f
19 changed files with 3972 additions and 6 deletions
@@ -0,0 +1,746 @@
+using System.ComponentModel.DataAnnotations;
+using System.Data;
+using Jiaowu.Api.Domain.Academic;
+using Jiaowu.Api.Domain.Identity;
+using Jiaowu.Api.Infrastructure.Auth;
+using Jiaowu.Api.Infrastructure.CourseSelection;
+using Jiaowu.Api.Infrastructure.Persistence;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.EntityFrameworkCore;
+
+namespace Jiaowu.Api.Controllers;
+
+[ApiController]
+[Authorize]
+[Route("api/course-selections")]
+public sealed class CourseSelectionsController(
+    AppDbContext db,
+    ICurrentUserDataScope currentUserDataScope) : ControllerBase
+{
+    private const string RoundManagers =
+        SystemRoles.SuperAdmin + "," +
+        SystemRoles.AcademicAdmin;
+
+    private const string OfferingManagers =
+        SystemRoles.SuperAdmin + "," +
+        SystemRoles.AcademicAdmin + "," +
+        SystemRoles.CollegeAdmin;
+
+    private const string SelectionUsers =
+        OfferingManagers + "," +
+        SystemRoles.Student;
+
+    private const string RosterReaders =
+        OfferingManagers + "," +
+        SystemRoles.Teacher;
+
+    [HttpGet("rounds")]
+    [Authorize(Roles = SelectionUsers)]
+    public async Task<ActionResult> GetRounds(
+        Guid? academicTermId,
+        CancellationToken cancellationToken)
+    {
+        var source = db.CourseSelectionRounds.AsNoTracking().AsQueryable();
+        if (academicTermId.HasValue)
+            source = source.Where(x => x.AcademicTermId == academicTermId);
+        if (currentUserDataScope.Current.IsInRole(SystemRoles.Student))
+            source = source.Where(x => x.Status != CourseSelectionRoundStatus.Draft);
+
+        var now = DateTime.UtcNow;
+        return Ok(await source
+            .OrderByDescending(x => x.AcademicTerm!.StartDate)
+            .ThenByDescending(x => x.StartsAt)
+            .Select(x => new
+            {
+                x.Id,
+                x.Name,
+                x.AcademicTermId,
+                TermName = x.AcademicTerm!.Name,
+                x.StartsAt,
+                x.EndsAt,
+                x.WithdrawalEndsAt,
+                x.MaxCredits,
+                x.Status,
+                IsAvailableNow =
+                    x.Status == CourseSelectionRoundStatus.Open &&
+                    now >= x.StartsAt &&
+                    now <= x.EndsAt,
+                OfferingCount = x.Offerings.Count,
+                x.Notes,
+                x.UpdatedAt
+            })
+            .ToListAsync(cancellationToken));
+    }
+
+    [HttpPost("rounds")]
+    [Authorize(Roles = RoundManagers)]
+    public async Task<ActionResult> CreateRound(
+        CourseSelectionRoundRequest request,
+        CancellationToken cancellationToken)
+    {
+        var validation = await ValidateRoundAsync(request, cancellationToken);
+        if (validation is not null) return validation;
+        var round = new CourseSelectionRound
+        {
+            AcademicTermId = request.AcademicTermId,
+            Name = request.Name.Trim(),
+            StartsAt = request.StartsAt.ToUniversalTime(),
+            EndsAt = request.EndsAt.ToUniversalTime(),
+            WithdrawalEndsAt = request.WithdrawalEndsAt.ToUniversalTime(),
+            MaxCredits = request.MaxCredits,
+            Notes = Normalize(request.Notes)
+        };
+        db.CourseSelectionRounds.Add(round);
+        return await SaveAsync(round.Id, true, cancellationToken);
+    }
+
+    [HttpPut("rounds/{id:guid}")]
+    [Authorize(Roles = RoundManagers)]
+    public async Task<ActionResult> UpdateRound(
+        Guid id,
+        CourseSelectionRoundRequest request,
+        CancellationToken cancellationToken)
+    {
+        var round = await db.CourseSelectionRounds.FindAsync([id], cancellationToken);
+        if (round is null) return NotFound();
+        if (round.Status != CourseSelectionRoundStatus.Draft)
+            return ConflictProblem("只有草稿选课批次可以修改。");
+        var validation = await ValidateRoundAsync(request, cancellationToken);
+        if (validation is not null) return validation;
+        round.AcademicTermId = request.AcademicTermId;
+        round.Name = request.Name.Trim();
+        round.StartsAt = request.StartsAt.ToUniversalTime();
+        round.EndsAt = request.EndsAt.ToUniversalTime();
+        round.WithdrawalEndsAt = request.WithdrawalEndsAt.ToUniversalTime();
+        round.MaxCredits = request.MaxCredits;
+        round.Notes = Normalize(request.Notes);
+        return await SaveAsync(id, false, cancellationToken);
+    }
+
+    [HttpDelete("rounds/{id:guid}")]
+    [Authorize(Roles = RoundManagers)]
+    public async Task<ActionResult> DeleteRound(Guid id, CancellationToken cancellationToken)
+    {
+        var round = await db.CourseSelectionRounds.FindAsync([id], cancellationToken);
+        if (round is null) return NotFound();
+        if (round.Status != CourseSelectionRoundStatus.Draft)
+            return ConflictProblem("只有草稿选课批次可以删除。");
+        db.CourseSelectionRounds.Remove(round);
+        return await SaveAsync(id, false, cancellationToken);
+    }
+
+    [HttpPost("rounds/{id:guid}/open")]
+    [Authorize(Roles = RoundManagers)]
+    public async Task<ActionResult> OpenRound(Guid id, CancellationToken cancellationToken)
+    {
+        var round = await db.CourseSelectionRounds
+            .Include(x => x.Offerings)
+            .FirstOrDefaultAsync(x => x.Id == id, cancellationToken);
+        if (round is null) return NotFound();
+        if (round.Status != CourseSelectionRoundStatus.Draft)
+            return ConflictProblem("只有草稿选课批次可以开放。");
+        if (round.Offerings.Count == 0)
+            return ConflictProblem("至少配置一个可选教学班后才能开放。");
+        round.Status = CourseSelectionRoundStatus.Open;
+        return await SaveAsync(id, false, cancellationToken);
+    }
+
+    [HttpPost("rounds/{id:guid}/close")]
+    [Authorize(Roles = RoundManagers)]
+    public async Task<ActionResult> CloseRound(Guid id, CancellationToken cancellationToken)
+    {
+        var round = await db.CourseSelectionRounds.FindAsync([id], cancellationToken);
+        if (round is null) return NotFound();
+        if (round.Status != CourseSelectionRoundStatus.Open)
+            return ConflictProblem("只有开放中的选课批次可以关闭。");
+        round.Status = CourseSelectionRoundStatus.Closed;
+        return await SaveAsync(id, false, cancellationToken);
+    }
+
+    [HttpGet("rounds/{roundId:guid}/offerings")]
+    [Authorize(Roles = OfferingManagers)]
+    public async Task<ActionResult> GetOfferings(
+        Guid roundId,
+        CancellationToken cancellationToken)
+    {
+        var source = ScopedOfferings()
+            .AsNoTracking()
+            .Where(x => x.CourseSelectionRoundId == roundId);
+        return Ok(await source
+            .OrderBy(x => x.TeachingTask!.Course!.Code)
+            .ThenBy(x => x.TeachingTask!.TaskNumber)
+            .Select(x => new
+            {
+                x.Id,
+                x.CourseSelectionRoundId,
+                x.TeachingTaskId,
+                x.TeachingTask!.TaskNumber,
+                TaskName = x.TeachingTask.Name,
+                CourseCode = x.TeachingTask.Course!.Code,
+                CourseName = x.TeachingTask.Course.Name,
+                CollegeName = x.TeachingTask.Course.College!.Name,
+                x.TeachingTask.Course.Credits,
+                TeacherNames = x.TeachingTask.Teachers
+                    .OrderByDescending(item => item.IsPrimary)
+                    .Select(item => item.Teacher!.Name),
+                ClassNames = x.TeachingTask.Classes
+                    .Select(item => item.AdministrativeClass!.Name),
+                x.Capacity,
+                EnrolledCount = x.Enrollments.Count(item =>
+                    item.Status == CourseEnrollmentStatus.Enrolled),
+                x.IsOpenToAll,
+                x.Notes,
+                x.UpdatedAt
+            })
+            .ToListAsync(cancellationToken));
+    }
+
+    [HttpPost("rounds/{roundId:guid}/offerings")]
+    [Authorize(Roles = OfferingManagers)]
+    public async Task<ActionResult> CreateOffering(
+        Guid roundId,
+        CourseSelectionOfferingRequest request,
+        CancellationToken cancellationToken)
+    {
+        var round = await db.CourseSelectionRounds.FindAsync([roundId], cancellationToken);
+        if (round is null) return NotFound();
+        if (round.Status != CourseSelectionRoundStatus.Draft)
+            return ConflictProblem("选课批次开放后不能调整教学班。");
+        var task = await FindAccessibleTaskAsync(request.TeachingTaskId, cancellationToken);
+        var validation = ValidateOffering(round, task, request);
+        if (validation is not null) return validation;
+        var offering = new CourseSelectionOffering
+        {
+            CourseSelectionRoundId = roundId,
+            TeachingTaskId = request.TeachingTaskId,
+            Capacity = request.Capacity,
+            IsOpenToAll = request.IsOpenToAll,
+            Notes = Normalize(request.Notes)
+        };
+        db.CourseSelectionOfferings.Add(offering);
+        return await SaveAsync(offering.Id, true, cancellationToken);
+    }
+
+    [HttpPut("rounds/{roundId:guid}/offerings/{id:guid}")]
+    [Authorize(Roles = OfferingManagers)]
+    public async Task<ActionResult> UpdateOffering(
+        Guid roundId,
+        Guid id,
+        CourseSelectionOfferingRequest request,
+        CancellationToken cancellationToken)
+    {
+        var offering = await ScopedOfferings()
+            .Include(x => x.CourseSelectionRound)
+            .FirstOrDefaultAsync(
+                x => x.Id == id && x.CourseSelectionRoundId == roundId,
+                cancellationToken);
+        if (offering is null) return NotFound();
+        if (offering.CourseSelectionRound!.Status != CourseSelectionRoundStatus.Draft)
+            return ConflictProblem("选课批次开放后不能调整教学班。");
+        var task = await FindAccessibleTaskAsync(request.TeachingTaskId, cancellationToken);
+        var validation = ValidateOffering(offering.CourseSelectionRound, task, request);
+        if (validation is not null) return validation;
+        offering.TeachingTaskId = request.TeachingTaskId;
+        offering.Capacity = request.Capacity;
+        offering.IsOpenToAll = request.IsOpenToAll;
+        offering.Notes = Normalize(request.Notes);
+        return await SaveAsync(id, false, cancellationToken);
+    }
+
+    [HttpDelete("rounds/{roundId:guid}/offerings/{id:guid}")]
+    [Authorize(Roles = OfferingManagers)]
+    public async Task<ActionResult> DeleteOffering(
+        Guid roundId,
+        Guid id,
+        CancellationToken cancellationToken)
+    {
+        var offering = await ScopedOfferings()
+            .Include(x => x.CourseSelectionRound)
+            .FirstOrDefaultAsync(
+                x => x.Id == id && x.CourseSelectionRoundId == roundId,
+                cancellationToken);
+        if (offering is null) return NotFound();
+        if (offering.CourseSelectionRound!.Status != CourseSelectionRoundStatus.Draft)
+            return ConflictProblem("选课批次开放后不能调整教学班。");
+        db.CourseSelectionOfferings.Remove(offering);
+        return await SaveAsync(id, false, cancellationToken);
+    }
+
+    [HttpGet("offerings/{id:guid}/roster")]
+    [Authorize(Roles = RosterReaders)]
+    public async Task<ActionResult> GetRoster(Guid id, CancellationToken cancellationToken)
+    {
+        var offering = await db.CourseSelectionOfferings.AsNoTracking()
+            .Where(x => x.Id == id)
+            .Select(x => new
+            {
+                x.Id,
+                x.TeachingTaskId,
+                x.TeachingTask!.TaskNumber,
+                TaskName = x.TeachingTask.Name,
+                CourseName = x.TeachingTask.Course!.Name,
+                CollegeId = x.TeachingTask.Course.CollegeId,
+                TeacherUserIds = x.TeachingTask.Teachers
+                    .Select(item => item.Teacher!.UserId),
+                x.Capacity
+            })
+            .FirstOrDefaultAsync(cancellationToken);
+        if (offering is null) return NotFound();
+        var scope = currentUserDataScope.Current;
+        var isAssignedTeacher =
+            scope.IsInRole(SystemRoles.Teacher) &&
+            offering.TeacherUserIds.Contains(scope.UserId);
+        if (!isAssignedTeacher && !scope.CanAccessCollege(offering.CollegeId))
+            return Forbid();
+
+        var students = await db.CourseEnrollments.AsNoTracking()
+            .Where(x =>
+                x.CourseSelectionOfferingId == id &&
+                x.Status == CourseEnrollmentStatus.Enrolled)
+            .OrderBy(x => x.Student!.StudentNumber)
+            .Select(x => new
+            {
+                x.Id,
+                x.StudentId,
+                x.Student!.StudentNumber,
+                x.Student.Name,
+                ClassName = x.Student.AdministrativeClass!.Name,
+                MajorName = x.Student.AdministrativeClass.Major!.Name,
+                x.EnrolledAt
+            })
+            .ToListAsync(cancellationToken);
+        return Ok(new
+        {
+            offering.Id,
+            offering.TeachingTaskId,
+            offering.TaskNumber,
+            offering.TaskName,
+            offering.CourseName,
+            offering.Capacity,
+            EnrolledCount = students.Count,
+            Students = students
+        });
+    }
+
+    [HttpGet("student/options")]
+    [Authorize(Roles = SystemRoles.Student)]
+    public async Task<ActionResult> GetStudentOptions(
+        Guid roundId,
+        CancellationToken cancellationToken)
+    {
+        var student = await CurrentStudentAsync(cancellationToken);
+        if (student is null) return ProfileNotFound();
+        var round = await db.CourseSelectionRounds.AsNoTracking()
+            .FirstOrDefaultAsync(x => x.Id == roundId, cancellationToken);
+        if (round is null || round.Status == CourseSelectionRoundStatus.Draft)
+            return NotFound();
+
+        var offerings = await db.CourseSelectionOfferings.AsNoTracking()
+            .Where(x =>
+                x.CourseSelectionRoundId == roundId &&
+                x.TeachingTask!.Status == TeachingTaskStatus.Published &&
+                (x.IsOpenToAll ||
+                 x.TeachingTask.Classes.Any(item =>
+                     item.AdministrativeClassId == student.AdministrativeClassId)))
+            .OrderBy(x => x.TeachingTask!.Course!.Code)
+            .Select(x => new StudentOfferingDto(
+                x.Id,
+                x.TeachingTaskId,
+                x.TeachingTask!.TaskNumber,
+                x.TeachingTask.Course!.Code,
+                x.TeachingTask.Course.Name,
+                x.TeachingTask.Course.Credits,
+                x.TeachingTask.Teachers
+                    .OrderByDescending(item => item.IsPrimary)
+                    .Select(item => item.Teacher!.Name),
+                x.Capacity,
+                x.Enrollments.Count(item =>
+                    item.Status == CourseEnrollmentStatus.Enrolled),
+                x.IsOpenToAll,
+                x.Enrollments
+                    .Where(item => item.StudentId == student.Id)
+                    .Select(item => (CourseEnrollmentStatus?)item.Status)
+                    .FirstOrDefault(),
+                db.ScheduleEntries
+                    .Where(entry =>
+                        entry.TeachingTaskId == x.TeachingTaskId &&
+                        entry.SchedulePlan!.AcademicTermId == round.AcademicTermId &&
+                        entry.SchedulePlan.Status == SchedulePlanStatus.Published)
+                    .OrderBy(entry => entry.DayOfWeek)
+                    .ThenBy(entry => entry.StartPeriod)
+                    .Select(entry => new StudentScheduleDto(
+                        entry.DayOfWeek,
+                        entry.StartPeriod,
+                        entry.PeriodCount,
+                        entry.StartWeek,
+                        entry.EndWeek,
+                        entry.WeekPattern,
+                        entry.Classroom!.Name))
+                    .ToList()))
+            .ToListAsync(cancellationToken);
+
+        return Ok(new
+        {
+            Round = new
+            {
+                round.Id,
+                round.Name,
+                round.StartsAt,
+                round.EndsAt,
+                round.WithdrawalEndsAt,
+                round.MaxCredits,
+                round.Status,
+                IsAvailableNow = CourseSelectionRules.IsSelectionOpen(
+                    round,
+                    DateTime.UtcNow)
+            },
+            Student = new
+            {
+                student.Id,
+                student.StudentNumber,
+                student.Name,
+                ClassName = student.AdministrativeClass!.Name
+            },
+            Offerings = offerings
+        });
+    }
+
+    [HttpGet("student/enrollments")]
+    [Authorize(Roles = SystemRoles.Student)]
+    public async Task<ActionResult> GetStudentEnrollments(
+        Guid? academicTermId,
+        CancellationToken cancellationToken)
+    {
+        var student = await CurrentStudentAsync(cancellationToken);
+        if (student is null) return ProfileNotFound();
+        var source = db.CourseEnrollments.AsNoTracking()
+            .Where(x => x.StudentId == student.Id);
+        if (academicTermId.HasValue)
+        {
+            source = source.Where(x =>
+                x.CourseSelectionOffering!.CourseSelectionRound!.AcademicTermId ==
+                academicTermId);
+        }
+        return Ok(await source
+            .OrderByDescending(x => x.EnrolledAt)
+            .Select(x => new
+            {
+                x.Id,
+                x.CourseSelectionOfferingId,
+                RoundId = x.CourseSelectionOffering!.CourseSelectionRoundId,
+                RoundName = x.CourseSelectionOffering.CourseSelectionRound!.Name,
+                TermName = x.CourseSelectionOffering.CourseSelectionRound.AcademicTerm!.Name,
+                x.CourseSelectionOffering.TeachingTaskId,
+                TaskNumber = x.CourseSelectionOffering.TeachingTask!.TaskNumber,
+                CourseCode = x.CourseSelectionOffering.TeachingTask.Course!.Code,
+                CourseName = x.CourseSelectionOffering.TeachingTask.Course.Name,
+                x.CourseSelectionOffering.TeachingTask.Course.Credits,
+                TeacherNames = x.CourseSelectionOffering.TeachingTask.Teachers
+                    .OrderByDescending(item => item.IsPrimary)
+                    .Select(item => item.Teacher!.Name),
+                x.Status,
+                x.EnrolledAt,
+                x.WithdrawnAt,
+                CanWithdraw =
+                    x.Status == CourseEnrollmentStatus.Enrolled &&
+                    x.CourseSelectionOffering.CourseSelectionRound.Status ==
+                        CourseSelectionRoundStatus.Open &&
+                    DateTime.UtcNow <=
+                        x.CourseSelectionOffering.CourseSelectionRound.WithdrawalEndsAt
+            })
+            .ToListAsync(cancellationToken));
+    }
+
+    [HttpPost("student/enrollments")]
+    [Authorize(Roles = SystemRoles.Student)]
+    public async Task<ActionResult> Enroll(
+        StudentEnrollmentRequest request,
+        CancellationToken cancellationToken)
+    {
+        var student = await CurrentStudentAsync(cancellationToken);
+        if (student is null) return ProfileNotFound();
+        if (student.Status != StudentStatus.Active)
+            return ConflictProblem("只有在籍学生可以选课。");
+
+        await using var transaction = await db.Database.BeginTransactionAsync(
+            IsolationLevel.Serializable,
+            cancellationToken);
+        var offering = await db.CourseSelectionOfferings
+            .Include(x => x.CourseSelectionRound)
+            .Include(x => x.TeachingTask)
+            .ThenInclude(x => x!.Course)
+            .Include(x => x.TeachingTask)
+            .ThenInclude(x => x!.Classes)
+            .FirstOrDefaultAsync(x => x.Id == request.OfferingId, cancellationToken);
+        if (offering is null) return NotFound();
+        var round = offering.CourseSelectionRound!;
+        var task = offering.TeachingTask!;
+        var now = DateTime.UtcNow;
+        if (!CourseSelectionRules.IsSelectionOpen(round, now))
+            return ConflictProblem("当前不在该选课批次的开放时间内。");
+        if (task.Status != TeachingTaskStatus.Published)
+            return ConflictProblem("该教学班当前不可选。");
+        if (!offering.IsOpenToAll &&
+            !task.Classes.Any(x =>
+                x.AdministrativeClassId == student.AdministrativeClassId))
+            return Forbid();
+
+        var existing = await db.CourseEnrollments.FirstOrDefaultAsync(
+            x =>
+                x.CourseSelectionOfferingId == offering.Id &&
+                x.StudentId == student.Id,
+            cancellationToken);
+        if (existing?.Status == CourseEnrollmentStatus.Enrolled)
+            return ConflictProblem("你已经选择了该教学班。");
+        var enrolledCount = await db.CourseEnrollments.CountAsync(
+            x =>
+                x.CourseSelectionOfferingId == offering.Id &&
+                x.Status == CourseEnrollmentStatus.Enrolled,
+            cancellationToken);
+        if (enrolledCount >= offering.Capacity)
+            return ConflictProblem("该教学班名额已满。");
+
+        var duplicateCourse = await db.CourseEnrollments.AnyAsync(
+            x =>
+                x.StudentId == student.Id &&
+                x.Status == CourseEnrollmentStatus.Enrolled &&
+                x.CourseSelectionOffering!.TeachingTask!.CourseId == task.CourseId &&
+                x.CourseSelectionOffering.CourseSelectionRound!.AcademicTermId ==
+                    round.AcademicTermId,
+            cancellationToken);
+        if (duplicateCourse)
+            return ConflictProblem("同一学期不能重复选择相同课程。");
+
+        var selectedCredits = await db.CourseEnrollments
+            .Where(x =>
+                x.StudentId == student.Id &&
+                x.Status == CourseEnrollmentStatus.Enrolled &&
+                x.CourseSelectionOffering!.CourseSelectionRoundId == round.Id)
+            .SumAsync(
+                x => (decimal?)x.CourseSelectionOffering!.TeachingTask!.Course!.Credits,
+                cancellationToken) ?? 0;
+        if (selectedCredits + task.Course!.Credits > round.MaxCredits)
+        {
+            return ConflictProblem(
+                $"选课后将达到 {selectedCredits + task.Course.Credits:0.#} 学分，超过本轮 {round.MaxCredits:0.#} 学分上限。");
+        }
+
+        var candidateEntries = await PublishedScheduleEntries(
+            round.AcademicTermId,
+            [task.Id],
+            cancellationToken);
+        if (candidateEntries.Count == 0)
+            return ConflictProblem("该教学班尚未发布课表，暂时不能选课。");
+        var selectedTaskIds = await db.CourseEnrollments
+            .Where(x =>
+                x.StudentId == student.Id &&
+                x.Status == CourseEnrollmentStatus.Enrolled &&
+                x.CourseSelectionOffering!.CourseSelectionRound!.AcademicTermId ==
+                    round.AcademicTermId)
+            .Select(x => x.CourseSelectionOffering!.TeachingTaskId)
+            .Distinct()
+            .ToArrayAsync(cancellationToken);
+        var selectedEntries = await PublishedScheduleEntries(
+            round.AcademicTermId,
+            selectedTaskIds,
+            cancellationToken);
+        if (CourseSelectionRules.HasScheduleConflict(candidateEntries, selectedEntries))
+            return ConflictProblem("该教学班与已选课程的上课时间冲突。");
+
+        if (existing is null)
+        {
+            existing = new CourseEnrollment
+            {
+                CourseSelectionOfferingId = offering.Id,
+                StudentId = student.Id
+            };
+            db.CourseEnrollments.Add(existing);
+        }
+        else
+        {
+            existing.Status = CourseEnrollmentStatus.Enrolled;
+            existing.EnrolledAt = now;
+            existing.WithdrawnAt = null;
+        }
+        await db.SaveChangesAsync(cancellationToken);
+        await transaction.CommitAsync(cancellationToken);
+        return Created(string.Empty, new { existing.Id });
+    }
+
+    [HttpDelete("student/enrollments/{id:guid}")]
+    [Authorize(Roles = SystemRoles.Student)]
+    public async Task<ActionResult> Withdraw(Guid id, CancellationToken cancellationToken)
+    {
+        var student = await CurrentStudentAsync(cancellationToken);
+        if (student is null) return ProfileNotFound();
+        var enrollment = await db.CourseEnrollments
+            .Include(x => x.CourseSelectionOffering)
+            .ThenInclude(x => x!.CourseSelectionRound)
+            .FirstOrDefaultAsync(
+                x => x.Id == id && x.StudentId == student.Id,
+                cancellationToken);
+        if (enrollment is null) return NotFound();
+        if (enrollment.Status != CourseEnrollmentStatus.Enrolled)
+            return ConflictProblem("该课程已经退选。");
+        if (!CourseSelectionRules.CanWithdraw(
+                enrollment.CourseSelectionOffering!.CourseSelectionRound!,
+                DateTime.UtcNow))
+            return ConflictProblem("当前批次已停止退课。");
+        enrollment.Status = CourseEnrollmentStatus.Withdrawn;
+        enrollment.WithdrawnAt = DateTime.UtcNow;
+        return await SaveAsync(id, false, cancellationToken);
+    }
+
+    private IQueryable<CourseSelectionOffering> ScopedOfferings()
+    {
+        var source = db.CourseSelectionOfferings.AsQueryable();
+        var scope = currentUserDataScope.Current;
+        return scope.Scope == DataScope.All
+            ? source
+            : source.Where(x =>
+                x.TeachingTask!.Course!.CollegeId == scope.RestrictedCollegeId);
+    }
+
+    private async Task<TeachingTask?> FindAccessibleTaskAsync(
+        Guid id,
+        CancellationToken cancellationToken)
+    {
+        var scope = currentUserDataScope.Current;
+        var source = db.TeachingTasks.AsNoTracking().AsQueryable();
+        if (scope.Scope != DataScope.All)
+        {
+            source = source.Where(x =>
+                x.Course!.CollegeId == scope.RestrictedCollegeId);
+        }
+        return await source
+            .Include(x => x.Course)
+            .FirstOrDefaultAsync(x => x.Id == id, cancellationToken);
+    }
+
+    private ActionResult? ValidateOffering(
+        CourseSelectionRound round,
+        TeachingTask? task,
+        CourseSelectionOfferingRequest request)
+    {
+        if (task is null) return ValidationProblem("所选教学班不存在或超出数据范围。");
+        if (task.AcademicTermId != round.AcademicTermId)
+            return ValidationProblem("教学班与选课批次必须属于同一学期。");
+        if (task.Status != TeachingTaskStatus.Published)
+            return ValidationProblem("只有已发布的教学班可以进入选课。");
+        if (request.Capacity > task.Capacity)
+            return ValidationProblem($"选课容量不能超过教学班容量 {task.Capacity}。");
+        return null;
+    }
+
+    private async Task<ActionResult?> ValidateRoundAsync(
+        CourseSelectionRoundRequest request,
+        CancellationToken cancellationToken)
+    {
+        var startsAt = request.StartsAt.ToUniversalTime();
+        var endsAt = request.EndsAt.ToUniversalTime();
+        var withdrawalEndsAt = request.WithdrawalEndsAt.ToUniversalTime();
+        if (startsAt >= endsAt)
+            return ValidationProblem("选课开始时间必须早于结束时间。");
+        if (withdrawalEndsAt < endsAt)
+            return ValidationProblem("退课截止时间不能早于选课结束时间。");
+        if (!await db.AcademicTerms.AnyAsync(
+                x => x.Id == request.AcademicTermId && x.IsEnabled,
+                cancellationToken))
+            return ValidationProblem("所选学期不存在或已停用。");
+        return null;
+    }
+
+    private async Task<Student?> CurrentStudentAsync(
+        CancellationToken cancellationToken)
+    {
+        var userId = currentUserDataScope.Current.UserId;
+        return await db.Students
+            .Include(x => x.AdministrativeClass)
+            .FirstOrDefaultAsync(x => x.UserId == userId, cancellationToken);
+    }
+
+    private async Task<List<ScheduleEntry>> PublishedScheduleEntries(
+        Guid academicTermId,
+        IReadOnlyCollection<Guid> taskIds,
+        CancellationToken cancellationToken)
+    {
+        if (taskIds.Count == 0) return [];
+        return await db.ScheduleEntries.AsNoTracking()
+            .Where(x =>
+                taskIds.Contains(x.TeachingTaskId) &&
+                x.SchedulePlan!.AcademicTermId == academicTermId &&
+                x.SchedulePlan.Status == SchedulePlanStatus.Published)
+            .ToListAsync(cancellationToken);
+    }
+
+    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 ProfileNotFound() =>
+        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 CourseSelectionRoundRequest(
+    Guid AcademicTermId,
+    [Required, MaxLength(120)] string Name,
+    DateTime StartsAt,
+    DateTime EndsAt,
+    DateTime WithdrawalEndsAt,
+    [Range(typeof(decimal), "0.5", "99")] decimal MaxCredits,
+    [MaxLength(500)] string? Notes);
+
+public sealed record CourseSelectionOfferingRequest(
+    Guid TeachingTaskId,
+    [Range(1, 10000)] int Capacity,
+    bool IsOpenToAll,
+    [MaxLength(500)] string? Notes);
+
+public sealed record StudentEnrollmentRequest(Guid OfferingId);
+
+public sealed record StudentOfferingDto(
+    Guid Id,
+    Guid TeachingTaskId,
+    string TaskNumber,
+    string CourseCode,
+    string CourseName,
+    decimal Credits,
+    IEnumerable<string> TeacherNames,
+    int Capacity,
+    int EnrolledCount,
+    bool IsOpenToAll,
+    CourseEnrollmentStatus? EnrollmentStatus,
+    IEnumerable<StudentScheduleDto> Schedules);
+
+public sealed record StudentScheduleDto(
+    int DayOfWeek,
+    int StartPeriod,
+    int PeriodCount,
+    int StartWeek,
+    int EndWeek,
+    WeekPattern WeekPattern,
+    string ClassroomName);
@@ -1,3 +1,4 @@
+using Jiaowu.Api.Domain.Academic;
 using Jiaowu.Api.Infrastructure.Persistence;
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Mvc;
@@ -35,6 +36,14 @@ public sealed class DashboardController(AppDbContext db) : ControllerBase
                CurriculumPlans = await db.CurriculumPlans.CountAsync(cancellationToken),
                TeachingTasks = await db.TeachingTasks.CountAsync(cancellationToken),
                SchedulePlans = await db.SchedulePlans.CountAsync(cancellationToken),
+                CourseSelectionRounds = await db.CourseSelectionRounds
+                    .CountAsync(cancellationToken),
+                CourseSelectionOfferings = await db.CourseSelectionOfferings
+                    .CountAsync(cancellationToken),
+                CourseEnrollments = await db.CourseEnrollments
+                    .CountAsync(
+                        x => x.Status == CourseEnrollmentStatus.Enrolled,
+                        cancellationToken),
                Users = await db.Users.CountAsync(cancellationToken)
            }
        };