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 注解：

@RequireRole(UserRole.SCHOOL)  // 只有学校管理员可以访问

2. 租户隔离

在学校/教师/家长端点中使用 SecurityUtils.getCurrentTenantId() 按当前租户过滤数据。

3. 统一响应格式

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 客户端

开发命令

后端

# 使用 Docker Compose 运行（推荐）
docker compose up --build

# 本地运行（需要 MySQL 已启动）
cd reading-platform-java
mvn spring-boot:run

# 构建
mvn clean package -DskipTests

前端

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