kindergarten_java/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a **Kindergarten Course Management System** (少儿智慧阅读平台) with a Spring Boot backend and Vue 3 frontend. The system manages courses, lessons, tasks, and student growth records for kindergartens.

## Architecture

### Backend (`reading-platform-java`)
- **Framework**: Spring Boot 3.2.3 + Java 17
- **Persistence**: MyBatis-Plus 3.5.5
- **Security**: Spring Security + JWT
- **API Docs**: Knife4j (Swagger OpenAPI 3)
- **Database**: MySQL 8.0
- **Migration**: Flyway

### Frontend (`reading-platform-frontend`)
- **Framework**: Vue 3 + TypeScript + Vite
- **UI**: Ant Design Vue
- **State**: Pinia
- **API**: Axios with auto-generated TypeScript clients via Orval

## Multi-Tenant Architecture

The system supports multiple kindergartens (tenants):
- `admin` role: Super admin (no tenant, manages system-wide courses)
- `school` role: School administrator (manages school's teachers, students, classes)
- `teacher` role: Teacher (manages lessons, tasks for their tenant)
- `parent` role: Parent (views child's progress and tasks)

Each entity (except `admin_users`) has a `tenant_id` field. System courses have `tenant_id = NULL`.

## Project Structure

```
kindergarten_java/
├── reading-platform-java/           # Spring Boot backend
│   ├── src/main/java/.../controller/
│   │   ├── admin/                   # Super admin endpoints (/api/v1/admin/*)
│   │   ├── school/                  # School admin endpoints (/api/v1/school/*)
│   │   ├── teacher/                 # Teacher endpoints (/api/v1/teacher/*)
│   │   └── parent/                  # Parent endpoints (/api/v1/parent/*)
│   ├── entity/                      # Database entities (27 tables)
│   ├── mapper/                      # MyBatis-Plus mappers
│   ├── service/                     # Service layer interface + impl
│   ├── common/
│   │   ├── annotation/RequireRole   # Role-based access control
│   │   ├── security/                # JWT authentication
│   │   ├── enums/                   # UserRole, CourseStatus, etc.
│   │   ├── response/                # Result<T>, PageResult<T>
│   │   └── config/                  # Security, MyBatis, OpenAPI configs
│   └── resources/
│       ├── db/migration/            # Flyway migration scripts
│       └── mapper/                  # MyBatis XML files
│
├── reading-platform-frontend/       # Vue 3 frontend
│   ├── src/views/
│   │   ├── admin/                   # Super admin pages
│   │   ├── school/                  # School admin pages
│   │   ├── teacher/                 # Teacher pages
│   │   └── parent/                  # Parent pages
│   ├── api/generated/               # Auto-generated API clients
│   ├── api-spec.yml                 # OpenAPI specification
│   └── router/index.ts              # Vue Router config
│
├── docker-compose.yml               # Backend + Frontend services
└── docs/开发协作指南.md              # Development guide (Chinese)
```

## Key Patterns

### 1. Role-Based Access Control
Use `@RequireRole` annotation on controllers/services:
```java
@RequireRole(UserRole.SCHOOL)  // Only school admins can access
```

### 2. Tenant Isolation
Use `SecurityUtils.getCurrentTenantId()` in school/teacher/parent endpoints to filter data by current tenant.

### 3. Unified Response Format
```java
Result<T> success(T data)   // { code: 200, message: "success", data: ... }
Result<T> error(code, msg)  // { code: xxx, message: "...", data: null }
```

### 4. OpenAPI-Driven Development
- Backend: Annotate controllers with `@Operation`, `@Parameter`, `@Schema`
- Frontend: Run `npm run api:update` to regenerate TypeScript clients from `api-spec.yml`

## Development Commands

### Backend
```bash
# Run with Docker Compose (recommended)
docker compose up --build

# Run locally (requires MySQL running)
cd reading-platform-java
mvn spring-boot:run

# Build
mvn clean package -DskipTests
```

### Frontend
```bash
cd reading-platform-frontend
npm install
npm run dev
npm run build

# Update API clients from backend spec
npm run api:update
```

### Database Migration
- Add new migration scripts to `reading-platform-java/src/main/resources/db/migration/V{n}__description.sql`
- Flyway runs automatically on backend startup (dev mode only)

## Database Schema (27 Tables)
- **Tenant**: tenants, tenant_courses
- **Users**: admin_users, teachers, students, parents, parent_students
- **Class**: classes, class_teachers, student_class_history
- **Course**: courses, course_versions, course_resources, course_scripts, course_script_pages, course_activities
- **Lesson**: lessons, lesson_feedbacks, student_records
- **Task**: tasks, task_targets, task_completions, task_templates
- **Growth**: growth_records
- **Resource**: resource_libraries, resource_items
- **Schedule**: schedule_plans, schedule_templates
- **System**: system_settings, notifications, operation_logs, tags

## Test Accounts
| Role | Username | Password |
|------|----------|----------|
| Admin | admin | admin123 |
| School | school | 123456 |
| Teacher | teacher1 | 123456 |
| Parent | parent1 | 123456 |

## API Documentation
- Access: http://localhost:8080/doc.html (after backend starts)