# cgms2025

**Repository Path**: vasant759/cgms2025

## Basic Information

- **Project Name**: cgms2025
- **Description**: 信息系统开发实践项目——成绩管理系统
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-25
- **Last Updated**: 2025-11-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: React, Postgresql, SPA

## README

# cgms2025

信息系统开发实践项目——成绩管理系统

## 项目说明

在[信息系统开发课程课内项目《成绩管理系统》](https://gitee.com/lyucg/isdev)的 cgms3 基础上，增加或完善下来内容：

1. [ x ]**完善课程基础信息**（任务 3）：课程号、课程名、学分、学时
   - 依赖关系：无
   - 用户角色：教秘
2. [ x ] **课程分班次功能**（任务 1、2、4）：设置系统的使用对象是“教秘”；班次包含班次号、班次名、学期、地点、课程
   - 依赖关系：需要课程基础信息
   - 功能说明：
     1. 创建班次：班次号、班次名、学期、地点、课程
     2. 班次管理：增删改查班次信息
     3. 用户角色：教秘
3. [ x ] **选课功能**（任务 5）：1. 教秘选择某班次 → 2. 从学生列表中勾选学生 → 3. 提交关联。（任务 5）
   - 依赖关系：需要班次管理功能
4. [ x ] **成绩录入**（任务 6）：按班次录入成绩，注意考虑易用性设计
   - 依赖关系：需要选课功能
5. [ x ] **成绩查询**（任务 7）：查询某课程某班次或某学期的所有学生成绩
   - 依赖关系：需要成绩录入功能
6. [ x ] **报表生成**（任务 8）：列出某个学生所有成绩生成报表
   - 依赖关系：需要成绩查询功能

## 项目个人工作总结

### 洪菁曼（vasant759）

1. **核心权限系统开发（v4.0.0）**

   - 实现教秘用户认证体系，开发`login.py`中的 JWT 令牌签发逻辑
   - 设计 RBAC 权限模型，在数据库脚本`1_table.sql`中创建 sys_users 表结构，`user_passwords`表的`hashed_password`字段存储 bcrypt hash 加密后的密码
   - 前端设计登录页面和路由跳转逻辑，当无登录状态时访问根目录时，跳转到登录页；当有登录状态时访问根目录时，跳转到主页面
   - 教秘登录时调用`/api/login`接口，生成有效期为 60 分钟的访问令牌

2. **学生成绩报表系统（v4.5.0）**

   - 直接面向用户的 PDF/Excel 双模式导出功能，例如教秘在学生详情的“成绩档案栏”点击"导出 PDF"按钮，将触发`/api/student/{stu_sn}/report/export?format=pdf`请求，生成包含加权平均分的成绩单 PDF，文件命名规则`学生成绩_学号_日期.pdf`
   - Excel 模板使用`xlsxwriter`库动态生成带格式的单元格

3. **班次管理功能开发（v4.1.0）**

   - 重构班次号生成算法，在`course_class.py`使用正则表达式实现`class_no`的"课程号-年份学期-序号"格式验证，例如班次号`10055-2023S1-01`表示 2023 级第 1 学期第 01 个班次
   - 开发班次信息修改接口，前端通过`ClassDetail.jsx`的表单校验，限制仅允许修改地点字段

4. **选课冲突检测（v4.2.0）**

   - 冲突校验逻辑：同一学生不能同时选择同一课程的多个班次
   - 存在冲突的学生在班次详情的“学生管理”栏中以红色背景高亮，提示"冲突（不可选）"状态，并且不开放选择按钮

5. **多维度成绩查询（v4.4.0）**

   - 设计多级查询 API，在`appserv/serv/grade.py`开发支持课程（+班次/学期）组合查询的`query_grades`接口
   - 优化数据库索引，为 class 表添加 semester 字段索引

6. **课程基础信息模块（v3.5.0）**
   - 设计课程数据库结构，其中课程号首两位表示课程类型（但未具体设计，仅做一种初步逻辑）
   - 开发课程信息表单组件`webapp/src/course/CourseDetail.jsx`
   - 示例：课程号`10055`表示 10 类（基础课）055 号课程
7. **样式模块迁移与逻辑修复（v4.6.0）**待优化
   - 尝试 CSS in JS 的 styled-components 以对复杂的 css 全局样式进行管理，但是未完全生效，且前端代码复杂性更高了。
   - 将自设样式应用于 Ant Design 的分页、按钮组件，调整配色未全部完成，页面整体样式欠妥。

### 安雨琪（安 7）

1.  实现了一个 Excel 文件处理模块，主要功能包括。
    (1).下载模板文件（通过 API 获取）；
    (2).解析上传的 Excel 文件（验证格式并转为 JSON）；
    (3).提交导入数据到后端（处理结果并更新前端状态）。
    核心是完成从 Excel 到数据库的数据导入流程，包含完整的前后端交互和错误处理机制。
2.  重构课程与学生模型，更新组件调整数据（依靠数据库的知识）主要就是实现对后端的修改，对数据库关系的修改，让数据存储更严谨。
    (1)student：sn 从 10000 开始自增 1；no 为入学年份、专业代码、班级号、班内序号组成，比如 23 065 01 18；gender 以 F、M、O 存储
    (2)course：sn 从 20000 开始自增 1；no 为课程类型、课程内序号，比如 10055 class：班次号为 course.no-入学年份，比如 10055-2023，体现 2023 级的学生上 10055 课程；semester 为学期，比如 2024-2025-1；关联课程号；约束班次号内有课程号
    (3)grade：sn 尚未规定自增，默认为 1 开始；外联 student 和 course 的 sn 为联合主键
    例如：('10055-2023', '高等数学', '2023-2024-1', '教学楼 A201'),
3.  隐藏的`<input type="file">`用于触发 Excel 文件选择，选择后自动解析数据并显示预览；模态框展示解析后的数据表格，用颜色标记异常成绩（红色=空值，橙色=超范围，绿色=正常），用户确认后执行导入操作。实现了从文件选择到数据预览再到最终导入的完整流程。

### 陈旭（chen）

1.  优化唯一性约束并改进学生信息维护逻辑：更新维护数据库外键等
2.  实现批量成绩更新 API 及成绩录入界面：在班次详情页添加成绩录入标签页，批量更新成绩记录，自动处理插入和更新等
3.  重构课程学生模型，删学期字段
4.  增编号学分等验证，调整数据处理，student 和 course 的全栈调整：课程号必须为 5 位数字，学分必须大于 0，学时必须大于 0 等

### 刘奕嘉（咖啡要加糖）

1.  优化体验，增强 Excel 导入功能，支持英文字段映射，并优化数据处理。
2.  增强模板下载和导入验证功能，修改文件上传处理，获取文件名并添加错误处理机制，新增弹窗关闭处理函数。
3.  重构课程与学生模型，增验证、删学期字段，修改  SQL 查询语句，从数据库中获取学生成绩信息；提供了对学生课程成绩的查询、创建、更新和删除功能；使用 SQL 创建学生表、班次表、成绩表；React 组件，用于在网页上展示学生成绩表格，并与后端 API 交互获取数据；外联 student 和 course 的 sn 为联合主键。
4.  增加数据库数据内容。

## 项目完成情况（按版本排序）

### 任务 3 ：完善课程信息。 ==v3.5.0==

- /dbscripts：course 包含课程号、课程名、学分、学时字段；
- /appserv：course.py 实现了课程信息的 CRUD 接口；
- /webapp：CourseDetail.jsx 包含课程号、课程名、学分、学时的表单组件

### 整体 DEBUG ==v3.6.0==：

- /webapp：参照 student 和 course 现有的组件结构，添加了 grade 的对应基础供后续开发；更新导航菜单
- /appserv：增加 student，course，grade 的字段格式认证，对应 CRUD 接口重构和修改传入字段以与前端对应
- /dbscripts：数据库表结构更新
  - student：sn 从 10000 开始自增 1；no 为入学年份、专业代码、班级号、班内序号组成，比如 23 065 01 18；gender 以 F、M、O 存储
  - course：sn 从 20000 开始自增 1；no 为课程类型、课程内序号，比如 10055
    class：班次号为 course.no-入学年份，比如 10055-2023，体现 2023 级的学生上 10055 课程；semester 为学期，比如 2024-2025-1；关联课程号；约束班次号内有课程号
  - grade：sn 尚未规定自增，默认为 1 开始；外联 student 和 course 的 sn 为联合主键

### 任务 1：设置教秘用户角色及登录权限。==v4.0.0==

- 用户名: jiaomi_admin 密码: Admin@1234

- 因开发需要，将.env.example 文件重命名为.env，然后修改.env 文件中的 DATABASE_URL 为自己的数据库连接地址。
  ├── appserv/
  │ ├── .env # 实际使用的环境变量
  │ ├── .env.example # 示例模板
  │ └── serv/

  - 配置方式：

    1. 进入后端目录 `cd appserv`

    2. 一键生成密钥并创建 .env（Windows PowerShell）

       ```powershell
       openssl rand -hex 32 | Out-File -Encoding utf8 .env

       Get-Content .env.example | Add-Content .env
       ```

    3. 进入.env 中修改

       把 your_32byte_random_string_here 替换成第一行的一串码，删除第一行的码

### 任务 2 & 4：班次增删改查与表单自动填写逻辑。==v4.1.0==

- 班次号逻辑修改成：'课程号-年份学期-序号'（如 10055-2023S1-01）

- 修改班次信息时，只允许修改地点字段

- 增加登录状态检验

### 任务 5：某一班次详情下的学生管理栏。 ==v4.2.0==

- 添加缓存，修改身份认证方法，提供分页（待优化）
- /dbscripts：class_student 包含班级序号、学生序号、选课时间
- /appserv：selection.py 具体实现了选课时的逻辑查询（可选学生、是否有学生已在当前课程其余班次的冲突情况）
- /webapp： ClassStudentSelection.jsx 融入 ClassDetail.jsx 中，在原有的编辑班次界面进行分栏（基本信息、学生管理），区分可选和有冲突的学生。

### 任务 6：班次录入成绩。 ==v4.3.0==

- /webapp：班次成绩录入界面：表格形式展示学生名单，支持在线批量成绩输入与保存
- /appserv：批量成绩更新，学生成绩查询
- 可下载成绩导入模板 Excel，具有验证模板文件逻辑

1.  **实时协作增强**
    - 自动保存防抖机制（30 秒阈值可配置）
    - 数据版本冲突检测（30 秒轮询校验）
    - 离开页面警告提示（防止数据丢失）
2.  **Excel 导入增强**
    - 动态模板文件名验证（包含班次编号和名称）
    - 成绩有效性实时校验（0-100 范围检查）
    - 错误行高亮显示（含具体错误原因）
    - 导入结果统计面板（成功/失败计数）
3.  **用户体验优化**

    - 自动保存倒计时可视化
    - 批量保存防重复点击
    - 输入状态持久化（基于 localStorage）
    - 表格固定列优化（学号列始终可见）

4.  **数据完整性保障**
    - 基准数据快照机制（Map 存储初始值）
    - 双重防抖策略（输入防抖 + 保存节流）
    - 服务端版本校验（通过 check-conflict API 实现）
    - 数据完整性校验（前端 + 后端）

### 任务 7：成绩查询。 ==v4.4.0==

- /webapp：默认输出所有学生成绩，支持课程单查询和课程＋班次/学期双查询
- /appserv：学生成绩多级查询 API
- /dbscripts：优化成绩查询索引

### 任务 8：单个学生的成绩报表。 ==v4.5.0==

- /webapp：保持 SPA 架构（更换成绩录入的模板导出使用的 window.open 方法）；添加学生报表栏的前端设计
- /appserv：对导出 Excel/PDF 的处理，和生成学生报表的后端处理
- /dbscripts：添加 class_student 的更新时间戳，新增视图 student_grade_report

## 项目开发过程分支

1. v3.5.0
   - feature/course-basic-info
2. v3.6.0
   - feat/sql-info-debug
   - feat/stu_cou-info-debug
   - feat/grade-info-debug
3. v4.0.0
   - feat/login-auth
4. v4.1.0
   - feat/course-class-scheduling
5. v4.2.0
   - feat/student-selection
6. v4.3.0
   - feat/grade-entry
7. v4.4.0

   - feat/grade-query

8. v4.5.0
   - feat/stu-report-generation
9. v4.6.0
   - refactor/core-UI-debug