已完成“成绩管理与学业档案”模块:

教师批量录入平时、期中、期末成绩。
自动计算总评、绩点和及格状态。
支持缺考、缓考、免修。
教师提交 → 学院审核/退回 → 校级发布。
学生只能查看正式发布成绩。
自动统计平均分、完成度、及格率和加权 GPA。
SQLite 本地增量升级和 MySQL 正式迁移均已完成。
分级权限在前后端同时校验。
This commit is contained in:
2026-07-24 15:33:47 +08:00 Unverified
parent 151a22554f
commit af52e27a3a
18 changed files with 3686 additions and 22 deletions
@@ -0,0 +1,515 @@
using System.ComponentModel.DataAnnotations;
using Jiaowu.Api.Domain.Academic;
using Jiaowu.Api.Domain.Identity;
using Jiaowu.Api.Infrastructure.Auth;
using Jiaowu.Api.Infrastructure.Grades;
using Jiaowu.Api.Infrastructure.Persistence;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
namespace Jiaowu.Api.Controllers;
[ApiController]
[Authorize]
[Route("api/grades")]
public sealed class GradesController(
AppDbContext db,
ICurrentUserDataScope currentUserDataScope) : ControllerBase
{
private const string SheetUsers =
SystemRoles.SuperAdmin + "," +
SystemRoles.AcademicAdmin + "," +
SystemRoles.CollegeAdmin + "," +
SystemRoles.Teacher;
private const string Reviewers =
SystemRoles.SuperAdmin + "," +
SystemRoles.AcademicAdmin + "," +
SystemRoles.CollegeAdmin;
private const string Publishers =
SystemRoles.SuperAdmin + "," +
SystemRoles.AcademicAdmin;
[HttpGet("sheets")]
[Authorize(Roles = SheetUsers)]
public async Task<ActionResult> GetSheets(
Guid? academicTermId,
GradeSheetStatus? status,
CancellationToken cancellationToken)
{
var source = AccessibleTasks().AsNoTracking()
.Where(x =>
x.Status == TeachingTaskStatus.Published ||
x.Status == TeachingTaskStatus.Closed);
if (academicTermId.HasValue)
source = source.Where(x => x.AcademicTermId == academicTermId);
var items = await source
.OrderByDescending(x => x.AcademicTerm!.StartDate)
.ThenBy(x => x.TaskNumber)
.Select(x => new
{
x.Id,
x.TaskNumber,
TaskName = x.Name,
x.AcademicTermId,
TermName = x.AcademicTerm!.Name,
CourseCode = x.Course!.Code,
CourseName = x.Course.Name,
CollegeName = x.Course.College!.Name,
x.Course.Credits,
TeacherNames = x.Teachers
.OrderByDescending(item => item.IsPrimary)
.Select(item => item.Teacher!.Name),
ClassNames = x.Classes.Select(item => item.AdministrativeClass!.Name),
Sheet = db.GradeSheets
.Where(sheet => sheet.TeachingTaskId == x.Id)
.Select(sheet => new
{
sheet.Id,
sheet.Status,
sheet.RegularWeight,
sheet.MidtermWeight,
sheet.FinalWeight,
StudentCount = sheet.Records.Count,
CompletedCount = sheet.Records.Count(record =>
record.TotalScore != null ||
record.ExamStatus != GradeExamStatus.Normal),
PassedCount = sheet.Records.Count(record =>
record.TotalScore >= 60),
sheet.SubmittedAt,
sheet.ReviewedAt,
sheet.PublishedAt,
sheet.UpdatedAt
})
.FirstOrDefault()
})
.ToListAsync(cancellationToken);
if (status.HasValue)
items = items.Where(x => x.Sheet?.Status == status.Value).ToList();
return Ok(items);
}
[HttpPost("sheets")]
[Authorize(Roles = SheetUsers)]
public async Task<ActionResult> CreateSheet(
GradeSheetRequest request,
CancellationToken cancellationToken)
{
if (!GradeCalculator.AreWeightsValid(
request.RegularWeight,
request.MidtermWeight,
request.FinalWeight))
return ValidationProblem("平时、期中和期末成绩比例必须合计 100%。");
var task = await AccessibleTasks()
.Include(x => x.Teachers)
.FirstOrDefaultAsync(x => x.Id == request.TeachingTaskId, cancellationToken);
if (task is null) return NotFound();
if (task.Status is not (TeachingTaskStatus.Published or TeachingTaskStatus.Closed))
return ConflictProblem("只有已发布或已结课的教学班可以建立成绩单。");
if (!CanInitialize(task)) return Forbid();
if (await db.GradeSheets.AnyAsync(
x => x.TeachingTaskId == task.Id,
cancellationToken))
return ConflictProblem("该教学班已经建立成绩单。");
var studentIds = await db.CourseEnrollments.AsNoTracking()
.Where(x =>
x.Status == CourseEnrollmentStatus.Enrolled &&
x.CourseSelectionOffering!.TeachingTaskId == task.Id)
.Select(x => x.StudentId)
.Distinct()
.ToListAsync(cancellationToken);
if (studentIds.Count == 0)
return ConflictProblem("教学班当前没有有效选课学生,无法建立成绩单。");
var sheet = new GradeSheet
{
TeachingTaskId = task.Id,
RegularWeight = request.RegularWeight,
MidtermWeight = request.MidtermWeight,
FinalWeight = request.FinalWeight,
Records = studentIds.Select(studentId => new GradeRecord
{
StudentId = studentId
}).ToList()
};
db.GradeSheets.Add(sheet);
return await SaveAsync(sheet.Id, true, cancellationToken);
}
[HttpGet("sheets/{id:guid}")]
[Authorize(Roles = SheetUsers)]
public async Task<ActionResult> GetSheet(Guid id, CancellationToken cancellationToken)
{
var sheet = await AccessibleSheets().AsNoTracking()
.Where(x => x.Id == id)
.Select(x => new
{
x.Id,
x.TeachingTaskId,
x.TeachingTask!.TaskNumber,
TaskName = x.TeachingTask.Name,
x.TeachingTask.AcademicTermId,
TermName = x.TeachingTask.AcademicTerm!.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.RegularWeight,
x.MidtermWeight,
x.FinalWeight,
x.Status,
x.ReviewComment,
x.SubmittedAt,
x.ReviewedAt,
x.PublishedAt,
Records = x.Records
.OrderBy(record => record.Student!.StudentNumber)
.Select(record => new
{
record.Id,
record.StudentId,
record.Student!.StudentNumber,
record.Student.Name,
ClassName = record.Student.AdministrativeClass!.Name,
record.RegularScore,
record.MidtermScore,
record.FinalScore,
record.TotalScore,
record.GradePoint,
record.ExamStatus,
record.Notes,
record.UpdatedAt
}),
x.CreatedAt,
x.UpdatedAt
})
.FirstOrDefaultAsync(cancellationToken);
if (sheet is null) return NotFound();
var task = await db.TeachingTasks.AsNoTracking()
.Include(x => x.Teachers)
.ThenInclude(x => x.Teacher)
.SingleAsync(x => x.Id == sheet.TeachingTaskId, cancellationToken);
return Ok(new
{
Sheet = sheet,
CanEdit = CanEditScores(task) &&
sheet.Status is GradeSheetStatus.Draft or GradeSheetStatus.Returned,
CanReview = IsReviewer() && sheet.Status == GradeSheetStatus.Submitted,
CanPublish = IsPublisher() && sheet.Status == GradeSheetStatus.Approved
});
}
[HttpPut("sheets/{id:guid}/weights")]
[Authorize(Roles = SheetUsers)]
public async Task<ActionResult> UpdateWeights(
Guid id,
GradeWeightsRequest request,
CancellationToken cancellationToken)
{
if (!GradeCalculator.AreWeightsValid(
request.RegularWeight,
request.MidtermWeight,
request.FinalWeight))
return ValidationProblem("平时、期中和期末成绩比例必须合计 100%。");
var sheet = await EditableSheetAsync(id, cancellationToken);
if (sheet is null) return NotFound();
if (!CanEditScores(sheet.TeachingTask!)) return Forbid();
if (sheet.Status is not (GradeSheetStatus.Draft or GradeSheetStatus.Returned))
return ConflictProblem("当前状态不能修改成绩构成。");
sheet.RegularWeight = request.RegularWeight;
sheet.MidtermWeight = request.MidtermWeight;
sheet.FinalWeight = request.FinalWeight;
foreach (var record in sheet.Records) Recalculate(sheet, record);
return await SaveAsync(id, false, cancellationToken);
}
[HttpPut("sheets/{id:guid}/records")]
[Authorize(Roles = SheetUsers)]
public async Task<ActionResult> UpdateRecords(
Guid id,
GradeRecordsRequest request,
CancellationToken cancellationToken)
{
var sheet = await EditableSheetAsync(id, cancellationToken);
if (sheet is null) return NotFound();
if (!CanEditScores(sheet.TeachingTask!)) return Forbid();
if (sheet.Status is not (GradeSheetStatus.Draft or GradeSheetStatus.Returned))
return ConflictProblem("成绩单提交后不能继续修改。");
var records = sheet.Records.ToDictionary(x => x.Id);
if (request.Records.Select(x => x.Id).Distinct().Count() != request.Records.Count ||
request.Records.Any(x => !records.ContainsKey(x.Id)))
return ValidationProblem("包含无效或重复的成绩记录。");
foreach (var item in request.Records)
{
if (!ValidScore(item.RegularScore) ||
!ValidScore(item.MidtermScore) ||
!ValidScore(item.FinalScore))
return ValidationProblem("成绩必须在 0—100 分之间。");
var record = records[item.Id];
record.RegularScore = item.RegularScore;
record.MidtermScore = item.MidtermScore;
record.FinalScore = item.FinalScore;
record.ExamStatus = item.ExamStatus;
record.Notes = Normalize(item.Notes);
Recalculate(sheet, record);
}
return await SaveAsync(id, false, cancellationToken);
}
[HttpPost("sheets/{id:guid}/submit")]
[Authorize(Roles = SheetUsers)]
public async Task<ActionResult> Submit(Guid id, CancellationToken cancellationToken)
{
var sheet = await EditableSheetAsync(id, cancellationToken);
if (sheet is null) return NotFound();
if (!CanEditScores(sheet.TeachingTask!)) return Forbid();
if (sheet.Status is not (GradeSheetStatus.Draft or GradeSheetStatus.Returned))
return ConflictProblem("只有草稿或已退回成绩单可以提交。");
if (sheet.Records.Count == 0)
return ConflictProblem("成绩单没有学生记录。");
if (sheet.Records.Any(x =>
x.ExamStatus == GradeExamStatus.Normal &&
!x.TotalScore.HasValue))
return ConflictProblem("仍有学生缺少必填成绩分项,请补充后再提交。");
sheet.Status = GradeSheetStatus.Submitted;
sheet.SubmittedAt = DateTime.UtcNow;
sheet.ReviewComment = null;
return await SaveAsync(id, false, cancellationToken);
}
[HttpPost("sheets/{id:guid}/approve")]
[Authorize(Roles = Reviewers)]
public async Task<ActionResult> Approve(Guid id, CancellationToken cancellationToken)
{
var sheet = await AccessibleSheets().FirstOrDefaultAsync(
x => x.Id == id,
cancellationToken);
if (sheet is null) return NotFound();
if (!IsReviewer()) return Forbid();
if (sheet.Status != GradeSheetStatus.Submitted)
return ConflictProblem("只有待审核成绩单可以通过审核。");
sheet.Status = GradeSheetStatus.Approved;
sheet.ReviewedAt = DateTime.UtcNow;
sheet.ReviewComment = null;
return await SaveAsync(id, false, cancellationToken);
}
[HttpPost("sheets/{id:guid}/return")]
[Authorize(Roles = Reviewers)]
public async Task<ActionResult> Return(
Guid id,
GradeReviewRequest request,
CancellationToken cancellationToken)
{
var sheet = await AccessibleSheets().FirstOrDefaultAsync(
x => x.Id == id,
cancellationToken);
if (sheet is null) return NotFound();
if (!IsReviewer()) return Forbid();
if (sheet.Status != GradeSheetStatus.Submitted)
return ConflictProblem("只有待审核成绩单可以退回。");
if (string.IsNullOrWhiteSpace(request.Comment))
return ValidationProblem("退回时必须填写修改意见。");
sheet.Status = GradeSheetStatus.Returned;
sheet.ReviewedAt = DateTime.UtcNow;
sheet.ReviewComment = request.Comment.Trim();
return await SaveAsync(id, false, cancellationToken);
}
[HttpPost("sheets/{id:guid}/publish")]
[Authorize(Roles = Publishers)]
public async Task<ActionResult> Publish(Guid id, CancellationToken cancellationToken)
{
var sheet = await AccessibleSheets().FirstOrDefaultAsync(
x => x.Id == id,
cancellationToken);
if (sheet is null) return NotFound();
if (!IsPublisher()) return Forbid();
if (sheet.Status != GradeSheetStatus.Approved)
return ConflictProblem("只有审核通过的成绩单可以发布。");
sheet.Status = GradeSheetStatus.Published;
sheet.PublishedAt = DateTime.UtcNow;
return await SaveAsync(id, false, cancellationToken);
}
[HttpGet("student/transcript")]
[Authorize(Roles = SystemRoles.Student)]
public async Task<ActionResult> GetStudentTranscript(
Guid? academicTermId,
CancellationToken cancellationToken)
{
var userId = currentUserDataScope.Current.UserId;
var student = await db.Students.AsNoTracking()
.Where(x => x.UserId == userId)
.Select(x => new
{
x.Id,
x.StudentNumber,
x.Name,
ClassName = x.AdministrativeClass!.Name,
MajorName = x.AdministrativeClass.Major!.Name
})
.FirstOrDefaultAsync(cancellationToken);
if (student is null)
return ConflictProblem("当前账号未关联有效学生档案。");
var source = db.GradeRecords.AsNoTracking()
.Where(x =>
x.StudentId == student.Id &&
x.GradeSheet!.Status == GradeSheetStatus.Published);
if (academicTermId.HasValue)
source = source.Where(x =>
x.GradeSheet!.TeachingTask!.AcademicTermId == academicTermId);
var records = await source
.OrderByDescending(x => x.GradeSheet!.TeachingTask!.AcademicTerm!.StartDate)
.ThenBy(x => x.GradeSheet!.TeachingTask!.Course!.Code)
.Select(x => new
{
x.Id,
AcademicTermId = x.GradeSheet!.TeachingTask!.AcademicTermId,
TermName = x.GradeSheet.TeachingTask.AcademicTerm!.Name,
x.GradeSheet.TeachingTaskId,
x.GradeSheet.TeachingTask.TaskNumber,
CourseCode = x.GradeSheet.TeachingTask.Course!.Code,
CourseName = x.GradeSheet.TeachingTask.Course.Name,
x.GradeSheet.TeachingTask.Course.Credits,
x.TotalScore,
x.GradePoint,
x.ExamStatus,
x.GradeSheet.PublishedAt
})
.ToListAsync(cancellationToken);
return Ok(new { Student = student, Records = records });
}
private IQueryable<TeachingTask> AccessibleTasks()
{
var source = db.TeachingTasks.AsQueryable();
var scope = currentUserDataScope.Current;
if (scope.Scope == DataScope.All) return source;
if (scope.Scope == DataScope.College)
return source.Where(x => x.Course!.CollegeId == scope.RestrictedCollegeId);
if (scope.IsInRole(SystemRoles.Teacher))
return source.Where(x =>
x.Teachers.Any(item => item.Teacher!.UserId == scope.UserId));
return source.Where(_ => false);
}
private IQueryable<GradeSheet> AccessibleSheets() =>
db.GradeSheets.Where(x => AccessibleTasks().Any(task =>
task.Id == x.TeachingTaskId));
private async Task<GradeSheet?> EditableSheetAsync(
Guid id,
CancellationToken cancellationToken) =>
await AccessibleSheets()
.Include(x => x.Records)
.Include(x => x.TeachingTask)
.ThenInclude(x => x!.Teachers)
.ThenInclude(x => x.Teacher)
.FirstOrDefaultAsync(x => x.Id == id, cancellationToken);
private bool CanInitialize(TeachingTask task) =>
currentUserDataScope.Current.IsInRole(SystemRoles.SuperAdmin) ||
currentUserDataScope.Current.IsInRole(SystemRoles.AcademicAdmin) ||
currentUserDataScope.Current.IsInRole(SystemRoles.CollegeAdmin) ||
IsAssignedTeacher(task);
private bool CanEditScores(TeachingTask task) =>
currentUserDataScope.Current.IsInRole(SystemRoles.SuperAdmin) ||
IsAssignedTeacher(task);
private bool IsAssignedTeacher(TeachingTask task) =>
task.Teachers.Any(x =>
x.Teacher?.UserId == currentUserDataScope.Current.UserId);
private bool IsReviewer() =>
currentUserDataScope.Current.IsInRole(SystemRoles.SuperAdmin) ||
currentUserDataScope.Current.IsInRole(SystemRoles.AcademicAdmin) ||
currentUserDataScope.Current.IsInRole(SystemRoles.CollegeAdmin);
private bool IsPublisher() =>
currentUserDataScope.Current.IsInRole(SystemRoles.SuperAdmin) ||
currentUserDataScope.Current.IsInRole(SystemRoles.AcademicAdmin);
private static void Recalculate(GradeSheet sheet, GradeRecord record)
{
record.TotalScore = GradeCalculator.CalculateTotal(
record.RegularScore,
record.MidtermScore,
record.FinalScore,
sheet.RegularWeight,
sheet.MidtermWeight,
sheet.FinalWeight,
record.ExamStatus);
record.GradePoint = GradeCalculator.CalculateGradePoint(record.TotalScore);
}
private static bool ValidScore(decimal? score) =>
!score.HasValue || score.Value is >= 0 and <= 100;
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 GradeSheetRequest(
Guid TeachingTaskId,
[Range(typeof(decimal), "0", "100")] decimal RegularWeight,
[Range(typeof(decimal), "0", "100")] decimal MidtermWeight,
[Range(typeof(decimal), "0", "100")] decimal FinalWeight);
public sealed record GradeWeightsRequest(
[Range(typeof(decimal), "0", "100")] decimal RegularWeight,
[Range(typeof(decimal), "0", "100")] decimal MidtermWeight,
[Range(typeof(decimal), "0", "100")] decimal FinalWeight);
public sealed record GradeRecordsRequest(
IReadOnlyCollection<GradeRecordRequest> Records);
public sealed record GradeRecordRequest(
Guid Id,
decimal? RegularScore,
decimal? MidtermScore,
decimal? FinalScore,
GradeExamStatus ExamStatus,
[MaxLength(300)] string? Notes);
public sealed record GradeReviewRequest(
[MaxLength(500)] string? Comment);