En
583b47c430
- 新增学校通知控制器 (SchoolNotificationController) - 新增任务模板创建/更新请求 DTO - 新增日程计划创建和模板应用请求 DTO - 新增 TokenService 服务实现 - 新增多个服务实现类 (AdminStats, CourseLesson, CoursePackage 等) - 添加数据库迁移脚本 V7__fix_schedule_plans.sql - 更新配置文件和依赖 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
144 lines
5.3 KiB
Markdown
144 lines
5.3 KiB
Markdown
# CLAUDE.md
|
||
|
||
本文档为 Claude Code (claude.ai/code) 在本项目中工作时提供指导。
|
||
|
||
## 项目概述
|
||
|
||
这是一个**少儿智慧阅读平台**（Kindergarten Course Management System），采用 Spring Boot 后端 + Vue 3 前端架构。系统管理幼儿园的课程、课时、任务和学生成长记录。
|
||
|
||
## 技术架构
|
||
|
||
### 后端 (`reading-platform-java`)
|
||
- **框架**: Spring Boot 3.2.3 + Java 17
|
||
- **持久层**: MyBatis-Plus 3.5.5
|
||
- **安全**: Spring Security + JWT
|
||
- **API 文档**: Knife4j (Swagger OpenAPI 3)
|
||
- **数据库**: MySQL 8.0
|
||
- **数据库迁移**: Flyway
|
||
|
||
### 前端 (`reading-platform-frontend`)
|
||
- **框架**: Vue 3 + TypeScript + Vite
|
||
- **UI 组件库**: Ant Design Vue
|
||
- **状态管理**: Pinia
|
||
- **API**: Axios + Orval 自动生成的 TypeScript 客户端
|
||
|
||
## 多租户架构
|
||
|
||
系统支持多个幼儿园（租户）：
|
||
- `admin` 角色：超级管理员（无租户，管理全系统课程）
|
||
- `school` 角色：学校管理员（管理本校的教师、学生、班级）
|
||
- `teacher` 角色：教师（管理本校的课时和任务）
|
||
- `parent` 角色：家长（查看孩子的进度和任务）
|
||
|
||
除 `admin_users` 外，每个实体都有 `tenant_id` 字段。系统课程的 `tenant_id = NULL`。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
kindergarten_java/
|
||
├── reading-platform-java/ # Spring Boot 后端
|
||
│ ├── src/main/java/.../controller/
|
||
│ │ ├── admin/ # 超级管理员端点 (/api/v1/admin/*)
|
||
│ │ ├── school/ # 学校管理员端点 (/api/v1/school/*)
|
||
│ │ ├── teacher/ # 教师端点 (/api/v1/teacher/*)
|
||
│ │ └── parent/ # 家长端点 (/api/v1/parent/*)
|
||
│ ├── entity/ # 数据库实体（27张表）
|
||
│ ├── mapper/ # MyBatis-Plus 映射器
|
||
│ ├── service/ # 服务层接口 + 实现
|
||
│ ├── common/
|
||
│ │ ├── annotation/RequireRole # 基于角色的访问控制
|
||
│ │ ├── security/ # JWT 认证
|
||
│ │ ├── enums/ # UserRole, CourseStatus 等枚举
|
||
│ │ ├── response/ # Result<T>, PageResult<T>
|
||
│ │ └── config/ # Security, MyBatis, OpenAPI 配置
|
||
│ └── resources/
|
||
│ ├── db/migration/ # Flyway 迁移脚本
|
||
│ └── mapper/ # MyBatis XML 文件
|
||
│
|
||
├── reading-platform-frontend/ # Vue 3 前端
|
||
│ ├── src/views/
|
||
│ │ ├── admin/ # 超级管理员页面
|
||
│ │ ├── school/ # 学校管理员页面
|
||
│ │ ├── teacher/ # 教师页面
|
||
│ │ └── parent/ # 家长页面
|
||
│ ├── api/generated/ # 自动生成的 API 客户端
|
||
│ ├── api-spec.yml # OpenAPI 规范
|
||
│ └── router/index.ts # Vue Router 配置
|
||
│
|
||
├── docker-compose.yml # 后端 + 前端服务
|
||
└── docs/开发协作指南.md # 开发指南（中文）
|
||
```
|
||
|
||
## 关键模式
|
||
|
||
### 1. 基于角色的访问控制
|
||
在 Controller/Service 上使用 `@RequireRole` 注解：
|
||
```java
|
||
@RequireRole(UserRole.SCHOOL) // 只有学校管理员可以访问
|
||
```
|
||
|
||
### 2. 租户隔离
|
||
在学校/教师/家长端点中使用 `SecurityUtils.getCurrentTenantId()` 按当前租户过滤数据。
|
||
|
||
### 3. 统一响应格式
|
||
```java
|
||
Result<T> success(T data) // { code: 200, message: "success", data: ... }
|
||
Result<T> error(code, msg) // { code: xxx, message: "...", data: null }
|
||
```
|
||
|
||
### 4. OpenAPI 驱动开发
|
||
- 后端：在 Controller 上使用 `@Operation`、`@Parameter`、`@Schema` 注解
|
||
- 前端：运行 `npm run api:update` 从 `api-spec.yml` 重新生成 TypeScript 客户端
|
||
|
||
## 开发命令
|
||
|
||
### 后端
|
||
```bash
|
||
# 使用 Docker Compose 运行（推荐）
|
||
docker compose up --build
|
||
|
||
# 本地运行（需要 MySQL 已启动）
|
||
cd reading-platform-java
|
||
mvn spring-boot:run
|
||
|
||
# 构建
|
||
mvn clean package -DskipTests
|
||
```
|
||
|
||
### 前端
|
||
```bash
|
||
cd reading-platform-frontend
|
||
npm install
|
||
npm run dev
|
||
npm run build
|
||
|
||
# 从后端规范更新 API 客户端
|
||
npm run api:update
|
||
```
|
||
|
||
### 数据库迁移
|
||
- 将新的迁移脚本添加到 `reading-platform-java/src/main/resources/db/migration/V{n}__description.sql`
|
||
- Flyway 会在后端启动时自动运行（仅开发模式）
|
||
|
||
## 数据库表结构（27张表）
|
||
- **租户**: tenants, tenant_courses
|
||
- **用户**: admin_users, teachers, students, parents, parent_students
|
||
- **班级**: classes, class_teachers, student_class_history
|
||
- **课程**: courses, course_versions, course_resources, course_scripts, course_script_pages, course_activities
|
||
- **课时**: lessons, lesson_feedbacks, student_records
|
||
- **任务**: tasks, task_targets, task_completions, task_templates
|
||
- **成长**: growth_records
|
||
- **资源**: resource_libraries, resource_items
|
||
- **日程**: schedule_plans, schedule_templates
|
||
- **系统**: system_settings, notifications, operation_logs, tags
|
||
|
||
## 测试账号
|
||
| 角色 | 用户名 | 密码 |
|
||
|------|--------|------|
|
||
| 管理员 | admin | admin123 |
|
||
| 学校 | school | 123456 |
|
||
| 教师 | teacher1 | 123456 |
|
||
| 家长 | parent1 | 123456 |
|
||
|
||
## API 文档
|
||
- 访问地址：http://localhost:8080/doc.html（后端启动后） |