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:

@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

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

# 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

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)