393 lines
12 KiB
Markdown
393 lines
12 KiB
Markdown
# 开发日志 - 2026-03-13
|
||
|
||
**开发者**: Claude
|
||
**日期**: 2026-03-13
|
||
|
||
---
|
||
|
||
## 今日工作内容
|
||
|
||
### 1. 学校端 API 调试与修复
|
||
|
||
#### 问题发现
|
||
- 学校端大部分 API 返回 500 错误
|
||
- 用户登录失败（密码哈希不匹配）
|
||
- 缺少统计 API 和课程 API
|
||
|
||
#### 修复过程
|
||
|
||
**1. 密码问题修复**
|
||
- 发现数据库中的密码哈希与测试密码 `123456` 不匹配
|
||
- 创建 `reset_passwords.py` 脚本，使用 BCrypt 生成新哈希
|
||
- 更新所有用户表（admin_users, tenants, teachers, parents）的密码
|
||
|
||
**2. 创建 School Stats API**
|
||
- 创建 `SchoolStatsController.java`
|
||
- 实现以下接口：
|
||
- `/api/school/stats` - 基础统计
|
||
- `/api/school/stats/teachers` - 活跃教师排行
|
||
- `/api/school/stats/courses` - 课程使用统计
|
||
- `/api/school/stats/activities` - 近期活动
|
||
- `/api/school/stats/lesson-trend` - 授课趋势
|
||
- `/api/school/stats/course-distribution` - 课程分布
|
||
|
||
**3. 创建 School Course API**
|
||
- 创建 `SchoolCourseController.java`
|
||
- 实现以下接口：
|
||
- `/api/school/courses` - 课程列表
|
||
- `/api/school/courses/{id}` - 课程详情
|
||
|
||
**4. 修复 API 响应格式不匹配**
|
||
- 后端返回：`{list, total, pageNum, pageSize, pages}`
|
||
- 前端期望：`{items, total, page, pageSize}`
|
||
- 更新 `src/api/school.ts` 的类型定义
|
||
- 批量更新所有视图文件：`result.items` → `result.list`
|
||
|
||
**5. 修复 SchoolPackageController 路径**
|
||
- 将 `/api/v1/school/packages` 改为 `/api/school/packages`
|
||
|
||
---
|
||
|
||
## 测试结果
|
||
|
||
### 学校端功能测试
|
||
- ✅ 登录功能正常
|
||
- ✅ Dashboard 加载正常，统计 API 响应正常
|
||
- ✅ 教师管理页面加载正常
|
||
- ✅ 学生管理页面加载正常
|
||
- ✅ 班级管理页面加载正常
|
||
- ✅ 课程管理页面加载正常
|
||
|
||
### API 状态汇总
|
||
| API | 状态 |
|
||
|-----|------|
|
||
| `/api/auth/login` | ✅ |
|
||
| `/api/school/stats` | ✅ |
|
||
| `/api/school/teachers` | ✅ |
|
||
| `/api/school/students` | ✅ |
|
||
| `/api/school/classes` | ✅ |
|
||
| `/api/school/parents` | ✅ |
|
||
| `/api/school/tasks` | ✅ |
|
||
| `/api/school/courses` | ✅ |
|
||
| `/api/school/growth-records` | ✅ |
|
||
| `/api/school/packages` | ✅ |
|
||
|
||
---
|
||
|
||
## 新增文件
|
||
|
||
### 后端
|
||
- `SchoolStatsController.java` - 统计数据控制器
|
||
- `SchoolCourseController.java` - 课程管理控制器
|
||
|
||
### 脚本
|
||
- `reset_passwords.py` - 密码重置脚本
|
||
- `test_db_query.py` - 数据库查询测试脚本
|
||
- `verify_password.py` - 密码哈希验证脚本
|
||
|
||
### 文档
|
||
- `/docs/test-logs/school/2026-03-13.md` - 学校端测试记录
|
||
- `/docs/dev-logs/2026-03-13.md` - 今日开发日志
|
||
|
||
---
|
||
|
||
## 技术要点
|
||
|
||
### BCrypt 密码哈希
|
||
```python
|
||
import bcrypt
|
||
|
||
# 生成哈希
|
||
salt = bcrypt.gensalt(rounds=10)
|
||
password_hash = bcrypt.hashpw(password.encode('utf-8'), salt)
|
||
|
||
# 验证密码
|
||
bcrypt.checkpw(password.encode('utf-8'), hash_bytes)
|
||
```
|
||
|
||
### MyBatis-Plus 分页查询
|
||
```java
|
||
Page<Clazz> page = classService.getClassPage(tenantId, pageNum, pageSize, keyword, grade, status);
|
||
return Result.success(PageResult.of(page));
|
||
```
|
||
|
||
---
|
||
|
||
## 待完成工作
|
||
|
||
1. 测试教师/学生添加功能
|
||
2. 测试班级创建功能
|
||
3. 测试任务创建功能
|
||
4. 测试家长管理功能
|
||
5. 完善统计数据计算逻辑
|
||
|
||
---
|
||
|
||
### 2. 教师端 API 调试与修复
|
||
|
||
#### 问题发现
|
||
- 前端 API 导入错误：`getApi` 函数不存在（应为 `getReadingPlatformAPI`）
|
||
- 教师端 Dashboard API 返回 500 错误
|
||
- 缺少教师端统计相关的 API 端点
|
||
|
||
#### 修复过程
|
||
|
||
**1. 修复 API 客户端导入**
|
||
- 更新 `src/api/client.ts`：`getApi` → `getReadingPlatformAPI`
|
||
- 更新 `src/api/teacher.ts`：修正导入函数名
|
||
- 更新 `src/api/school-course.ts`：批量修正导入
|
||
|
||
**2. 创建 Teacher Stats API**
|
||
- 创建 `TeacherStatsController.java`
|
||
- 实现以下接口：
|
||
- `/api/teacher/dashboard` - 教师端首页统计
|
||
- `/api/teacher/today-lessons` - 今日课程
|
||
- `/api/teacher/recommended-courses` - 推荐课程
|
||
- `/api/teacher/weekly-stats` - 本周统计
|
||
- `/api/teacher/lesson-trend` - 授课趋势
|
||
- `/api/teacher/course-usage` - 课程使用统计
|
||
- 使用 try-catch 处理缺失的 `lessons` 表（远程数据库未同步）
|
||
|
||
**3. 更新前端 API 调用**
|
||
- 修正 `teacher.ts` 中的方法名：
|
||
- `api.teacherCourseControllerGetDashboard()` → `api.getDashboard()`
|
||
- `api.teacherCourseControllerGetTodayLessons()` → `api.getTodayLessons()`
|
||
- `api.teacherCourseControllerGetRecommendedCourses()` → `api.getRecommendedCourses()`
|
||
- `api.teacherCourseControllerGetWeeklyStats()` → `api.getWeeklyStats()`
|
||
- `api.teacherCourseControllerGetLessonTrend()` → `api.getLessonTrend()`
|
||
- `api.teacherCourseControllerGetCourseUsage()` → `api.getCourseUsage()`
|
||
- 移除未使用的类型导入 `TeacherCourseControllerGetLessonTrendParams`
|
||
|
||
**4. 添加教师班级端点**
|
||
- 在 `TeacherCourseController.java` 中添加 `/api/teacher/classes` 端点
|
||
|
||
---
|
||
|
||
## 测试结果
|
||
|
||
### 教师端功能测试（晚间）
|
||
- ✅ 登录功能正常
|
||
- ✅ Dashboard 加载成功，显示 25 个统计卡片
|
||
- ✅ Dashboard API 调用成功（不再返回 500 错误）
|
||
- ✅ 今日课程、推荐课程、本周统计 API 正常响应
|
||
- ✅ 授课趋势、课程使用统计 API 正常响应
|
||
- ⚠️ 班级管理页面需要进一步测试（classes 端点已添加）
|
||
|
||
### API 状态汇总（新增）
|
||
| API | 状态 |
|
||
|-----|------|
|
||
| `/api/teacher/dashboard` | ✅ |
|
||
| `/api/teacher/today-lessons` | ✅ |
|
||
| `/api/teacher/recommended-courses` | ✅ |
|
||
| `/api/teacher/weekly-stats` | ✅ |
|
||
| `/api/teacher/lesson-trend` | ✅ |
|
||
| `/api/teacher/course-usage` | ✅ |
|
||
| `/api/teacher/classes` | ⚠️ 已添加，待测试 |
|
||
|
||
---
|
||
|
||
## 新增文件
|
||
|
||
### 后端
|
||
- `TeacherStatsController.java` - 教师端统计数据控制器
|
||
- 修改 `TeacherCourseController.java` - 添加班级端点
|
||
|
||
### 脚本
|
||
- `create_lessons_table.py` - 创建缺失数据库表的脚本（未执行，远程数据库访问受限）
|
||
|
||
---
|
||
|
||
## 备注
|
||
|
||
- Java 后端运行在 port 8080
|
||
- 前端 Vite 运行在 port 5173
|
||
- 远程数据库：8.148.151.56:3306/reading_platform
|
||
- 远程数据库缺少 `lessons` 表，已使用 try-catch 优雅处理
|
||
|
||
---
|
||
|
||
### 3. 课程包三端全链路测试与修复
|
||
|
||
#### 测试目标
|
||
围绕课程包业务，从超管端创建到学校端查看、教师端备课的完整链路测试。
|
||
|
||
#### Bug 修复记录
|
||
|
||
**Bug 1: 登录 API 路径错误**
|
||
- 测试脚本使用 `/api/v1/auth/login`，实际是 `/api/auth/login`
|
||
|
||
**Bug 2: 角色名称大小写错误**
|
||
- 测试脚本使用 `"role": "ADMIN"`，枚举要求小写 `"admin"`
|
||
|
||
**Bug 3: 测试账号密码错误**
|
||
- 测试脚本使用 `123456`，数据库是 `123456`
|
||
|
||
**Bug 4: 套餐提交审核必须包含课程**
|
||
- 提交审核时报错 "套餐必须包含至少一个课程包"
|
||
- 修复：先创建课程，再添加到套餐
|
||
|
||
**Bug 5: 学校端 API 路径错误**
|
||
- 测试脚本使用 `/api/v1/school/packages`，实际是 `/api/school/packages`
|
||
|
||
**Bug 6: 教师端无法看到系统课程**
|
||
- `getCoursePage` 和 `getCoursesByTenantId` 只查租户课程
|
||
- 修复：同时查询租户课程和系统课程 (`isSystem = 1`)
|
||
|
||
**Bug 7: 创建系统课程未设置 isSystem 标志**
|
||
- `AdminCourseController.createCourse` 设置了但未保存
|
||
- 修复：添加 `courseMapper.updateById(course)`
|
||
|
||
**Bug 8: 课程需要发布才能被教师端看到**
|
||
- 教师端查询 `status = 'published'`
|
||
- 修复：创建后调用发布接口
|
||
|
||
#### 新增功能
|
||
- 新增套餐授权接口：`POST /api/v1/admin/packages/{id}/grant`
|
||
- 请求参数：tenantId, endDate, pricePaid
|
||
|
||
#### 测试结果
|
||
- ✅ 超管端：登录、创建/发布课程、创建套餐、添加课程、提交审核、审核通过、发布套餐、授权给租户
|
||
- ✅ 学校端：登录、查看授权套餐
|
||
- ✅ 教师端：登录、查看可用课程
|
||
|
||
#### 测试脚本
|
||
- `test_package_full_api.py` - 完整套餐 API 测试
|
||
- `test_three_ends.py` - 三端全链路测试
|
||
- `/docs/test-logs/package/2026-03-13-full-flow.md` - 详细测试记录
|
||
|
||
---
|
||
|
||
### 4. 代码合规性审查与重构
|
||
|
||
#### 审查范围
|
||
严格按照 `.claude/CLAUDE.md` 开发规范进行全项目代码审查
|
||
|
||
#### 发现的问题
|
||
|
||
**P0 - 三层架构违规（4项）**
|
||
- `SchoolStatsController` - 直接注入 `TeacherMapper`, `StudentMapper`, `ClazzMapper`
|
||
- `TeacherStatsController` - 直接注入 `ClazzMapper`, `StudentMapper`, `CourseMapper`, `LessonMapper`
|
||
- `TeacherCourseController` - 直接注入 `ClazzMapper`
|
||
- `AdminCourseController` - 直接注入 `CourseMapper` 用于更新 isSystem 标志
|
||
|
||
**P1 - API 路径不一致（8项）**
|
||
- `AdminCourseController`: `/api/admin/courses` → 应为 `/api/v1/admin/courses`
|
||
- `AdminTenantController`: `/api/admin/tenants` → 应为 `/api/v1/admin/tenants`
|
||
- 前端 `vite.config.ts`: 代理重写规则导致路径混乱
|
||
- 前端 `src/api/index.ts`: baseURL 设置与实际不一致
|
||
- 前端 API 文件: `/admin/*` 路径缺少 `/v1` 前缀
|
||
|
||
**P2 - 文档与代码不一致（5项）**
|
||
- `.claude/CLAUDE.md` 前端 API 调用示例与实际代码不符
|
||
- 缺少 API 路径规范说明
|
||
- 前端目录结构描述不准确
|
||
|
||
#### 修复过程
|
||
|
||
**1. 三层架构重构**
|
||
|
||
新增 Service 层：
|
||
- `SchoolStatsService` + `SchoolStatsServiceImpl` - 学校端统计服务
|
||
- `TeacherStatsService` + `TeacherStatsServiceImpl` - 教师端统计服务
|
||
|
||
扩展现有 Service：
|
||
- `ClassService.getActiveClassesByTenantId()` - 获取活跃班级
|
||
- `CourseService.createSystemCourse()` - 创建系统课程专用方法
|
||
|
||
更新 Controller：
|
||
- 移除所有直接 Mapper 注入
|
||
- 改为调用 Service 层方法
|
||
- 验证编译通过
|
||
|
||
**2. API 路径统一**
|
||
|
||
后端路径修复：
|
||
```java
|
||
// AdminCourseController
|
||
@RequestMapping("/api/v1/admin/courses") // 原路径: /api/admin/courses
|
||
|
||
// AdminTenantController
|
||
@RequestMapping("/api/v1/admin/tenants") // 原路径: /api/admin/tenants
|
||
```
|
||
|
||
前端配置修复：
|
||
```typescript
|
||
// vite.config.ts - 移除重写规则
|
||
proxy: {
|
||
'/api': {
|
||
target: 'http://localhost:8080',
|
||
changeOrigin: true,
|
||
}
|
||
}
|
||
|
||
// src/api/index.ts - 修改 baseURL
|
||
baseURL: '/api' // 原值: '/api/v1'
|
||
```
|
||
|
||
前端 API 路径更新：
|
||
- `admin.ts`: `/admin/tenants` → `/v1/admin/tenants`
|
||
- `admin.ts`: `/admin/stats` → `/v1/admin/stats`
|
||
- `lesson.ts`: `/admin/courses` → `/v1/admin/courses`
|
||
- `package.ts`: `/admin/packages` → `/v1/admin/packages`
|
||
- `theme.ts`: `/admin/themes` → `/v1/admin/themes`
|
||
|
||
**3. 文档规范更新**
|
||
|
||
更新 `.claude/CLAUDE.md`：
|
||
- 前端目录结构: `client.ts` → `index.ts`
|
||
- 新增三种 API 调用方式说明
|
||
- 新增 API 路径规范表格
|
||
- 更新 Controller 路径约定说明
|
||
|
||
#### Git 提交记录
|
||
- `066b1f2` - refactor: 代码合规性审查修复 - 三层架构、API路径、文档规范
|
||
- `c0b465d` - docs: 更新CHANGELOG - 记录代码合规性审查修复
|
||
|
||
#### 变更统计
|
||
- 修改文件: 16 个
|
||
- 新增文件: 4 个 Service 类
|
||
- 代码变更: +592 行，-305 行
|
||
|
||
---
|
||
|
||
### 5. Playwright 自动化测试
|
||
|
||
#### 测试目标
|
||
使用 Playwright 进行浏览器自动化，测试超管端课程包创建流程
|
||
|
||
#### 测试脚本
|
||
- `test_create_course_simple.py` - 简化版自动化脚本
|
||
|
||
#### 测试结果
|
||
| 步骤 | 状态 |
|
||
|------|------|
|
||
| 浏览器启动 | ✅ |
|
||
| 登录页访问 | ✅ |
|
||
| 超管登录 | ✅ |
|
||
| 导航到创建页面 | ✅ |
|
||
| 表单字段填写 | ✅ |
|
||
| 提交按钮定位 | ⚠️ 需手动确认 |
|
||
|
||
#### 生成的截图
|
||
```
|
||
screenshots/
|
||
├── create_page.png - 创建页面
|
||
├── form_filled.png - 表单填写完成
|
||
└── before_submit.png - 提交前状态
|
||
```
|
||
|
||
#### 填写的表单内容
|
||
- 课程名称: 春日主题活动_{timestamp}
|
||
- 课程编码: SPRING{timestamp}
|
||
- 课程描述: 以春天为主题的活动介绍
|
||
- 课程目标: 认知、技能、情感三维目标
|
||
- 核心内容: 春天的花草、气候、动物、习俗
|
||
- 课程亮点: 活动丰富、贴近生活、注重体验
|
||
- 环境创设: 主题墙、自然角、美工区布置
|
||
|
||
#### 备注
|
||
- 使用 Playwright 1.58.0
|
||
- Chromium for Testing 浏览器
|
||
- headless=False 模式便于观察执行过程
|
||
|