docs: 全文档合规检查与修正 - 代码示例规范/行数准确性/路径一致性/状态同步

2026-06-18 03:31:07 +08:00
parent 0423b2b984
commit 4d659ad9a1
18 changed files with 595 additions and 522 deletions
--- a/docs/design/004_question_bank_implementation.md
+++ b/docs/design/004_question_bank_implementation.md
@@ -145,12 +145,12 @@ type QuestionContent = {
 ### 7.1 登录态与权限校验
 - 题库创建/更新/知识点加载统一使用会话身份；缺失会话时回退到首个教师账号以保持演示可用。
 - 主要修改：
-  - [actions.ts](file:///c:/Users/xiner/Desktop/CICD/src/modules/questions/actions.ts)
+  - [actions.ts](file:///e:/Desktop/CICD/src/modules/questions/actions.ts)

 ### 7.2 弹窗稳定性
 - Create Question 弹窗在打开时仅在默认知识点变化时更新，避免重复 setState 造成循环更新。
 - 主要修改：
-  - [create-question-dialog.tsx](file:///c:/Users/xiner/Desktop/CICD/src/modules/questions/components/create-question-dialog.tsx)
+  - [create-question-dialog.tsx](file:///e:/Desktop/CICD/src/modules/questions/components/create-question-dialog.tsx)

 ### 7.3 校验
 - `npm run lint`：通过
--- a/docs/design/005_exam_module_implementation.md
+++ b/docs/design/005_exam_module_implementation.md
@@ -173,7 +173,7 @@ type ExamNode = {

 - **题库列表稳定性**:
  - 题库卡片对题目 content/type 做解析兜底，避免异常数据导致运行时崩溃。
-  - 主要修改： [question-bank-list.tsx](file:///c:/Users/xiner/Desktop/CICD/src/modules/exams/components/assembly/question-bank-list.tsx)
+  - 主要修改： [question-bank-list.tsx](file:///e:/Desktop/CICD/src/modules/exams/components/assembly/question-bank-list.tsx)

 **日期**：2026-01-12 (当前)

--- a/docs/design/006_homework_module_implementation.md
+++ b/docs/design/006_homework_module_implementation.md
@@ -37,7 +37,7 @@
 - `homework_submissions`: 学生作业尝试（attempt_no/status/时间/是否迟交）
 - `homework_answers`: 每题答案（answer_content/score/feedback）

-数据库变更记录见：[schema-changelog.md](file:///c:/Users/xiner/Desktop/CICD/docs/db/schema-changelog.md#L34-L77)
+数据库变更记录见：[schema-changelog.md](file:///e:/Desktop/CICD/docs/db/schema-changelog.md#L34-L77)

 ### 2.2 设计要点：冻结 Exam → Homework Assignment

@@ -52,37 +52,37 @@
 ### 3.1 教师端

 - `/teacher/homework/assignments`: 作业列表  
-  实现：[assignments/page.tsx](file:///c:/Users/xiner/Desktop/CICD/src/app/(dashboard)/teacher/homework/assignments/page.tsx)
+  实现：[assignments/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/homework/assignments/page.tsx)
 - `/teacher/homework/assignments/create`: 从 Exam 派发作业  
-  实现：[create/page.tsx](file:///c:/Users/xiner/Desktop/CICD/src/app/(dashboard)/teacher/homework/assignments/create/page.tsx)
+  实现：[create/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/homework/assignments/create/page.tsx)
 - `/teacher/homework/assignments/[id]`: 作业详情  
-  实现：[[id]/page.tsx](file:///c:/Users/xiner/Desktop/CICD/src/app/(dashboard)/teacher/homework/assignments/%5Bid%5D/page.tsx)
+  实现：[[id]/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/homework/assignments/%5Bid%5D/page.tsx)
 - `/teacher/homework/assignments/[id]/submissions`: 作业提交列表（按作业筛选）  
-  实现：[[id]/submissions/page.tsx](file:///c:/Users/xiner/Desktop/CICD/src/app/(dashboard)/teacher/homework/assignments/%5Bid%5D/submissions/page.tsx)
+  实现：[[id]/submissions/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/homework/assignments/%5Bid%5D/submissions/page.tsx)
 - `/teacher/homework/submissions`: 全部提交列表  
-  实现：[submissions/page.tsx](file:///c:/Users/xiner/Desktop/CICD/src/app/(dashboard)/teacher/homework/submissions/page.tsx)
+  实现：[submissions/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/homework/submissions/page.tsx)
 - `/teacher/homework/submissions/[submissionId]`: 批改页  
-  实现：[[submissionId]/page.tsx](file:///c:/Users/xiner/Desktop/CICD/src/app/(dashboard)/teacher/homework/submissions/%5BsubmissionId%5D/page.tsx)
+  实现：[[submissionId]/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/homework/submissions/%5BsubmissionId%5D/page.tsx)

 关联重定向：

 - `/teacher/exams/grading` → `/teacher/homework/submissions`  
-  实现：[grading/page.tsx](file:///c:/Users/xiner/Desktop/CICD/src/app/(dashboard)/teacher/exams/grading/page.tsx)
+  实现：[grading/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/exams/grading/page.tsx)
 - `/teacher/exams/grading/[submissionId]` → `/teacher/homework/submissions`  
-  实现：[grading/[submissionId]/page.tsx](file:///c:/Users/xiner/Desktop/CICD/src/app/(dashboard)/teacher/exams/grading/%5BsubmissionId%5D/page.tsx)
+  实现：[grading/[submissionId]/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/exams/grading/%5BsubmissionId%5D/page.tsx)

 ### 3.2 学生端

 - `/student/learning/assignments`: 作业列表  
-  实现：[page.tsx](file:///c:/Users/xiner/Desktop/CICD/src/app/(dashboard)/student/learning/assignments/page.tsx)
+  实现：[page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/student/learning/assignments/page.tsx)
 - `/student/learning/assignments/[assignmentId]`: 作答页（开始/保存/提交）  
-  实现：[[assignmentId]/page.tsx](file:///c:/Users/xiner/Desktop/CICD/src/app/(dashboard)/student/learning/assignments/%5BassignmentId%5D/page.tsx)
+  实现：[[assignmentId]/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/student/learning/assignments/%5BassignmentId%5D/page.tsx)

 ---

 ## 4. 数据访问层（Data Access）

-数据访问位于：[data-access.ts](file:///c:/Users/xiner/Desktop/CICD/src/modules/homework/data-access.ts)
+数据访问位于：[data-access.ts](file:///e:/Desktop/CICD/src/modules/homework/data-access.ts)

 ### 4.1 教师侧查询

@@ -106,7 +106,7 @@

 ## 5. Server Actions

-实现位于：[actions.ts](file:///c:/Users/xiner/Desktop/CICD/src/modules/homework/actions.ts)
+实现位于：[actions.ts](file:///e:/Desktop/CICD/src/modules/homework/actions.ts)

 ### 5.1 教师侧

@@ -129,13 +129,13 @@

 ### 6.1 教师批改视图

- [HomeworkGradingView](file:///c:/Users/xiner/Desktop/CICD/src/modules/homework/components/homework-grading-view.tsx)
+- [HomeworkGradingView](file:///e:/Desktop/CICD/src/modules/homework/components/homework-grading-view.tsx)
  - 左侧：学生答案只读展示
  - 右侧：按题录入分数与反馈，并提交批改

 ### 6.2 学生作答视图

- [HomeworkTakeView](file:///c:/Users/xiner/Desktop/CICD/src/modules/homework/components/homework-take-view.tsx)
+- [HomeworkTakeView](file:///e:/Desktop/CICD/src/modules/homework/components/homework-take-view.tsx)
  - Start：开始一次作答
  - Save：按题保存
  - Submit：提交（提交前会先保存当前题目答案）
@@ -147,7 +147,7 @@

 ## 7. 类型定义

-类型位于：[types.ts](file:///c:/Users/xiner/Desktop/CICD/src/modules/homework/types.ts)
+类型位于：[types.ts](file:///e:/Desktop/CICD/src/modules/homework/types.ts)

 - 教师侧：`HomeworkAssignmentListItem` / `HomeworkSubmissionDetails` 等
 - 学生侧：`StudentHomeworkAssignmentListItem` / `StudentHomeworkTakeData` 等
@@ -170,7 +170,7 @@

 ### 9.2 CI 构建与部署（Gitea）

-工作流位于：[ci.yml](file:///c:/Users/xiner/Desktop/CICD/.gitea/workflows/ci.yml)
+工作流位于：[ci.yml](file:///e:/Desktop/CICD/.gitea/workflows/ci.yml)

 - 构建阶段（`npm run build`）不依赖数据库连接：作业相关页面在构建时不会静态预渲染执行查库
 - 部署阶段通过 `docker run -e DATABASE_URL=...` 在运行时注入数据库连接串
@@ -181,7 +181,7 @@

 作业模块相关页面在渲染时会进行数据库查询，因此显式标记为动态渲染以避免构建期预渲染触发数据库连接：

- 教师端作业列表：[assignments/page.tsx](file:///c:/Users/xiner/Desktop/CICD/src/app/(dashboard)/teacher/homework/assignments/page.tsx)
+- 教师端作业列表：[assignments/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/homework/assignments/page.tsx)

 ---

@@ -191,32 +191,32 @@

 将 `/teacher/homework/assignments/[id]` 页面调整为“只负责组装”，把可复用展示逻辑下沉到模块内组件：

- 页面组装：[page.tsx](file:///c:/Users/xiner/Desktop/CICD/src/app/(dashboard)/teacher/homework/assignments/%5Bid%5D/page.tsx)
- 题目错误概览卡片（overview）：[homework-assignment-question-error-overview-card.tsx](file:///c:/Users/xiner/Desktop/CICD/src/modules/homework/components/homework-assignment-question-error-overview-card.tsx)
- 题目错误明细卡片（details）：[homework-assignment-question-error-details-card.tsx](file:///c:/Users/xiner/Desktop/CICD/src/modules/homework/components/homework-assignment-question-error-details-card.tsx)
- 试卷预览/错题工作台容器卡片：[homework-assignment-exam-content-card.tsx](file:///c:/Users/xiner/Desktop/CICD/src/modules/homework/components/homework-assignment-exam-content-card.tsx)
+- 页面组装：[page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/homework/assignments/%5Bid%5D/page.tsx)
+- 题目错误概览卡片（overview）：[homework-assignment-question-error-overview-card.tsx](file:///e:/Desktop/CICD/src/modules/homework/components/homework-assignment-question-error-overview-card.tsx)
+- 题目错误明细卡片（details）：[homework-assignment-question-error-details-card.tsx](file:///e:/Desktop/CICD/src/modules/homework/components/homework-assignment-question-error-details-card.tsx)
+- 试卷预览/错题工作台容器卡片：[homework-assignment-exam-content-card.tsx](file:///e:/Desktop/CICD/src/modules/homework/components/homework-assignment-exam-content-card.tsx)

 ### 10.2 题目点击联动：试卷预览 ↔ 错题详情

 在“试卷预览”中点击题目后，右侧联动展示该题的统计与错答列表（按学生逐条展示，不做合并）：

- 工作台（选择题目、拼装左右面板）：[homework-assignment-exam-error-explorer.tsx](file:///c:/Users/xiner/Desktop/CICD/src/modules/homework/components/homework-assignment-exam-error-explorer.tsx)
- 试卷预览面板（可选中题目）：[homework-assignment-exam-preview-pane.tsx](file:///c:/Users/xiner/Desktop/CICD/src/modules/homework/components/homework-assignment-exam-preview-pane.tsx)
- 错题详情面板（错误人数/错误率/错答列表）：[homework-assignment-question-error-detail-panel.tsx](file:///c:/Users/xiner/Desktop/CICD/src/modules/homework/components/homework-assignment-question-error-detail-panel.tsx)
+- 工作台（选择题目、拼装左右面板）：[homework-assignment-exam-error-explorer.tsx](file:///e:/Desktop/CICD/src/modules/homework/components/homework-assignment-exam-error-explorer.tsx)
+- 试卷预览面板（可选中题目）：[homework-assignment-exam-preview-pane.tsx](file:///e:/Desktop/CICD/src/modules/homework/components/homework-assignment-exam-preview-pane.tsx)
+- 错题详情面板（错误人数/错误率/错答列表）：[homework-assignment-question-error-detail-panel.tsx](file:///e:/Desktop/CICD/src/modules/homework/components/homework-assignment-question-error-detail-panel.tsx)

 ### 10.3 统计数据增强：返回逐学生错答

 为满足“错答列表逐条展示学生姓名 + 答案”的需求，作业统计查询返回每题的错答明细（包含学生信息）：

- 数据访问：[getHomeworkAssignmentAnalytics](file:///c:/Users/xiner/Desktop/CICD/src/modules/homework/data-access.ts)
- 类型定义：[types.ts](file:///c:/Users/xiner/Desktop/CICD/src/modules/homework/types.ts)
+- 数据访问：[getHomeworkAssignmentAnalytics](file:///e:/Desktop/CICD/src/modules/homework/data-access.ts)
+- 类型定义：[types.ts](file:///e:/Desktop/CICD/src/modules/homework/types.ts)

 ### 10.4 加载优化：Client Wrapper 动态分包

 由于 `next/dynamic({ ssr: false })` 不能在 Server Component 内使用，工作台动态加载通过 Client wrapper 进行隔离：

- Client wrapper：[homework-assignment-exam-error-explorer-lazy.tsx](file:///c:/Users/xiner/Desktop/CICD/src/modules/homework/components/homework-assignment-exam-error-explorer-lazy.tsx)
- 入口卡片（Server Component，渲染 wrapper）：[homework-assignment-exam-content-card.tsx](file:///c:/Users/xiner/Desktop/CICD/src/modules/homework/components/homework-assignment-exam-content-card.tsx)
+- Client wrapper：[homework-assignment-exam-error-explorer-lazy.tsx](file:///e:/Desktop/CICD/src/modules/homework/components/homework-assignment-exam-error-explorer-lazy.tsx)
+- 入口卡片（Server Component，渲染 wrapper）：[homework-assignment-exam-content-card.tsx](file:///e:/Desktop/CICD/src/modules/homework/components/homework-assignment-exam-content-card.tsx)

 ### 10.5 校验

@@ -240,7 +240,7 @@

 数据由 Homework 模块统一提供聚合查询，避免页面层拼 SQL：

- 新增查询：[getStudentDashboardGrades](file:///c:/Users/xiner/Desktop/CICD/src/modules/homework/data-access.ts)
+- 新增查询：[getStudentDashboardGrades](file:///e:/Desktop/CICD/src/modules/homework/data-access.ts)
  - `trend`：取该学生所有 `graded` 提交中“每个 assignment 最新一次”的集合，按时间升序取最近 10 个
  - `recent`：对 `trend` 再按时间降序取最近 5 条，用于表格展示
  - `maxScore`：通过 `homework_assignment_questions` 汇总每个 assignment 的总分（SUM(score)）
@@ -255,7 +255,7 @@

 为 Dashboard 聚合数据提供显式类型：

- [types.ts](file:///c:/Users/xiner/Desktop/CICD/src/modules/homework/types.ts)
+- [types.ts](file:///e:/Desktop/CICD/src/modules/homework/types.ts)
  - `StudentHomeworkScoreAnalytics`
  - `StudentRanking`
  - `StudentDashboardGradeProps`
@@ -263,11 +263,11 @@
 ### 11.4 页面与组件接入

 - 学生主页页面负责“取数 + 计算基础计数 + 传参”：
-  - [student/dashboard/page.tsx](file:///c:/Users/xiner/Desktop/CICD/src/app/(dashboard)/student/dashboard/page.tsx)
+  - [student/dashboard/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/student/dashboard/page.tsx)
  - 取数：`getStudentDashboardGrades(student.id)`
  - 传入：`<StudentDashboard grades={grades} />`
 - 展示组件负责渲染卡片：
-  - [student-view.tsx](file:///c:/Users/xiner/Desktop/CICD/src/modules/dashboard/components/student-view.tsx)
+  - [student-view.tsx](file:///e:/Desktop/CICD/src/modules/dashboard/components/student-view.tsx)
  - 趋势图：使用内联 `svg polyline` 渲染折线，避免引入额外图表依赖

 ### 11.5 校验
@@ -319,8 +319,8 @@
 - 提交作业与学生列表查询改为使用真实登录用户，避免提交后仍显示未开始。
 - 学生列表优先展示最近一次已提交/已评分记录，提升状态准确性。
 - 主要修改：
-  - [actions.ts](file:///c:/Users/xiner/Desktop/CICD/src/modules/homework/actions.ts)
-  - [data-access.ts](file:///c:/Users/xiner/Desktop/CICD/src/modules/homework/data-access.ts)
+  - [actions.ts](file:///e:/Desktop/CICD/src/modules/homework/actions.ts)
+  - [data-access.ts](file:///e:/Desktop/CICD/src/modules/homework/data-access.ts)

 ### 14.2 校验
 - `npm run lint`：通过