kindergarten_java/CLAUDE.md

# 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（后端启动后）