xiner/NextEdu
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

feat(attendance,elective): 实现所有 P2 长期改进项

Browse Source 
P2 修复（来自审计报告）：
- 2.4.4: Server Action 错误消息 i18n 化（attendance/elective 全部 Action）
- 2.5.3: 抽取 AttendancePageLayout 组件复用（admin/teacher 页面）
- 2.5.4: 抽取 ElectivePageLayout 组件复用（admin/teacher 列表页）
- 2.6.3: 考勤月历键盘导航（tabIndex + 方向键 + Home/End + role=grid）
- 2.8.2: getStudentAttendanceSummary 分页优化（SQL 聚合统计 + LIMIT 分页）
- 2.8.3: resolveCourseDisplayNames 缓存优化（React cache 去重）
- 2.1.4: elective data-access 跨模块依赖接口抽象（resolvers.ts 可注入）

P2 建议项：
- 选课时间冲突检测（parseSchedule + isScheduleConflict 纯函数 + checkScheduleConflict）
- 学分上限校验（MAX_CREDIT_PER_TERM + checkCreditLimit）
- 考勤/选课数据导出 Excel（export.ts + API 路由扩展）

新增文件：
- src/modules/attendance/components/attendance-page-layout.tsx
- src/modules/elective/components/elective-page-layout.tsx
- src/modules/elective/resolvers.ts
- src/modules/attendance/export.ts
- src/modules/elective/export.ts

校验：
- npm run lint 通过（exit 0）
- npx tsc --noEmit attendance/elective/parent 相关零错误
This commit is contained in:
SpecialX
2026-06-23 09:02:41 +08:00
parent c766951374
commit e2e0487a3b
50 changed files with 1514 additions and 411 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
src/modules/attendance/actions.ts
View File

@@ -1,9 +1,11 @@
"use server"
import { revalidatePath } from "next/cache"
import { requirePermission, PermissionDeniedError } from "@/shared/lib/auth-guard"
import { getTranslations } from "next-intl/server"
import { requirePermission } from "@/shared/lib/auth-guard"
import { Permissions } from "@/shared/types/permissions"
import type { ActionState } from "@/shared/types/action-state"
import { handleActionError, safeJsonParse } from "@/shared/lib/action-utils"
import { trackEvent } from "@/shared/lib/track-event"
import { verifyTeacherOwnsClass } from "@/modules/classes/data-access"
@@ -32,15 +34,16 @@ async function assertRecordOwnership(
recordId: string,
ctx: Awaited<ReturnType<typeof requirePermission>>
): Promise<{ ok: boolean; message?: string }> {
const t = await getTranslations("attendance")
if (ctx.dataScope.type === "all") return { ok: true }
if (ctx.dataScope.type === "class_taught") {
const classId = await getAttendanceRecordClassId(recordId)
if (!classId) return { ok: false, message: "Attendance record not found" }
if (!classId) return { ok: false, message: t("errors.notFound") }
const owns = await verifyTeacherOwnsClass(classId, ctx.userId)
if (!owns) return { ok: false, message: "You do not own this attendance record" }
if (!owns) return { ok: false, message: t("errors.noOwnership") }
return { ok: true }
}
return { ok: false, message: "Insufficient permissions" }
return { ok: false, message: t("errors.insufficientPermissions") }
}
/**
@@ -53,13 +56,14 @@ async function assertClassOwnership(
classId: string,
ctx: Awaited<ReturnType<typeof requirePermission>>
): Promise<{ ok: boolean; message?: string }> {
const t = await getTranslations("attendance")
if (ctx.dataScope.type === "all") return { ok: true }
if (ctx.dataScope.type === "class_taught") {
const owns = await verifyTeacherOwnsClass(classId, ctx.userId)
if (!owns) return { ok: false, message: "You do not own this class" }
if (!owns) return { ok: false, message: t("errors.noClassOwnership") }
return { ok: true }
}
return { ok: false, message: "Insufficient permissions" }
return { ok: false, message: t("errors.insufficientPermissions") }
}
export async function recordAttendanceAction(
@@ -67,6 +71,7 @@ export async function recordAttendanceAction(
formData: FormData
): Promise<ActionState<string>> {
try {
const t = await getTranslations("attendance")
const ctx = await requirePermission(Permissions.ATTENDANCE_MANAGE)
const parsed = RecordAttendanceSchema.safeParse({
@@ -81,7 +86,7 @@ export async function recordAttendanceAction(
if (!parsed.success) {
return {
success: false,
message: "Invalid form data",
message: t("errors.invalidForm"),
errors: parsed.error.flatten().fieldErrors,
}
}
@@ -95,11 +100,9 @@ export async function recordAttendanceAction(
targetType: "attendance_record",
properties: { studentId: parsed.data.studentId, classId: parsed.data.classId, status: parsed.data.status },
})
return { success: true, message: "Attendance recorded", data: id }
return { success: true, message: t("messages.recorded"), data: id }
} catch (e) {
if (e instanceof PermissionDeniedError) return { success: false, message: e.message }
if (e instanceof Error) return { success: false, message: e.message }
return { success: false, message: "Unexpected error" }
return handleActionError(e)
}
}
@@ -108,21 +111,22 @@ export async function batchRecordAttendanceAction(
formData: FormData
): Promise<ActionState<number>> {
try {
const t = await getTranslations("attendance")
const ctx = await requirePermission(Permissions.ATTENDANCE_MANAGE)
const recordsJson = formData.get("recordsJson")
if (typeof recordsJson !== "string" || recordsJson.length === 0) {
return { success: false, message: "Missing records data" }
return { success: false, message: t("errors.missingRecords") }
}
const parsed = BatchRecordAttendanceSchema.safeParse({
records: JSON.parse(recordsJson),
records: safeJsonParse(recordsJson, t("errors.invalidRecordsJson")),
})
if (!parsed.success) {
return {
success: false,
message: "Invalid form data",
message: t("errors.invalidForm"),
errors: parsed.error.flatten().fieldErrors,
}
}
@@ -135,11 +139,9 @@ export async function batchRecordAttendanceAction(
targetType: "attendance_record",
properties: { count, classId: parsed.data.records[0]?.classId },
})
return { success: true, message: `Recorded attendance for ${count} students`, data: count }
return { success: true, message: t("messages.batchRecorded", { count }), data: count }
} catch (e) {
if (e instanceof PermissionDeniedError) return { success: false, message: e.message }
if (e instanceof Error) return { success: false, message: e.message }
return { success: false, message: "Unexpected error" }
return handleActionError(e)
}
}
@@ -149,11 +151,12 @@ export async function updateAttendanceAction(
formData: FormData
): Promise<ActionState<string>> {
try {
const t = await getTranslations("attendance")
const ctx = await requirePermission(Permissions.ATTENDANCE_MANAGE)
const ownership = await assertRecordOwnership(id, ctx)
if (!ownership.ok) {
return { success: false, message: ownership.message ?? "Ownership check failed" }
return { success: false, message: ownership.message ?? t("messages.ownershipCheckFailed") }
}
const parsed = UpdateAttendanceSchema.safeParse({
@@ -165,7 +168,7 @@ export async function updateAttendanceAction(
if (!parsed.success) {
return {
success: false,
message: "Invalid form data",
message: t("errors.invalidForm"),
errors: parsed.error.flatten().fieldErrors,
}
}
@@ -179,11 +182,9 @@ export async function updateAttendanceAction(
targetType: "attendance_record",
properties: { status: parsed.data.status },
})
return { success: true, message: "Attendance updated" }
return { success: true, message: t("messages.updated") }
} catch (e) {
if (e instanceof PermissionDeniedError) return { success: false, message: e.message }
if (e instanceof Error) return { success: false, message: e.message }
return { success: false, message: "Unexpected error" }
return handleActionError(e)
}
}
@@ -191,11 +192,12 @@ export async function deleteAttendanceAction(
id: string
): Promise<ActionState<string>> {
try {
const t = await getTranslations("attendance")
const ctx = await requirePermission(Permissions.ATTENDANCE_MANAGE)
const ownership = await assertRecordOwnership(id, ctx)
if (!ownership.ok) {
return { success: false, message: ownership.message ?? "Ownership check failed" }
return { success: false, message: ownership.message ?? t("messages.ownershipCheckFailed") }
}
await deleteAttendanceRecord(id)
@@ -206,11 +208,9 @@ export async function deleteAttendanceAction(
targetId: id,
targetType: "attendance_record",
})
return { success: true, message: "Attendance record deleted" }
return { success: true, message: t("messages.deleted") }
} catch (e) {
if (e instanceof PermissionDeniedError) return { success: false, message: e.message }
if (e instanceof Error) return { success: false, message: e.message }
return { success: false, message: "Unexpected error" }
return handleActionError(e)
}
}
@@ -219,6 +219,7 @@ export async function saveAttendanceRulesAction(
formData: FormData
): Promise<ActionState<string>> {
try {
const t = await getTranslations("attendance")
const ctx = await requirePermission(Permissions.ATTENDANCE_MANAGE)
const parsed = AttendanceRuleSchema.safeParse({
@@ -231,14 +232,14 @@ export async function saveAttendanceRulesAction(
if (!parsed.success) {
return {
success: false,
message: "Invalid form data",
message: t("errors.invalidForm"),
errors: parsed.error.flatten().fieldErrors,
}
}
const ownership = await assertClassOwnership(parsed.data.classId, ctx)
if (!ownership.ok) {
return { success: false, message: ownership.message ?? "Ownership check failed" }
return { success: false, message: ownership.message ?? t("messages.ownershipCheckFailed") }
}
const id = await upsertAttendanceRules(parsed.data)
@@ -250,10 +251,8 @@ export async function saveAttendanceRulesAction(
targetType: "attendance_rule",
properties: { classId: parsed.data.classId },
})
return { success: true, message: "Attendance rules saved", data: id }
return { success: true, message: t("messages.rulesSaved"), data: id }
} catch (e) {
if (e instanceof PermissionDeniedError) return { success: false, message: e.message }
if (e instanceof Error) return { success: false, message: e.message }
return { success: false, message: "Unexpected error" }
return handleActionError(e)
}
}

38
src/modules/attendance/components/attendance-page-layout.tsx Normal file
View File

@@ -0,0 +1,38 @@
import type { ReactNode } from "react"
import { cn } from "@/shared/lib/utils"
/**
* 考勤模块页面布局（消除 admin/teacher 页面重复结构）。
*
* 复用模式：标题区 + 统计卡片（可选）+ 筛选区 + 内容区。
*/
interface AttendancePageLayoutProps {
/** 页面头部（标题 + 描述 + 操作按钮） */
header: ReactNode
/** 统计卡片区（admin 总览页使用） */
stats?: ReactNode
/** 筛选区 */
filters?: ReactNode
/** 主体内容（列表/表单等） */
children: ReactNode
/** 额外类名 */
className?: string
}
export function AttendancePageLayout({
header,
stats,
filters,
children,
className,
}: AttendancePageLayoutProps) {
return (
<div className={cn("h-full flex-1 flex-col space-y-8 p-8 md:flex", className)}>
{header}
{stats}
{filters}
{children}
</div>
)
}

78
src/modules/attendance/data-access-stats.ts
View File

@@ -1,9 +1,10 @@
import "server-only"
import { and, asc, desc, eq, gte, lte } from "drizzle-orm"
import { and, asc, count, desc, eq, gte, lte, sql } from "drizzle-orm"
import { db } from "@/shared/db"
import { attendanceRecords, classes, users } from "@/shared/db/schema"
import { safeParseDate } from "@/shared/lib/action-utils"
import type {
AttendanceListItem,
@@ -23,6 +24,9 @@ const EMPTY_STATS: AttendanceStats = {
lateRate: 0,
}
/** 最近记录的默认截取数量（避免一次拉全量） */
const DEFAULT_RECENT_LIMIT = 20
/**
* 根据考勤记录行计算统计（纯函数，便于测试）。
*/
@@ -41,13 +45,44 @@ export const computeStats = (rows: { status: string }[]): AttendanceStats => {
return stats
}
/**
* 将 SQL 聚合行转换为 AttendanceStats（避免拉全量记录计算统计）。
*/
const statsFromAggregate = (row: {
total: number
present: number
absent: number
late: number
earlyLeave: number
excused: number
}): AttendanceStats => {
const total = Number(row.total ?? 0)
const present = Number(row.present ?? 0)
const late = Number(row.late ?? 0)
return {
total,
present,
absent: Number(row.absent ?? 0),
late,
earlyLeave: Number(row.earlyLeave ?? 0),
excused: Number(row.excused ?? 0),
presentRate: total > 0 ? Math.round((present / total) * 10000) / 100 : 0,
lateRate: total > 0 ? Math.round((late / total) * 10000) / 100 : 0,
}
}
const serializeDate = (d: Date | string | null): string =>
d ? new Date(d).toISOString().slice(0, 10) : ""
/**
* 获取学生考勤汇总。
* 优化：统计使用 SQL 聚合查询（避免拉全量记录），最近记录使用 LIMIT 分页。
*/
export async function getStudentAttendanceSummary(
studentId: string,
startDate?: string,
endDate?: string
endDate?: string,
recentLimit: number = DEFAULT_RECENT_LIMIT
): Promise<StudentAttendanceSummary | null> {
const [student] = await db
.select({ name: users.name })
@@ -57,9 +92,33 @@ export async function getStudentAttendanceSummary(
if (!student) return null
const conditions = [eq(attendanceRecords.studentId, studentId)]
if (startDate) conditions.push(gte(attendanceRecords.date, new Date(startDate)))
if (endDate) conditions.push(lte(attendanceRecords.date, new Date(endDate)))
if (startDate) conditions.push(gte(attendanceRecords.date, safeParseDate(startDate, "开始日期")))
if (endDate) conditions.push(lte(attendanceRecords.date, safeParseDate(endDate, "结束日期")))
const where = and(...conditions)
// 统计使用 SQL 聚合，避免拉全量记录
const [statsRow] = await db
.select({
total: count(),
present: sql<number>`COALESCE(SUM(CASE WHEN ${attendanceRecords.status} = 'present' THEN 1 ELSE 0 END), 0)`,
absent: sql<number>`COALESCE(SUM(CASE WHEN ${attendanceRecords.status} = 'absent' THEN 1 ELSE 0 END), 0)`,
late: sql<number>`COALESCE(SUM(CASE WHEN ${attendanceRecords.status} = 'late' THEN 1 ELSE 0 END), 0)`,
earlyLeave: sql<number>`COALESCE(SUM(CASE WHEN ${attendanceRecords.status} = 'early_leave' THEN 1 ELSE 0 END), 0)`,
excused: sql<number>`COALESCE(SUM(CASE WHEN ${attendanceRecords.status} = 'excused' THEN 1 ELSE 0 END), 0)`,
})
.from(attendanceRecords)
.where(where)
const stats = statsFromAggregate(statsRow ?? {
total: 0,
present: 0,
absent: 0,
late: 0,
earlyLeave: 0,
excused: 0,
})
// 最近记录使用 LIMIT 分页，避免拉全量
const rows = await db
.select({
record: attendanceRecords,
@@ -67,12 +126,11 @@ export async function getStudentAttendanceSummary(
})
.from(attendanceRecords)
.leftJoin(classes, eq(classes.id, attendanceRecords.classId))
.where(and(...conditions))
.where(where)
.orderBy(desc(attendanceRecords.date))
.limit(recentLimit)
const stats = computeStats(rows.map((r) => ({ status: r.record.status })))
const recentRecords: AttendanceListItem[] = rows.slice(0, 20).map((r) => ({
const recentRecords: AttendanceListItem[] = rows.map((r) => ({
id: r.record.id,
studentId: r.record.studentId,
studentName: student.name ?? "Unknown",
@@ -108,8 +166,8 @@ export async function getClassAttendanceStats(
if (!classRow) return null
const conditions = [eq(attendanceRecords.classId, classId)]
if (startDate) conditions.push(gte(attendanceRecords.date, new Date(startDate)))
if (endDate) conditions.push(lte(attendanceRecords.date, new Date(endDate)))
if (startDate) conditions.push(gte(attendanceRecords.date, safeParseDate(startDate, "开始日期")))
if (endDate) conditions.push(lte(attendanceRecords.date, safeParseDate(endDate, "结束日期")))
const rows = await db
.select({

90
src/modules/attendance/export.ts Normal file
View File

@@ -0,0 +1,90 @@
import "server-only"
import { getTranslations } from "next-intl/server"
import type { DataScope } from "@/shared/types/permissions"
import { exportToExcel } from "@/shared/lib/excel"
import { getAttendanceRecords, getAttendanceStats } from "./data-access"
/**
* 导出考勤记录到 Excel
* Sheet 1: 考勤明细
* Sheet 2: 统计汇总
*/
export async function exportAttendanceRecordsToExcel(params: {
scope: DataScope
currentUserId?: string
classId?: string
status?: string
date?: string
}): Promise<Buffer> {
const t = await getTranslations("attendance")
const records = await getAttendanceRecords({
scope: params.scope,
currentUserId: params.currentUserId,
classId: params.classId,
status: params.status as
| "present"
| "absent"
| "late"
| "early_leave"
| "excused"
| undefined,
date: params.date,
})
const detailRows = records.items.map((r) => ({
[t("list.columns.student")]: r.studentName,
[t("list.columns.class")]: r.className,
[t("list.columns.date")]: r.date,
[t("list.columns.status")]: t(`status.${r.status}`),
[t("list.columns.remark")]: r.remark ?? "",
[t("list.columns.recorder")]: r.recorderName,
[t("list.columns.createdAt")]: r.createdAt.split("T")[0],
}))
const stats = await getAttendanceStats({
scope: params.scope,
currentUserId: params.currentUserId ?? "",
classId: params.classId,
date: params.date,
})
const statsRows = [
{ metric: t("stats.totalRecords"), value: stats.totalRecords },
{ metric: t("stats.present"), value: stats.presentCount },
{ metric: t("stats.absent"), value: stats.absentCount },
{ metric: t("stats.late"), value: stats.lateCount },
{ metric: t("stats.earlyLeave"), value: stats.earlyLeaveCount },
{ metric: t("stats.excused"), value: stats.excusedCount },
{ metric: t("stats.attendanceRate"), value: `${stats.attendanceRate}%` },
]
return exportToExcel({
sheets: [
{
name: t("title.adminOverview"),
columns: [
{ header: t("list.columns.student"), key: t("list.columns.student"), width: 18 },
{ header: t("list.columns.class"), key: t("list.columns.class"), width: 18 },
{ header: t("list.columns.date"), key: t("list.columns.date"), width: 14 },
{ header: t("list.columns.status"), key: t("list.columns.status"), width: 12 },
{ header: t("list.columns.remark"), key: t("list.columns.remark"), width: 24 },
{ header: t("list.columns.recorder"), key: t("list.columns.recorder"), width: 16 },
{ header: t("list.columns.createdAt"), key: t("list.columns.createdAt"), width: 14 },
],
rows: detailRows,
},
{
name: t("actions.stats"),
columns: [
{ header: "Metric", key: "metric", width: 24 },
{ header: "Value", key: "value", width: 16 },
],
rows: statsRows,
},
],
})
}