# class-pet-assistant-backend **Repository Path**: passer111/class-pet-assistant-backend ## Basic Information - **Project Name**: class-pet-assistant-backend - **Description**: 班级宠物助手后端 - **Primary Language**: Java - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-02-24 - **Last Updated**: 2026-02-24 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 班级宠物助手后端（Spring Boot + MyBatis-Plus） ## 技术栈 - **JDK**: 1.8 - **Spring Boot**: 2.7.18 - **MyBatis-Plus**: 3.5.5 - **数据库**: MySQL 8.0+ - **连接池**: Druid 1.2.23 - **JWT**: jjwt 0.12.6 - **API文档**: Knife4j 4.4.0 - **工具**: Hutool 5.8.25（JDK 1.8兼容版本） ## 项目结构 ``` class-pet-assistant-backend/ ├── pom.xml ├── src/main/ │ ├── java/com/classpet/assistant/ │ │ ├── ClassPetAssistantApplication.java │ │ ├── domain/ # 领域层 │ │ │ ├── entity/ # 7个实体 │ │ │ ├── service/ # 领域服务 │ │ ├── mapper/ # 6个Mapper接口 │ │ ├── application/ # 应用服务层 │ │ │ └── service/ # 3个ApplicationService │ │ ├── interfaces/ # 接口层 │ │ │ └── controller/ # 4个Controller │ │ ├── config/ # 配置层 │ │ │ ├── MyMetaObjectHandler.java │ │ │ ├── JwtAuthenticationInterceptor.java │ │ │ ├── JwtUtil.java │ │ │ ├── WebMvcConfig.java │ │ │ └── Knife4jConfig.java │ │ └── common/ # 通用组件 │ │ ├── Result.java # 统一响应封装 │ │ ├── BusinessException.java # 业务异常 │ │ └── GlobalExceptionHandler.java # 全局异常处理 │ └── resources/ │ ├── application.yml # 配置文件 │ └── schema.sql # 数据库初始化脚本 ``` ## 数据库设计 ### 核张核心表 1. **users** - 用户表 2. **classrooms** - 班级表 3. **students** - 学生表 4. **pets** - 宠物表 5. **growth_records** - 成长记录表 6. **shop_products** - 商城商品表 7. **redemption_records** - 兑换记录表 ### 关系设计 - 一个教师可以管理多个班级（1:N） - 一个班级包含多个学生（1:N） - 一个学生对应一个宠物（1:1） - 一个学生可以有多个成长记录（1:N） - 一个班级可以自定义商品（1:N） - 一个学生可以有多个兑换记录（1:N） ## 快速开始 ### 1. 数据库准备 ```sql -- 创建数据库 CREATE DATABASE class_pet_assistant CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; -- 执行初始化脚本 source schema.sql; ``` ### 2. 配置修改 修改 `src/main/resources/application.yml` 中的数据库连接信息： ```yaml spring: datasource: url: jdbc:mysql://localhost:3306/class_pet_assistant?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai username: root password: your_password ``` ### 3. 运行项目 ```bash # 编译项目 mvn clean install # 运行项目 mvn spring-boot:run ``` ### 4. 访问API文档 启动成功后，访问： - **API文档**: http://localhost:8080/api/swagger-ui.html - **Knife4j文档**: http://localhost:8080/api/doc ## 主要API接口 ### 认证模块 - `POST /api/auth/login` - 用户登录 - `POST /api/auth/logout` - 用户登出 - `GET /api/auth/currentUser` - 获取当前用户 ### 班级管理 - `POST /api/classes` - 创建班级 - `GET /api/classes?teacherId=1` - 获取教师所有班级 - `GET /api/classes/{id}` - 获取班级详情 - `PUT /api/classes/{id}` - 更新班级设置 - `DELETE /api/classes/{id}` - 删除班级 ### 学生管理 - `POST /api/classes/{classId}/students` - 添加学生 - `POST /api/classes/{classId}/students/batch` - 批量导入学生 - `GET /api/students/{classId}` - 获取学生列表 - `GET /api/students/{classId}/leaderboard` - 光荣榜 - `POST /api/students/{studentId}/points` - 更新积分 - `POST /api/students/{classId}/students/batch/points` - 批量更新积分 ### 商城管理 - `GET /api/shop?classId=1` - 获取商品 - `GETGET /api/shop` - 获取全局商品 - `PUT /api/shop/{classId}/products/{id}/toggle-stock` - 切换库存 - `POST /api/shop/students/{studentId}/redeem` - 商品兑换 - `GET /api/shop/{classId}/redemptions` - 获取兑换记录 ## 统一响应格式 所有API接口返回 `Result` 格式： ```json { "code": 200, "message": "操作成功", "data": { ... } } ``` - `200`: 成功 - `401`: 未授权 - `403`: 无权限 - `404`: 资源不存在 - `500`: 系统错误 ## JWT 认证 - 用户登录后生成JWT token - token包含：username, userId, role - 后续请求需在 `Authorization` header中携带：`Bearer {token}` - 拦截器自动验证token并设置用户信息到request ## MyBatis-Plus 使用说明 ### Mapper接口 ```java @Mapper public interface UserMapper extends BaseMapper { User selectById(Long id); } ``` ### LambdaQueryWrapper 使用 ```java LambdaQueryWrapper wrapper = new LambdaQueryWrapper<>(); wrapper.eq(User::getName, name); List users = userMapper.selectList(wrapper); ``` ### 自动填充 - `@TableField(fill = FieldFill.INSERT)` - 插入时自动填充 - `@TableField(fill = FieldFill.INSERT_UPDATE)` - 插入和更新时填充 - `@TableField(fill = FieldFill.UPDATE)` - 更新时填充 - 需要配合 `MyMetaObjectHandler` ## Druid 连接池配置 ```yaml spring: datasource: druid: initial-size: 5 # 初始连接数 min-idle: 5 # 最小空闲连接 max-active: 20 # 最大活动连接 max-wait: 60000 # 最大等待时间(ms) ``` ## 业务规则 ### 等级系统 - 等级阈值：[0, 5, 10, 20, 30, 45, 60, 75, 90, 100] - 10级为满级（守护神兽） - 积分增加经验值，自动计算等级 ### 兑换规则 - 积分必须 >= 商品价格 - 商品必须有库存 - 兑换后添加到学生badges字段（逗号分隔） - 创建兑换记录 ### 撤回规则 - 只能撤回一次（canWithdraw标记） - 撤回后扣减积分和经验值 - 可能导致降级 ## 前端对接建议 ### 1. 更新前端请求路径 将所有API请求改为 `/api/` 开头 ### 2. 处理JWT认证 登录后获取token： ```javascript const token = response.data.token // 后续请求携带token fetch('/api/auth/currentUser', { headers: { 'Authorization': `Bearer ${token}` } }) ``` ### 3. 处理统一响应 ```javascript if (response.code === 200) { const data = response.data // 成功，使用data } else { const message = response.message // 失败，显示错误信息 } ``` ## 常见问题 ### 1. JWT版本问题 **问题**: jjwt 0.11.5 无法下载 **解决**: 使用 `jjwt 0.12.6` 版本（已配置） ### 2. JPA依赖冲突 **解决**: 已移除所有JPA相关依赖和注解 - 使用MyBatis-Plus代替 - 实体使用 `@TableName` 而非 `@Entity` - Mapper继承 `BaseMapper` 而非 `JpaRepository` ### 3. JDK版本兼容 **问题**: Hutool 5.8.25 无法编译 **解决**: 使用JDK 1.8兼容版本 - 已配置 `source` 和 `target` 为 1.8 ## 测试账号 ### 教师账号 - 用户名: `teacher1` - 密码: `123456` - 角色: TEACHER ### 学生账号 - 用户名: `student1` - 密码: `123456` - 角色: STUDENT ## 下一步开发 ### 后端待完善 1. **创建缺失的Mapper接口** - `PetMapper` - `GrowthRecordMapper` - `RedemptionRecordMapper` 2. **完善业务逻辑** - 宠物分配服务 - 积分等级计算优化 - 兑换库存管理 3. **添加单元测试** - Service层测试 - Controller层测试 - Mapper层测试 4. **完善前端对接** - 更新前端API调用 - 处理JWT认证 - 适配统一响应格式 ### 安全加固 1. **密码加密** - 使用BCrypt加密存储 - 登录时解密验证 2. **Token刷新** - 实现Access Token + Refresh Token 3. **权限细化** - 基于角色的权限控制 - 基于班级成员的权限控制 4. **请求限流** - 使用Spring AOP或Redis实现限容 5. **数据验证** - 参数校验（@Valid） - 业务规则验证 --- **项目特点**： - ✅ 纯定的DDD分层架构 - ✅ JDK 1.8 + MyBatis-Plus 3.5.5 - ✅ JWT 认证 + Knife4j API文档 - ✅ Druid 连接池 - ✅ 统一响应 + 异常处理 - ✅ 完整的CRUD和业务逻辑