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

refactor: P0-1/2/4 解耦修复 - 拆分过耦合文件 + dashboard 解耦

Browse Source
This commit is contained in:
SpecialX
2026-06-18 01:45:55 +08:00
parent 220061d62e
commit 62be0b9404
18 changed files with 2534 additions and 2130 deletions
Download Patch File Download Diff File Expand all files Collapse all files

249
docs/architecture/005_architecture_data.json
View File

@@ -2048,6 +2048,14 @@
"createAiExamAction"
]
},
{
"name": "getExamsDashboardStats",
"signature": "(scope?: DataScope) => Promise<ExamsDashboardStats>",
"purpose": "获取考试仪表盘统计数据(考试总数,支持数据范围过滤)",
"usedBy": [
"dashboard/data-access.getAdminDashboardData"
]
},
{
"name": "omitScheduledAtFromDescription",
"signature": "(description: string | null) => string",
@@ -2535,13 +2543,6 @@
}
],
"dataAccess": [
{
"name": "getTeacherGradeTrends",
"signature": "(teacherId: string, limit?: number) => Promise<TeacherGradeTrendItem[]>",
"usedBy": [
"dashboard (教师仪表盘)"
]
},
{
"name": "getHomeworkAssignments",
"signature": "(params?: { creatorId?, ids?, classId?, scope? }) => Promise<HomeworkAssignmentListItem[]>",
@@ -2571,20 +2572,6 @@
"student/dashboard"
]
},
{
"name": "getStudentDashboardGrades",
"signature": "(studentId: string) => Promise<StudentDashboardGradeProps>",
"usedBy": [
"dashboard/data-access.ts"
]
},
{
"name": "getHomeworkAssignmentAnalytics",
"signature": "(assignmentId: string) => Promise<HomeworkAssignmentAnalytics | null>",
"usedBy": [
"homework错误分析组件"
]
},
{
"name": "getHomeworkAssignmentById",
"signature": "(id: string, scope?: DataScope) => Promise<...>",
@@ -2618,6 +2605,58 @@
]
}
],
"statsService": [
{
"name": "getTeacherGradeTrends",
"file": "stats-service.ts",
"signature": "(teacherId: string, limit?: number) => Promise<TeacherGradeTrendItem[]>",
"purpose": "教师仪表盘年级趋势数据",
"deps": [
"data-access.getAssignmentMaxScoreById"
],
"usedBy": [
"dashboard (教师仪表盘)"
],
"reExportedFrom": "data-access.ts (向后兼容)"
},
{
"name": "getHomeworkAssignmentAnalytics",
"file": "stats-service.ts",
"signature": "(assignmentId: string) => Promise<HomeworkAssignmentAnalytics | null>",
"purpose": "作业整体分析(含题目错误率/错答样本)",
"deps": [
"data-access.isRecord",
"data-access.toQuestionContent"
],
"usedBy": [
"homework错误分析组件"
],
"reExportedFrom": "data-access.ts (向后兼容)"
},
{
"name": "getStudentDashboardGrades",
"file": "stats-service.ts",
"signature": "(studentId: string) => Promise<StudentDashboardGradeProps>",
"purpose": "学生仪表盘成绩(趋势/近期/班级排名)",
"deps": [
"data-access.getAssignmentMaxScoreById"
],
"usedBy": [
"dashboard/data-access.ts"
],
"reExportedFrom": "data-access.ts (向后兼容)"
},
{
"name": "getHomeworkDashboardStats",
"file": "stats-service.ts",
"signature": "(scope?: DataScope) => Promise<HomeworkDashboardStats>",
"purpose": "获取作业仪表盘统计数据(作业数/已发布数/提交数/待批改数,支持数据范围过滤)",
"usedBy": [
"dashboard/data-access.getAdminDashboardData"
],
"reExportedFrom": "data-access.ts (向后兼容)"
}
],
"schema": [
{
"name": "CreateHomeworkAssignmentSchema",
@@ -2941,6 +2980,14 @@
"teacher/questions/page.tsx"
]
},
{
"name": "getQuestionsDashboardStats",
"signature": "() => Promise<QuestionsDashboardStats>",
"purpose": "获取题目仪表盘统计数据(题目总数)",
"usedBy": [
"dashboard/data-access.getAdminDashboardData"
]
},
{
"name": "GetQuestionsParams",
"type": "type",
@@ -3230,6 +3277,14 @@
"usedBy": [
"reorderChaptersAction"
]
},
{
"name": "getTextbooksDashboardStats",
"signature": "() => Promise<TextbooksDashboardStats>",
"purpose": "获取教材仪表盘统计数据(教材总数、章节总数)",
"usedBy": [
"dashboard/data-access.getAdminDashboardData"
]
}
],
"hooks": [
@@ -3618,6 +3673,14 @@
"classes内部"
]
},
{
"name": "getClassesDashboardStats",
"signature": "() => Promise<ClassesDashboardStats>",
"purpose": "获取班级仪表盘统计数据(班级总数)",
"usedBy": [
"dashboard/data-access.getAdminDashboardData"
]
},
{
"name": "createTeacherClass",
"signature": "(input) => Promise<string>",
@@ -4005,7 +4068,83 @@
"purpose": "班级作业组件"
}
]
}
},
"files": [
{
"path": "data-access.ts",
"lines": 656,
"description": "核心班级 CRUD + 邀请码 + 教师班级管理（含 re-export 向后兼容）",
"exports": [
"getTeacherClasses",
"getTeacherOptions",
"getTeacherTeachingSubjects",
"createTeacherClass",
"ensureClassInvitationCode",
"regenerateClassInvitationCode",
"enrollStudentByInvitationCode",
"enrollTeacherByInvitationCode",
"updateTeacherClass",
"setClassSubjectTeachers",
"deleteTeacherClass",
"enrollStudentByEmail",
"setStudentEnrollmentStatus",
"getSessionTeacherId",
"getTeacherIdForMutations",
"getAccessibleClassIdsForTeacher",
"getTeacherSubjectIdsForClass",
"getClassSubjects",
"compareClassLike",
"isDuplicateInvitationCodeError",
"generateUniqueInvitationCode"
]
},
{
"path": "data-access-stats.ts",
"lines": 604,
"description": "作业统计查询（班级/年级作业洞察）",
"exports": [
"getClassHomeworkInsights",
"getGradeHomeworkInsights",
"getClassesDashboardStats"
]
},
{
"path": "data-access-schedule.ts",
"lines": 230,
"description": "课表查询（学生/班级课表 CRUD）",
"exports": [
"getStudentSchedule",
"getClassSchedule",
"createClassScheduleItem",
"updateClassScheduleItem",
"deleteClassScheduleItem"
]
},
{
"path": "data-access-students.ts",
"lines": 280,
"description": "学生相关查询（科目成绩、学生名单、学生班级）",
"exports": [
"getStudentsSubjectScores",
"getClassStudentSubjectScoresV2",
"getStudentClasses",
"getClassStudents"
]
},
{
"path": "data-access-admin.ts",
"lines": 441,
"description": "管理员班级管理（管理员班级 CRUD、年级管理班级查询）",
"exports": [
"getAdminClasses",
"getGradeManagedClasses",
"getManagedGrades",
"createAdminClass",
"updateAdminClass",
"deleteAdminClass"
]
}
]
},
"school": {
"path": "src/modules/school",
@@ -4250,7 +4389,12 @@
"name": "getAdminDashboardData",
"signature": "(scope?: DataScope) => Promise<AdminDashboardData>",
"deps": [
"shared/db",
"users/data-access.getUsersDashboardStats",
"classes/data-access.getClassesDashboardStats",
"textbooks/data-access.getTextbooksDashboardStats",
"questions/data-access.getQuestionsDashboardStats",
"exams/data-access.getExamsDashboardStats",
"homework/stats-service.getHomeworkDashboardStats",
"DataScope"
],
"usedBy": [
@@ -4655,11 +4799,32 @@
"shared.db.schema.users"
]
},
{
"name": "getUsersDashboardStats",
"signature": "() => Promise<UsersDashboardStats>",
"file": "data-access.ts",
"deps": [
"shared.db",
"shared.db.schema.users",
"shared.db.schema.sessions",
"shared.db.schema.usersToRoles",
"shared.db.schema.roles"
],
"usedBy": [
"dashboard/data-access.getAdminDashboardData"
]
},
{
"name": "UserProfile",
"type": "type",
"file": "data-access.ts",
"definition": "{ id, name, email, image, role, phone, address, gender, age, onboardedAt, createdAt, updatedAt }"
},
{
"name": "UsersDashboardStats",
"type": "type",
"file": "data-access.ts",
"definition": "{ userCount, activeSessionsCount, userRoleCounts, recentUsers }"
}
],
"importExport": [
@@ -10527,38 +10692,38 @@
{
"from": "dashboard",
"to": "exams",
"type": "violation",
"description": "直接查询 exams 表(违规)"
"type": "data-access",
"description": "调用 getExamsDashboardStats 获取考试统计(P0-4 已修复)"
},
{
"from": "dashboard",
"to": "homework",
"type": "violation",
"description": "直接查询 homeworkAssignments/homeworkSubmissions 表(违规)"
"type": "data-access",
"description": "调用 getHomeworkDashboardStats 获取作业统计(P0-4 已修复)"
},
{
"from": "dashboard",
"to": "classes",
"type": "violation",
"description": "直接查询 classes 表(违规)"
"type": "data-access",
"description": "调用 getClassesDashboardStats 获取班级统计(P0-4 已修复)"
},
{
"from": "dashboard",
"to": "users",
"type": "violation",
"description": "直接查询 sessions/users/usersToRoles/roles 表(违规)"
"type": "data-access",
"description": "调用 getUsersDashboardStats 获取用户/会话/角色统计(P0-4 已修复)"
},
{
"from": "dashboard",
"to": "textbooks",
"type": "violation",
"description": "直接查询 textbooks/chapters 表(违规)"
"type": "data-access",
"description": "调用 getTextbooksDashboardStats 获取教材/章节统计(P0-4 已修复)"
},
{
"from": "dashboard",
"to": "questions",
"type": "violation",
"description": "直接查询 questions 表(违规)"
"type": "data-access",
"description": "调用 getQuestionsDashboardStats 获取题目统计(P0-4 已修复)"
},
{
"from": "messaging",
@@ -10714,7 +10879,10 @@
"file": "src/modules/classes/data-access.ts",
"lines": 2104,
"problem": "混入 homework/scheduling/grades 逻辑,严重违反模块职责单一原则",
"suggestion": "按职责拆分为 class-query/schedule/homework-insights/grade-query"
"suggestion": "按职责拆分为 class-query/schedule/homework-insights/grade-query",
"status": "resolved",
"resolvedAt": "2026-06-17",
"resolution": "拆分为 5 个文件：data-access.ts(656行,核心CRUD+邀请码+教师班级管理) + data-access-stats.ts(604行,作业统计) + data-access-schedule.ts(230行,课表) + data-access-students.ts(280行,学生查询) + data-access-admin.ts(441行,管理员班级管理)，所有文件均 ≤800 行，data-access.ts 通过 re-export 保持向后兼容"
},
{
"id": "P0-2",
@@ -10723,7 +10891,10 @@
"file": "src/modules/homework/data-access.ts",
"lines": 1038,
"problem": "混入排名计算业务逻辑",
"suggestion": "分离排名逻辑到独立文件(如 data-access-ranking.ts)"
"suggestion": "分离排名逻辑到独立文件(如 data-access-ranking.ts)",
"status": "resolved",
"resolvedAt": "2026-06-17",
"resolution": "拆分为 data-access.ts(596行) + stats-service.ts(346行)，统计函数(getTeacherGradeTrends/getHomeworkAssignmentAnalytics/getStudentDashboardGrades)迁移至 stats-service.ts，data-access.ts 通过 re-export 保持向后兼容"
},
{
"id": "P0-3",
@@ -10739,7 +10910,9 @@
"title": "dashboard 跨模块直接查询 11 张表",
"file": "src/modules/dashboard/data-access.ts",
"problem": "getAdminDashboardData 直查 sessions/users/classes/textbooks/chapters/questions/exams/homeworkAssignments/homeworkSubmissions/usersToRoles/roles,严重违反模块封装",
"suggestion": "改为通过各模块 data-access 获取数据"
"suggestion": "改为通过各模块 data-access 获取数据",
"status": "fixed",
"fixedBy": "新增 getUsersDashboardStats/getClassesDashboardStats/getTextbooksDashboardStats/getQuestionsDashboardStats/getExamsDashboardStats/getHomeworkDashboardStats,dashboard 改为并行调用各模块 stats 函数"
},
{
"id": "P0-5",