En
e501e17403
主要变更： 1. 新增学校报告服务 (SchoolReportService) - 学校概览统计 (getOverviewStats) - 教师统计报表 (getTeacherStats) - 课程统计报表 (getCourseStats) - 学生统计报表 (getStudentStats) - 课时趋势分析 (getLessonTrend) 2. 新增学校端 Controller - SchoolReportController: 学校统计报告接口 - SchoolResourceController: 学校资源管理接口 - SchoolFeedbackController: 学校反馈管理接口 3. 完善实体类字段 - CourseLesson: 添加 lessonOrder 字段 - ResourceItem: 添加 tenantId、type 字段 - Task: 添加 name 字段 - LessonFeedback: 添加 courseId、tenantId、overallRating 字段 4. 完善服务层实现 - ResourceServiceImpl: 实现资源库和资源项管理方法 - SchoolReportServiceImpl: 实现学校统计报表逻辑 - TeacherDashboardServiceImpl: 修复时间类型转换 - AdminStatsServiceImpl: 完善统计逻辑 5. 新增 Flyway 迁移脚本 (V2) - 添加 ORM 实体类缺失字段的数据库迁移 6. 修复路由冲突 - 移除 AdminCourseController 中重复的 getCourseLessons 方法 7. 添加测试工具类 - CheckDatabase, CheckClazzTable: 数据库检查工具 - InitDatabase, InitClasses: 数据初始化工具 - GeneratePasswordHash: 密码哈希生成工具 8. 配置 Maven Wrapper - 添加 maven-wrapper.properties 和 mvnw.cmd - 确保使用 Java 17 编译
134 lines
4.6 KiB
Markdown
134 lines
4.6 KiB
Markdown
# API 类型对比报告
|
||
|
||
生成日期：2026-03-11
|
||
|
||
## 测试概述
|
||
|
||
### 1. API 生成测试 ✅
|
||
- **orval 版本**: v7.13.2
|
||
- **生成状态**: 成功
|
||
- **输出文件**: `src/api/generated/api.ts` + `src/api/generated/model/*.ts`
|
||
- **警告**: 未找到全局安装的 prettier（不影响功能）
|
||
|
||
### 2. 后端 API 导出测试 ⚠️
|
||
- **后端地址**: http://8.148.151.56:3002
|
||
- **测试结果**: 无法连接（服务器可能关闭）
|
||
- **本地规范**: `api-spec.yml` (408KB, 155 个接口)
|
||
|
||
### 3. TypeScript 编译检查 ⚠️
|
||
- **错误数量**: 88 个
|
||
- **主要问题**:
|
||
- 未使用的变量 (TS6133): 约 50 个
|
||
- 类型不匹配 (TS2322/TS2345): 约 20 个
|
||
- 类型定义缺失 (TS2304/TS2724): 约 10 个
|
||
- 其他类型错误：约 8 个
|
||
|
||
## 类型定义对比
|
||
|
||
### ChildInfo (家长端 - 孩子信息)
|
||
|
||
| 字段 | 手写类型 | 生成类型 | 后端定义 | 状态 |
|
||
|------|---------|---------|---------|------|
|
||
| id | `number` | `string` | `String` | ❌ 不一致 |
|
||
| name | `string` | `string` | `String` | ✅ |
|
||
| gender | `string` | `string` | `String` | ✅ |
|
||
| birthDate | `string` | `string` | `String` | ✅ |
|
||
| relationship | `string` (必填) | `string` (可选) | `String` | ⚠️ 可选性 |
|
||
| class | `{id, name, grade}` | `ClassInfo` | `ClassInfo` | ⚠️ 字段名 |
|
||
| readingCount | `number` (必填) | `number` (可选) | `Integer` | ⚠️ 可选性 |
|
||
| lessonCount | `number` (必填) | `number` (可选) | `Integer` | ⚠️ 可选性 |
|
||
|
||
**修复建议**:
|
||
```typescript
|
||
// 修改 src/api/parent.ts
|
||
export interface ChildInfo {
|
||
id: string; // 改为 string
|
||
name: string;
|
||
gender?: string;
|
||
birthDate?: string;
|
||
relationship?: string; // 改为可选
|
||
classInfo?: { // 改为 classInfo
|
||
id: string; // 改为 string
|
||
name: string;
|
||
grade: string;
|
||
};
|
||
readingCount?: number; // 改为可选
|
||
lessonCount?: number; // 改为可选
|
||
}
|
||
```
|
||
|
||
### Task (任务)
|
||
|
||
| 字段 | 手写类型 | 生成类型 | 后端定义 | 状态 |
|
||
|------|---------|---------|---------|------|
|
||
| id | `number` | `number` | `Long` | ✅ |
|
||
| title | `string` | `string` | `String` | ✅ |
|
||
| description | `string` | `string` | `String` | ✅ |
|
||
| taskType | `'READING' | 'ACTIVITY' | 'HOMEWORK'` | `string` | `String` | ⚠️ 生成类型缺少枚举约束 |
|
||
| status | `string` | `string` | `String` | ✅ |
|
||
|
||
### Teacher (教师)
|
||
|
||
| 字段 | 手写类型 | 生成类型 | 后端定义 | 状态 |
|
||
|------|---------|---------|---------|------|
|
||
| id | `number` | `number` | `Long` | ✅ |
|
||
| name | `string` | `string` | `String` | ✅ |
|
||
| phone | `string` | `string` | `String` | ✅ |
|
||
| loginAccount | `string` | - | - | ⚠️ 手写特有 |
|
||
| status | `string` | `string` | `String` | ✅ |
|
||
| classIds | `number[]` | - | - | ⚠️ 手写特有 |
|
||
| classNames | `string` | - | - | ⚠️ 手写特有 |
|
||
|
||
**说明**: 手写类型包含前端额外需要的字段（来自多个接口的组合）
|
||
|
||
## 主要问题总结
|
||
|
||
### 1. ID 类型不一致
|
||
- 后端部分 Entity 使用 `String` 类型作为 ID（如 ChildInfoResponse）
|
||
- 前端手写类型使用 `number`
|
||
- **影响**: 可能导致类型校验失败或运行时错误
|
||
|
||
### 2. 字段命名不一致
|
||
- 后端使用 `classInfo`，前端使用 `class`
|
||
- **影响**: 前端代码访问 `child.class` 会返回 undefined
|
||
|
||
### 3. 必填/可选不一致
|
||
- 后端所有字段都是可选的（Java 对象默认）
|
||
- 前端手写类型部分字段为必填
|
||
- **影响**: 可能导致不必要的类型检查错误
|
||
|
||
### 4. 类型定义分散
|
||
- 同一个实体在不同接口有不同 Response 类型
|
||
- 例如 `Teacher` 有 `TeacherInfoResponse`, `Teacher`, `PageResultTeacher` 等
|
||
- **影响**: 前端需要维护多个类型定义
|
||
|
||
## 修复优先级
|
||
|
||
### 高优先级 (影响功能)
|
||
1. ❌ `ChildInfo.id` 类型错误 (number → string)
|
||
2. ❌ `ChildInfo.class` 字段名错误 (class → classInfo)
|
||
3. ❌ `Tenant.id` 类型检查
|
||
|
||
### 中优先级 (类型安全)
|
||
1. ⚠️ 统一 ID 类型为 string 或 number
|
||
2. ⚠️ 添加枚举类型约束（如 TaskType, UserRole）
|
||
3. ⚠️ 更新可选字段标记
|
||
|
||
### 低优先级 (代码质量)
|
||
1. 📝 清理未使用的变量
|
||
2. 📝 修复 ESLint 警告
|
||
3. 📝 统一类型命名规范
|
||
|
||
## 测试结论
|
||
|
||
1. **orval 生成工作正常**，可以用于生成类型参考
|
||
2. **手写 API 类型需要更新**以匹配后端实际返回
|
||
3. **建议建立类型同步流程**：
|
||
- 后端变更 → 更新 api-spec.yml → 重新生成 → 对比修复手写类型
|
||
|
||
## 下一步行动
|
||
|
||
1. 修复 `src/api/parent.ts` 中的 `ChildInfo` 类型
|
||
2. 检查其他 Response 类型的字段一致性
|
||
3. 添加运行时类型转换层（可选）
|