从0到1课后辅导管理系统开发实战：需求文档、架构设计全复盘

课后辅导管理系统的开发难点并不在某个单一技术点，而在于将线下机构分散的业务流程------排课、签到、课消、学员请假、教师考勤------完整地数字化。本文基于实际项目复盘，从需求文档编写到架构设计，完整梳理一个课后辅导管理系统的诞生过程，帮助准备自研或二次开发的团队少走弯路。

一、课后辅导管理系统的核心需求梳理

课后辅导管理的本质是"人、课、钱"三者的高效协同。在动手写代码之前，需求文档必须明确回答以下问题：

**角色权限边界**：系统涉及管理员、授课教师、学员（或家长）、财务人员四类角色。管理员关注整体运营数据，教师只需要看到自己的课表与学员名单，学员/家长关心剩余课时和课程评价。权限设计应采用RBAC模型，预置角色并支持细粒度权限分配。
**消息触达机制**：教师调课通知、学员上课提醒、课时不足预警，这些场景都需要消息推送。在需求文档中应定义消息模板、触发时机和推送渠道（短信/公众号模板消息/App Push），并预留对接第三方短信服务的接口。
**数据统计维度**：管理后台必须提供多维度报表，包括教师授课课时统计、学员出勤率、课程消耗速度、满班率等。需求文档中应明确统计口径和时间粒度（日/周/月）。

二、技术选型与整体架构设计

课后辅导管理系统属于典型的中小型业务系统，技术选型不宜过度复杂，应以快速迭代和维护成本为前提。参考成熟项目案例，建议采用以下技术组合：

**后端服务**：Spring Boot + MyBatis Plus + MySQL，提供RESTful API，使用JWT做身份认证。
**用户端**：采用UniApp（Vue语法）开发，一套代码适配小程序、H5和App，降低多端维护成本。
**管理后台**：Vue + Element UI，基于Vite构建，通过动态路由根据用户权限渲染菜单。
**定时任务**：使用Spring Schedule + Redis分布式锁，处理上课前提醒、课时不足预警等周期性任务。

整体架构分为表现层、应用层、领域层和基础设施层。表现层包括用户端小程序/App、管理后台Web；应用层提供接口服务、定时任务、消息推送服务；领域层沉淀核心业务实体；基础设施层依赖MySQL、Redis、MinIO（用于课件和头像存储）。

这里需要特别强调**接口幂等性**设计。课时核销接口可能因网络原因被重复调用，导致学员课时被多次扣除。解决方案是在核心接口设计中引入业务ID（如排课ID+签到时间），通过数据库索引或Redis SETNX命令保证请求幂等。

三、数据库设计要点与核心表结构

数据库设计决定了系统的扩展性。课后辅导管理系统至少需要以下核心表：学员表、教师表、课程表、班级表（关联学员和课程）、排课表、签到记录表、课时流水表、请假调课申请表。

以排课表为例，需要同时支持固定排课（每周固定时间）和临时排课（一次性调课），建议采用以下字段结构：

java 复制代码

```sql
CREATE TABLE `course_schedule` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT,
  `course_id` bigint(20) NOT NULL COMMENT '课程ID',
  `teacher_id` bigint(20) NOT NULL COMMENT '授课教师ID',
  `classroom_id` bigint(20) DEFAULT NULL COMMENT '教室ID',
  `schedule_date` date NOT NULL COMMENT '上课日期',
  `start_time` time NOT NULL COMMENT '开始时间',
  `end_time` time NOT NULL COMMENT '结束时间',
  `schedule_type` tinyint(1) NOT NULL DEFAULT '1' COMMENT '1-固定排课 2-临时排课',
  `status` tinyint(1) NOT NULL DEFAULT '0' COMMENT '0-待上课 1-已完成 2-已取消',
  `source_schedule_id` bigint(20) DEFAULT NULL COMMENT '补课来源排课ID',
  PRIMARY KEY (`id`),
  KEY `idx_teacher_date` (`teacher_id`, `schedule_date`),
  KEY `idx_course_date` (`course_id`, `schedule_date`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='排课表';
```

课时流水表是财务对账的关键，建议通过流水记录每次课消，保留操作前后的课时余额快照，便于追溯：

java 复制代码

```sql
CREATE TABLE `lesson_flow` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT,
  `student_id` bigint(20) NOT NULL COMMENT '学员ID',
  `schedule_id` bigint(20) NOT NULL COMMENT '排课ID',
  `change_amount` decimal(10,2) NOT NULL COMMENT '变动课时数',
  `before_balance` decimal(10,2) NOT NULL COMMENT '操作前剩余课时',
  `after_balance` decimal(10,2) NOT NULL COMMENT '操作后剩余课时',
  `created_by` varchar(50) NOT NULL COMMENT '操作人',
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='课时流水表';
```

四、核心功能模块实现与踩坑复盘

**1. 排课模块------时间冲突检测**

这是整个系统中业务复杂度的模块，稍微考虑不周就会导致教师或教室时间冲突。实现时先查出该教师在同一天所有未取消的排课记录，然后做时间段重叠判断。需要注意两个容易忽略的边界场景：课程结束时间恰好等于另一节课的开始时间（重叠区间为左闭右开）；以及跨天排课（如晚上22:00-23:30，需要考虑跨日情况）。

java 复制代码

```java
public boolean checkTeacherAvailable(Long teacherId, LocalDate date, LocalTime start, LocalTime end) {
    List<CourseSchedule> existSchedules = scheduleMapper.selectList(
        new LambdaQueryWrapper<CourseSchedule>()
            .eq(CourseSchedule::getTeacherId, teacherId)
            .eq(CourseSchedule::getScheduleDate, date)
            .eq(CourseSchedule::getStatus, 0)  // 待上课状态才冲突
    );
    for (CourseSchedule s : existSchedules) {
        // 使用 isBefore 和 isAfter 处理边界
        if (start.isBefore(s.getEndTime()) && end.isAfter(s.getStartTime())) {
            return false;
        }
    }
    return true;
}
```

**2. 课时核销模块------事务与并发控制**

签到操作同时涉及多张表的更新：修改排课表状态、生成签到记录、扣减学员剩余课时、写入课时流水表。整个流程必须放在一个数据库事务中，并对学员课时余额采用乐观锁控制。

java 复制代码

```java
@Transactional(rollbackFor = Exception.class)
public void signIn(SignInRequest request) {
    // 1. 设置排课状态为已完成
    // 2. 创建签到记录
    // 3. 扣减课时（注意使用乐观锁 version 字段）
    int affectedRows = studentMapper.deductLessonBalance(studentId, lessonCount, expectedVersion);
    if (affectedRows == 0) {
        throw new ServiceException("课时余额已被其他请求修改，请重试");
    }
    // 4. 写入课时流水
}
```

**3. 请假调课模块------状态机设计**

请假调课涉及排课状态和学员课时的联动变化。建议将排课状态设计为状态机：待上课→学员请假（课时冻结）→调课/补课（生成新排课）→完成。不建议直接删除原排课记录，而是保留状态标记，方便后续财务核对。

**4. 消息推送------可靠性与去重**

上课提醒需要提前一段时间推送，使用Spring Schedule定时扫描"待上课"状态的排课记录，生成推送任务。为了避免消息重复推送，引入推送日志表记录已推送的业务ID，同时在Redis中缓存去重Key，设置过期时间。

五、部署上线与复盘思考

系统采用前后端分离部署，后端服务打jar包后部署在云服务器，前端静态资源部署至Nginx。通过Caddy或Nginx配置HTTPS证书，保证小程序请求的合法性。MySQL建议每天凌晨执行自动备份，同时开启binlog用于增量恢复。

项目初版上线后的经验教训是：**不要把业务规则写死在代码里**。比如"请假超过3次自动隐藏课程"这类规则，不同机构的管理规定差异极大，合理做法是将规则参数化，在后台提供配置项。这类业务规则的频繁变更几乎无法避免，保持系统灵活性远比追求代码简洁更重要。

附：课后辅导管理系统开发FAQ

**Q1：课后辅导管理系统需要具备哪些功能模块？**

至少包含学员管理、教师管理、课程管理、排课管理、签到课时核销、请假调课、消息通知、财务管理（课时流水）和统计报表九大模块。可根据机构规模增加线下面授课分组和家长端查看功能。

**Q2：技术选型上如何做取舍？**

中小型系统优先选择Spring Boot + MyBatis Plus + MySQL的成熟组合，用户端使用UniApp实现多端复用，管理后台用Vue + ElementUI。这套技术栈社区资料丰富、招人方便，适合作为版系统的基础架构。

**Q3：排课模块的冲突检测怎么做？**

核心是查询同一天同一教师的所有有效排课，逐一判断时间段是否重叠。注意边界条件：结束时间等于开始时间不算冲突，跨天排课要特殊处理，补课排课还要排除原排课时间段的冲突。

**Q4：课时余额并发扣减问题如何处理？**

为学员表增加`version`字段（乐观锁），在更新余额的SQL语句中携带`WHERE version = #{expectedVersion}`，受影响行数为0则提示重试。同时通过数据库索引（如`student_id + schedule_id`）保证课时流水记录不能重复插入。

**Q5：如何保证系统后续的可扩展性？**

通过接口设计隔离业务差异：例如课时计费规则可以设计成策略模式，不同课程类型实现不同的课时计算接口。消息推送模块预留回调机制，方便接入企业或第三方服务。数据库层面将固定字段与扩展字段分离，避免频繁的DDL变更。