From 081fac9d975a81d2e831ddab43118881aba43c75 Mon Sep 17 00:00:00 2001 From: "Claude Opus 4.6" Date: Thu, 12 Mar 2026 19:49:48 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20Java=E5=90=8E=E7=AB=AF=E8=BF=81?= =?UTF-8?q?=E7=A7=BB=E5=AE=8C=E6=88=90=20-=20=E8=B5=84=E6=BA=90=E7=AE=A1?= =?UTF-8?q?=E7=90=86API=E4=BF=AE=E5=A4=8D=E4=B8=8E=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 完成从Node.js/NestJS到Java Spring Boot的后端迁移,修复资源管理API错误。 **核心修复:** - 修复资源库API 500错误 - ResourceLibrary/ResourceItem实体与数据库表结构对齐 - 更新ID类型从Long改为String,匹配数据库varchar(32) - 修正字段映射(libraryType → type) **新增Java实体(7个):** - CoursePackage, CoursePackageCourse, TenantPackage - CourseLesson, LessonStep, LessonStepResource - Theme **新增API控制器(5个):** - AdminResourceController - 资源库管理 - AdminPackageController - 课程套餐管理 - AdminCourseLessonController - 课程环节管理 - AdminThemeController - 主题字典管理 - SchoolPackageController - 学校套餐管理 **新增服务层(5个):** - ResourceLibraryService, CoursePackageService, CourseLessonService - ThemeService, FileStorageService **文档更新:** - 新增 Java环境配置与启动指南.md - 新增 Java后端启动完整指南.md - 新增 数据库迁移指南.md - 更新 CHANGELOG.md 和开发日志 **前端修复:** - 解决package.json合并冲突 Co-Authored-By: Claude Opus 4.6 --- .claude/CLAUDE.md | 333 ++++++++++++++--- docs/CHANGELOG.md | 69 ++++ docs/Java后端启动指南.md | 99 +++++ docs/Java环境配置与启动指南.md | 285 +++++++++++++++ docs/dev-logs/2026-03-12-java-migration.md | 189 ++++++++++ docs/dev-logs/2026-03-12.md | 257 +++++++++++++ .../2026-03-12-java-migration-summary.md | 144 ++++++++ docs/数据库迁移指南.md | 226 ++++++++++++ reading-platform-frontend/package.json | 1 - reading-platform-java/db-migrate.sh | 86 +++++ reading-platform-java/db_migrate.py | 238 ++++++++++++ reading-platform-java/pom.xml | 6 + .../exception/GlobalExceptionHandler.java | 10 +- .../platform/common/response/PageResult.java | 44 ++- .../platform/common/response/Result.java | 35 +- .../controller/FileUploadController.java | 74 ++++ .../admin/AdminCourseLessonController.java | 211 +++++++++++ .../admin/AdminPackageController.java | 140 +++++++ .../admin/AdminResourceController.java | 231 ++++++++++++ .../admin/AdminThemeController.java | 81 +++++ .../school/SchoolPackageController.java | 58 +++ .../request/CourseLessonCreateRequest.java | 189 ++++++++++ .../dto/request/PackageCreateRequest.java | 37 ++ .../dto/request/ThemeCreateRequest.java | 23 ++ .../reading/platform/entity/AdminUser.java | 2 +- .../reading/platform/entity/CourseLesson.java | 117 ++++++ .../platform/entity/CoursePackage.java | 97 +++++ .../platform/entity/CoursePackageCourse.java | 37 ++ .../reading/platform/entity/LessonStep.java | 62 ++++ .../platform/entity/LessonStepResource.java | 32 ++ .../com/reading/platform/entity/Parent.java | 2 +- .../reading/platform/entity/ResourceItem.java | 16 +- .../platform/entity/ResourceLibrary.java | 12 +- .../com/reading/platform/entity/Student.java | 2 +- .../com/reading/platform/entity/Teacher.java | 2 +- .../com/reading/platform/entity/Tenant.java | 2 +- .../platform/entity/TenantPackage.java | 60 +++ .../com/reading/platform/entity/Theme.java | 47 +++ .../platform/mapper/CourseLessonMapper.java | 12 + .../mapper/CoursePackageCourseMapper.java | 12 + .../platform/mapper/CoursePackageMapper.java | 12 + .../platform/mapper/LessonStepMapper.java | 12 + .../mapper/LessonStepResourceMapper.java | 12 + .../platform/mapper/TenantPackageMapper.java | 12 + .../reading/platform/mapper/ThemeMapper.java | 12 + .../platform/service/CourseLessonService.java | 344 ++++++++++++++++++ .../service/CoursePackageService.java | 276 ++++++++++++++ .../platform/service/FileStorageService.java | 175 +++++++++ .../service/ResourceLibraryService.java | 203 +++++++++++ .../platform/service/ThemeService.java | 120 ++++++ .../util/DatabaseMigrationRunner.java | 164 +++++++++ .../platform/util/DatabaseMigrationUtil.java | 112 ++++++ .../src/main/resources/application.yml | 56 +-- .../V20260312__create_new_tables.sql | 149 ++++++++ start-java-backend.sh | 24 ++ 55 files changed, 5149 insertions(+), 114 deletions(-) create mode 100644 docs/Java后端启动指南.md create mode 100644 docs/Java环境配置与启动指南.md create mode 100644 docs/dev-logs/2026-03-12-java-migration.md create mode 100644 docs/test-logs/2026-03-12-java-migration-summary.md create mode 100644 docs/数据库迁移指南.md create mode 100755 reading-platform-java/db-migrate.sh create mode 100755 reading-platform-java/db_migrate.py create mode 100644 reading-platform-java/src/main/java/com/reading/platform/controller/FileUploadController.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/controller/admin/AdminCourseLessonController.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/controller/admin/AdminPackageController.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/controller/admin/AdminResourceController.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/controller/admin/AdminThemeController.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/controller/school/SchoolPackageController.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/dto/request/CourseLessonCreateRequest.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/dto/request/PackageCreateRequest.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/dto/request/ThemeCreateRequest.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/entity/CourseLesson.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/entity/CoursePackage.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/entity/CoursePackageCourse.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/entity/LessonStep.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/entity/LessonStepResource.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/entity/TenantPackage.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/entity/Theme.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/mapper/CourseLessonMapper.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/mapper/CoursePackageCourseMapper.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/mapper/CoursePackageMapper.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/mapper/LessonStepMapper.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/mapper/LessonStepResourceMapper.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/mapper/TenantPackageMapper.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/mapper/ThemeMapper.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/service/CourseLessonService.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/service/CoursePackageService.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/service/FileStorageService.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/service/ResourceLibraryService.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/service/ThemeService.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/util/DatabaseMigrationRunner.java create mode 100644 reading-platform-java/src/main/java/com/reading/platform/util/DatabaseMigrationUtil.java create mode 100644 reading-platform-java/src/main/resources/db/migration/V20260312__create_new_tables.sql create mode 100755 start-java-backend.sh diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 7a108bf..9769735 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -1,6 +1,265 @@ # Claude 开发规范 -> 每次开始开发任务前,请先阅读本文档。 +> **重要**: 每次开始开发任务前,请先阅读本文档并严格遵守。 + +--- + +## 技术栈决策 + +### 后端技术栈(必须遵守) + +⚠️ **严禁使用 Node.js/NestJS 进行后端开发** + +| 组件 | 技术选型 | 版本 | 说明 | +|------|---------|------|------| +| 框架 | **Spring Boot** | 3.2+ | 基于 Java 17 | +| 持久层 | **MyBatis-Plus** | 3.5+ | 简化 CRUD | +| 数据库连接池 | **Alibaba Druid** | 1.2+ | 数据库连接池 + 监控 | +| 安全 | **Spring Security + JWT** | - | 无状态认证 + RBAC | +| API 文档 | **Knife4j (SpringDoc)** | 4.x | OpenAPI 3.0 | +| 数据库 | **MySQL** | 8.0+ | 关系型数据库 | +| 迁移 | **Flyway** | - | 版本化数据库变更 | +| 校验 | **Hibernate Validator** | - | JSR-303 参数校验 | +| 缓存 | **Redis + Spring Data Redis** | - | 缓存、会话存储 | +| 日志 | **Logback** | - | 结构化日志 | +| JSON | **FastJSON** | 2.x | JSON 序列化 | +| 工具类 | **Hutool** | 5.x | 常用工具集合 | +| 文件存储 | 阿里云 OSS | - | 对象存储 | + +### 前端技术栈 + +| 组件 | 技术选型 | 版本 | 说明 | +|------|---------|------|------| +| 框架 | **Vue 3** | 3.4+ | Composition API | +| 语言 | **TypeScript** | 5.x | 严格模式 | +| UI 库 | **Ant Design Vue** | 4.x | 企业级组件库 | +| 构建 | **Vite** | 5.x | 快速开发服务器 | +| 状态 | **Pinia** | 2.x | 轻量状态管理 | +| 请求 | **Axios** | 1.x | HTTP 客户端 | +| API 生成 | **Orval** | 7.x | OpenAPI → TypeScript | +| 路由 | **Vue Router** | 4.x | SPA 路由 | + +--- + +## 核心原则 + +1. **OpenAPI 规范驱动** - 前后端通过接口规范对齐,零沟通成本 +2. **类型安全优先** - TypeScript 强制类型校验,早发现早修复 +3. **约定大于配置** - 统一代码风格和目录结构,降低认知负担 +4. **自动化优先** - 能自动化的绝不手动(代码生成、部署、测试) +5. **三层架构分离** - Controller、Service、Mapper 职责清晰 + +--- + +## 项目结构 + +``` +ccProgram_0312/ +├── docs/ # 📁 项目文档 +│ ├── README.md # 项目说明 +│ ├── CHANGELOG.md # 变更日志 +│ ├── dev-logs/ # 开发日志 +│ ├── test-logs/ # 测试记录 +│ │ ├── admin/ # 超管端测试 +│ │ ├── school/ # 学校端测试 +│ │ ├── teacher/ # 教师端测试 +│ │ └── parent/ # 家长端测试 +│ └── design/ # 设计文档 +├── reading-platform-frontend/ # 前端项目 (Vue 3) +├── reading-platform-java/ # 后端项目 (Spring Boot) ← 唯一后端 +├── reading-platform-backend/ # ⚠️ 已弃用 (NestJS,不再维护) +├── start-all.sh # 统一启动 +└── stop-all.sh # 统一停止 +``` + +--- + +## 后端目录结构(Spring Boot) + +``` +reading-platform-java/ +├── src/main/java/com/reading/platform/ +│ ├── ReadingPlatformApplication.java # 启动类 +│ ├── common/ # 公共模块 +│ │ ├── config/ # 配置类 +│ │ │ ├── MybatisPlusConfig.java # MP 配置 +│ │ │ ├── RedisConfig.java # Redis 配置 +│ │ │ ├── SecurityConfig.java # 安全配置 +│ │ │ └── OpenApiConfig.java # API 文档配置 +│ │ ├── security/ # 安全相关 +│ │ │ ├── JwtAuthenticationFilter.java +│ │ │ ├── JwtTokenProvider.java +│ │ │ └── SecurityUtils.java +│ │ ├── response/ # 统一响应 +│ │ │ ├── Result.java +│ │ │ └── PageResult.java +│ │ ├── exception/ # 异常处理 +│ │ │ ├── BusinessException.java +│ │ │ └── GlobalExceptionHandler.java +│ │ ├── annotation/ # 自定义注解 +│ │ │ └── RequireRole.java +│ │ ├── aspect/ # AOP 切面 +│ │ │ └── RoleAspect.java +│ │ ├── enums/ # 枚举类 +│ │ └── util/ # 工具类 +│ ├── controller/ # 控制器层 +│ │ ├── AuthController.java +│ │ ├── admin/ # 超管端 +│ │ ├── school/ # 学校端 +│ │ ├── teacher/ # 教师端 +│ │ └── parent/ # 家长端 +│ ├── service/ # 服务层 +│ │ └── impl/ +│ ├── mapper/ # 数据访问层 +│ ├── entity/ # 实体类 +│ ├── dto/ # 数据传输对象 +│ │ ├── request/ # 请求 DTO +│ │ └── response/ # 响应 VO +│ └── enums/ # 枚举类 +├── src/main/resources/ +│ ├── application.yml # 主配置文件 +│ ├── application-dev.yml # 开发环境 +│ └── application-prod.yml # 生产环境 +├── pom.xml +└── Dockerfile +``` + +--- + +## 前端目录结构(Vue 3) + +``` +reading-platform-frontend/ +├── src/ +│ ├── main.ts # 入口文件 +│ ├── App.vue # 根组件 +│ ├── api/ # API 接口 +│ │ ├── generated/ # Orval 自动生成(禁止手改) +│ │ ├── client.ts # 统一入口 +│ │ └── *.ts # 业务适配层 +│ ├── assets/ # 静态资源 +│ ├── components/ # 公共组件 +│ ├── composables/ # 组合式函数 +│ ├── layouts/ # 布局组件 +│ ├── router/ # 路由配置 +│ ├── stores/ # Pinia 状态管理 +│ ├── types/ # 类型定义 +│ ├── utils/ # 工具函数 +│ ├── views/ # 页面组件 +│ │ ├── login/ # 登录页 +│ │ ├── admin/ # 超管端 +│ │ ├── school/ # 学校端 +│ │ ├── teacher/ # 教师端 +│ │ └── parent/ # 家长端 +│ └── constants/ # 常量定义 +├── orval.config.ts # API 生成配置 +├── index.html +├── package.json +└── vite.config.ts +``` + +--- + +## 后端开发规范 + +### 三层架构规范 + +**核心原则:Service 层和 Mapper 层必须使用实体类(Entity)接收和返回数据,严禁在 Service 层和 Mapper 层之间使用 DTO/VO 转换。** + +| 层级 | 职责 | 数据类型 | +|------|------|----------| +| **Controller** | 接收请求、参数校验、返回响应 | DTO ↔ Entity/VO | +| **Service** | 业务逻辑、事务控制 | Entity | +| **Mapper** | 数据库操作 | Entity | + +### Controller 层规范 + +```java +@RestController +@RequestMapping("/api/v1/xxx") +@Tag(name = "XXX管理", description = "XXX相关接口") +@RequiredArgsConstructor +public class XxxController { + + private final XxxService xxxService; + + @GetMapping + @Operation(summary = "查询列表") + public Result> list(PageQueryDto dto) { + PageResult pageResult = xxxService.page(dto); + return Result.success(convertToVO(pageResult)); + } +} +``` + +### Service 层规范 + +```java +public interface XxxService extends IService { + PageResult page(PageQueryDto dto); +} + +@Service +@RequiredArgsConstructor +public class XxxServiceImpl extends ServiceImpl + implements XxxService { + + @Override + public PageResult page(PageQueryDto dto) { + // 只使用 Entity,不使用 DTO + Page page = this.lambdaQuery() + .eq(Xxx::getStatus, 1) + .page(new Page<>(dto.getPage(), dto.getPageSize())); + return PageUtils.of(page); + } +} +``` + +### Mapper 层规范 + +```java +@Mapper +public interface XxxMapper extends BaseMapper { + // 继承 BaseMapper,使用 MyBatis-Plus 内置方法 +} +``` + +--- + +## 前端开发规范 + +### API 开发规范(Orval) + +1. **生成代码只读** - 不得在 `src/api/generated/` 内做任何手工修改 +2. **以生成类型为准** - 参数/返回类型优先使用生成的类型 +3. **统一调用入口** - 通过 `src/api/client.ts` 访问 + +### 推荐调用方式 + +```typescript +import { readingApi } from '@/api/client'; + +async function loadTenant(id: number) { + const res = await readingApi.getTenant({ id }); + return res.data; +} +``` + +### Vue SFC 约定 + +- 优先使用 `