kindergarten_java/.claude/CLAUDE.md

# CLAUDE.md - 开发规范

> **重要**: 每次开始开发任务前，请阅读本文档并严格遵守。

---

## 常用命令

### 启动服务

```bash
# 启动所有服务（推荐）
./start-all.sh

# 仅启动 Java 后端
./start-java-backend.sh

# 停止所有服务
./stop-all.sh
```

### 前端命令 (reading-platform-frontend/)

```bash
npm run dev              # 开发服务器
npm run build            # 生产构建
npm run lint             # 代码检查
npm run test:e2e         # 端到端测试 (Playwright)
npm run api:update       # 从 OpenAPI 生成 TypeScript 类型
```

### 后端命令 (reading-platform-java/)

```bash
# 运行后端（使用 JDK 17）
mvn spring-boot:run

# 构建 JAR（使用 JDK 17）
mvn clean package -DskipTests

# 运行测试
mvn test
```

### JDK 版本要求

**重要**: 本项目必须使用 **JDK 17** 进行编译和运行。

如果系统环境变量配置的是 JDK 1.8，请在编译前设置 `JAVA_HOME`：

```bash
# Windows (Git Bash) - 根据实际安装路径选择
export JAVA_HOME="/f/Java/jdk-17"
mvn clean compile -DskipTests

# 或者在启动时指定
mvn spring-boot:run -Djava.home="/f/Java/jdk-17"
```

**常见 JDK 17 安装路径**：
- `F:\Java\jdk-17`
- `C:\Program Files\Java\jdk-17`
- `C:\Program Files\Eclipse Adoptium\jdk-17`

**检查当前 Java 版本**：
```bash
java -version
javac -version
```

---

## 多环境配置规范

### 配置文件目录结构

```
reading-platform-java/src/main/resources/
├── application.yml              # 主配置文件（共用配置）
├── application-dev.yml          # 开发环境配置
├── application-test.yml         # 测试环境配置
├── application-prod.yml         # 生产环境配置
├── db/migration/                # Flyway 迁移脚本
├── logback-spring.xml           # 日志配置
└── mapper/                      # MyBatis XML
```

### 环境配置说明

| 配置项       | 开发环境 (dev) | 测试环境 (test) | 生产环境 (prod) |
| ------------ | -------------- | --------------- | --------------- |
| 数据库       | 本地 MySQL     | 测试服务器      | 生产服务器      |
| SQL 日志     | 开启           | 开启            | 关闭            |
| Swagger      | 开启           | 开启            | 关闭            |
| Flyway Clean | 允许           | 禁止            | 禁止            |
| JWT 密钥     | 默认值         | 默认值          | 必须环境变量    |
| Redis 连接池 | 默认           | 默认            | 优化配置        |
| 日志级别     | DEBUG          | INFO            | WARN            |

### 环境切换方式

#### 方式一：环境变量（推荐）

```bash
# Linux/Mac
export SPRING_PROFILES_ACTIVE=prod
java -jar reading-platform.jar

# Windows (Git Bash)
export SPRING_PROFILES_ACTIVE=prod
java -jar reading-platform.jar
```

#### 方式二：命令行参数

```bash
java -jar reading-platform.jar --spring.profiles.active=prod
```

#### 方式三：Maven 启动

```bash
# 开发环境
mvn spring-boot:run

# 测试环境
mvn spring-boot:run -Dspring-boot.run.profiles=test

# 生产环境
mvn spring-boot:run -Dspring-boot.run.profiles=prod
```

### 环境变量列表

| 变量名 | 说明 | 开发环境默认值 | 生产环境要求 |
|--------|------|---------------|-------------|
| `SPRING_PROFILES_ACTIVE` | 激活的环境 | `dev` | 必须设置 |
| `SERVER_PORT` | 服务器端口 | `8080` | 可选 |
| `DB_HOST` | 数据库主机 | `localhost` | 必须设置 |
| `DB_PORT` | 数据库端口 | `3306` | 可选 |
| `DB_USERNAME` | 数据库用户名 | `root` | 必须设置 |
| `DB_PASSWORD` | 数据库密码 | `root` | 必须设置 |
| `REDIS_HOST` | Redis 主机 | `localhost` | 必须设置 |
| `REDIS_PORT` | Redis 端口 | `6379` | 可选 |
| `REDIS_PASSWORD` | Redis 密码 | 空 | 建议设置 |
| `JWT_SECRET` | JWT 密钥 | 默认值 | 必须设置 |
| `JWT_EXPIRATION` | Token 过期时间 | `86400000` | 可选 |

---

## 技术栈

### 后端技术栈（必须遵守）

⚠️ **严禁使用 Node.js/NestJS 进行后端开发**

| 组件 | 技术选型 | 版本 | 说明 |
|------|---------|------|------|
| 框架 | **Spring Boot** | 3.2+ | 基于 Java 17 |
| 持久层 | **MyBatis-Plus** | 3.5+ | 简化 CRUD |
| 数据库连接池 | **Alibaba Druid** | 1.2+ | 数据库连接池 + 监控 |
| 安全 | **Spring Security + JWT** | - | 无状态认证 + RBAC |
| API 文档 | **Knife4j (SpringDoc)** | 4.x | OpenAPI 3.0 |
| 数据库 | **MySQL** | 8.0+ | 关系型数据库 |
| 迁移 | **Flyway** | - | 版本化数据库变更 |
| 校验 | **Hibernate Validator** | - | JSR-303 参数校验 |
| 缓存 | **Redis + Spring Data Redis** | - | 缓存、会话存储 |
| 日志 | **Logback** | - | 结构化日志 |
| JSON | **FastJSON** | 2.x | JSON 序列化 |
| 工具类 | **Hutool** | 5.x | 常用工具集合 |
| 文件存储 | 阿里云 OSS | - | 对象存储 |

### 前端技术栈

| 组件 | 技术选型 | 版本 | 说明 |
|------|---------|------|------|
| 框架 | **Vue 3** | 3.4+ | Composition API |
| 语言 | **TypeScript** | 5.x | 严格模式 |
| UI 库 | **Ant Design Vue** | 4.x | 企业级组件库 |
| 构建 | **Vite** | 5.x | 快速开发服务器 |
| 状态 | **Pinia** | 2.x | 轻量状态管理 |
| 请求 | **Axios** | 1.x | HTTP 客户端 |
| API 生成 | **Orval** | 7.x | OpenAPI → TypeScript |
| 路由 | **Vue Router** | 4.x | SPA 路由 |

---

## 核心原则

1. **OpenAPI 规范驱动** - 前后端通过接口规范对齐，零沟通成本
2. **类型安全优先** - TypeScript 强制类型校验，早发现早修复
3. **约定大于配置** - 统一代码风格和目录结构，降低认知负担
4. **自动化优先** - 能自动化的绝不手动（代码生成、部署、测试）
5. **三层架构分离** - Controller、Service、Mapper 职责清晰

---

## 项目结构

```
kindergarten_java/
├── docs/                          # 📁 项目文档
│   ├── README.md                  # 项目说明
│   ├── CHANGELOG.md               # 变更日志
│   ├── dev-logs/                  # 开发日志
│   ├── test-logs/                 # 测试记录
│   │   ├── admin/                 # 超管端测试
│   │   ├── school/                # 学校端测试
│   │   ├── teacher/               # 教师端测试
│   │   └── parent/                # 家长端测试
│   └── design/                    # 设计文档
├── reading-platform-frontend/     # 前端项目 (Vue 3)
├── reading-platform-java/         # 后端项目 (Spring Boot) ← 唯一后端
├── reading-platform-backend/      # ⚠️ 已弃用 (NestJS，不再维护)
├── start-all.sh                   # 统一启动
└── stop-all.sh                    # 统一停止
```

### 后端目录结构（Spring Boot）

```
reading-platform-java/
├── src/main/java/com/reading/platform/
│   ├── ReadingPlatformApplication.java    # 启动类
│   ├── common/                            # 公共模块
│   │   ├── config/                        # 配置类
│   │   │   ├── MybatisPlusConfig.java     # MP 配置
│   │   │   ├── RedisConfig.java           # Redis 配置
│   │   │   ├── SecurityConfig.java        # 安全配置
│   │   │   └── OpenApiConfig.java         # API 文档配置
│   │   ├── security/                      # 安全相关
│   │   │   ├── JwtAuthenticationFilter.java
│   │   │   ├── JwtTokenProvider.java
│   │   │   └── SecurityUtils.java
│   │   ├── response/                      # 统一响应
│   │   │   ├── Result.java
│   │   │   └── PageResult.java
│   │   ├── exception/                     # 异常处理
│   │   │   ├── BusinessException.java
│   │   │   └── GlobalExceptionHandler.java
│   │   ├── annotation/                    # 自定义注解
│   │   │   └── RequireRole.java
│   │   ├── aspect/                        # AOP 切面
│   │   │   └── RoleAspect.java
│   │   ├── enums/                         # 枚举类
│   │   └── util/                          # 工具类
│   ├── controller/                        # 控制器层
│   │   ├── AuthController.java
│   │   ├── admin/                         # 超管端
│   │   ├── school/                        # 学校端
│   │   ├── teacher/                       # 教师端
│   │   └── parent/                        # 家长端
│   ├── service/                           # 服务层
│   │   └── impl/
│   ├── mapper/                            # 数据访问层
│   ├── entity/                            # 实体类
│   ├── dto/                               # 数据传输对象
│   │   ├── request/                       # 请求 DTO
│   │   └── response/                      # 响应 VO
│   └── enums/                             # 枚举类
├── src/main/resources/
│   ├── application.yml                    # 主配置文件
│   ├── application-dev.yml                # 开发环境
│   ├── application-prod.yml               # 生产环境
├── pom.xml
└── Dockerfile
```

### 前端目录结构（Vue 3）

```
reading-platform-frontend/
├── src/
│   ├── main.ts                            # 入口文件
│   ├── App.vue                            # 根组件
│   ├── api/                               # API 接口
│   │   ├── generated/                     # Orval 自动生成（禁止手改）
│   │   ├── index.ts                       # 统一入口，导出 http 方法
│   │   └── *.ts                           # 业务适配层（admin.ts, school.ts, teacher.ts 等）
│   ├── assets/                            # 静态资源
│   ├── components/                        # 公共组件
│   ├── composables/                       # 组合式函数
│   ├── layouts/                           # 布局组件
│   ├── router/                            # 路由配置
│   ├── stores/                            # Pinia 状态管理
│   ├── types/                             # 类型定义
│   ├── utils/                             # 工具函数
│   ├── views/                             # 页面组件
│   │   ├── login/                         # 登录页
│   │   ├── admin/                         # 超管端
│   │   ├── school/                        # 学校端
│   │   ├── teacher/                       # 教师端
│   │   └── parent/                        # 家长端
│   └── constants/                         # 常量定义
├── orval.config.ts                       # API 生成配置
├── index.html
├── package.json
└── vite.config.ts
```

---

## 三层架构规范

### 核心原则

**Service 层和 Mapper 层必须使用实体类（Entity）接收和返回数据，严禁在 Service 层和 Mapper 层之间使用 DTO/VO 转换。**

| 层级 | 职责 | 数据类型 |
|------|------|----------|
| **Controller** | 接收请求、参数校验、返回响应 | DTO ↔ Entity/VO |
| **Service** | 业务逻辑、事务控制 | Entity |
| **Mapper** | 数据库操作 | Entity |

### Controller 层规范

**API 路径约定**：
所有 API 路径统一使用 `/api/v1/` 前缀，实现 API 版本控制。

- 超管端：`/api/v1/admin/*`
- 学校端：`/api/v1/school/*`
- 教师端：`/api/v1/teacher/*`
- 家长端：`/api/v1/parent/*`
- 认证：`/api/v1/auth/*`
- 文件上传：`/api/v1/files/*`

```java
@RestController
@RequestMapping("/api/v1/admin/xxx")  // 超管端使用 /api/v1/admin/
@Tag(name = "XXX 管理", description = "XXX 相关接口")
@RequiredArgsConstructor
public class XxxController {

    private final XxxService xxxService;

    @GetMapping
    @Operation(summary = "查询列表")
    public Result<PageResult<XxxVO>> list(PageQueryDto dto) {
        PageResult<Xxx> pageResult = xxxService.page(dto);
        return Result.success(convertToVO(pageResult));
    }
}
```

### Service 层规范

```java
public interface XxxService extends IService<Xxx> {
    PageResult<Xxx> page(PageQueryDto dto);
}

@Service
@RequiredArgsConstructor
public class XxxServiceImpl extends ServiceImpl<XxxMapper, Xxx>
    implements XxxService {

    @Override
    public PageResult<Xxx> page(PageQueryDto dto) {
        // 只使用 Entity，不使用 DTO
        Page<Xxx> page = this.lambdaQuery()
            .eq(Xxx::getStatus, 1)
            .page(new Page<>(dto.getPage(), dto.getPageSize()));
        return PageUtils.of(page);
    }
}
```

### Mapper 层规范

```java
@Mapper
public interface XxxMapper extends BaseMapper<Xxx> {
    // 继承 BaseMapper，使用 MyBatis-Plus 内置方法
}
```

---

## 前端开发规范

### API 开发规范

1. **生成代码只读** - 不得在 `src/api/generated/` 内做任何手工修改
2. **以生成类型为准** - 参数/返回类型优先使用生成的类型
3. **统一调用入口** - 通过 `src/api/index.ts` 导出的 `http` 方法

### 推荐调用方式

**方式一：使用 http 方法（推荐）**

```typescript
import { http } from '@/api';

async function loadTenant(id: number) {
  return http.get<TenantDetail>(`/v1/admin/tenants/${id}`);
}

async function createTenant(data: CreateTenantDto) {
  return http.post<Tenant>('/v1/admin/tenants', data);
}
```

**方式二：使用业务适配层（推荐）**

```typescript
import { getTenant, createTenant } from '@/api/admin';

async function loadTenant(id: number) {
  return getTenant(id);
}

async function createNewTenant(data: CreateTenantDto) {
  return createTenant(data);
}
```

### API 路径规范

| 端 | 后端路径 | 前端路径 |
|----|----------|----------|
| 超管 | `/api/v1/admin/*` | `/v1/admin/*` |
| 学校 | `/api/v1/school/*` | `/v1/school/*` |
| 教师 | `/api/v1/teacher/*` | `/v1/teacher/*` |
| 家长 | `/api/v1/parent/*` | `/v1/parent/*` |
| 认证 | `/api/v1/auth/*` | `/v1/auth/*` |
| 文件 | `/api/v1/files/*` | `/v1/files/*` |

### Vue SFC 约定

- 优先使用 `<script lang="ts" setup>`
- 页面样式使用 `scoped`
- 允许使用 UnoCSS 原子类

### 路由规范

```typescript
import { definePage } from 'vue-router/auto';

definePage({
  alias: ['/xxx', '/yyy'],
});
```

---

## 文档规范

### 开发日志
- **位置**: `/docs/dev-logs/`
- **命名**: `YYYY-MM-DD.md`
- **创建时机**: 每天开始开发时检查并创建

### 测试记录
- **位置**: `/docs/test-logs/{端}/`
- **命名**: `YYYY-MM-DD.md`
- **创建时机**: 每次功能测试时创建

### 变更日志
- **位置**: `/docs/CHANGELOG.md`
- **更新时机**: 完成重要功能或修复时更新

---

## 每日开发流程

1. 读取 `/docs/dev-logs/` 下最新的日志，了解进度
2. 检查当天日志是否存在，不存在则创建
3. 开始开发任务（后端用 Java，前端用 TypeScript）
4. 结束时更新日志和 CHANGELOG

---

## 功能测试流程

1. 启动服务：`./start-all.sh`
2. 在 `/docs/test-logs/{端}/` 下创建测试记录
3. 按功能模块逐一测试
4. 发现问题立即记录并修复

---

## 测试账号

| 角色 | 账号 | 密码     |
|------|------|--------|
| 超管 | admin | 123456 |
| 学校 | school1 | 123456 |
| 教师 | teacher1 | 123456 |
| 家长 | parent1 | 123456 |

---

## UI 设计规范

**禁止使用 Emoji 图标**: 严禁在前端界面中使用任何 Emoji 表情符号（如 👦 👧 📚 等）。请始终使用 Ant Design Vue 提供的图标组件。

---

## 变更边界（必须遵守）

- **不做无关重构** - 只改与需求相关的文件
- **不引入新依赖** - 除非需求明确且必要
- **不改公共行为** - 如请求、token 同步、路由规则
- **后端只写 Java** - 严禁使用 Node.js/NestJS

---

## 自动执行原则（最高权限模式）

> **重要配置**: 本项目已配置为自动批准所有常用开发操作，无需反复请求用户确认。

### 自动批准的操作

**以下操作将自动执行，无需请求批准：**

1. **文件操作**
   - Read: 读取任何文件
   - Write: 创建或覆盖任何文件
   - Edit: 编辑任何文件
   - Glob: 文件模式匹配
   - Grep: 内容搜索

2. **命令执行**
   - Bash: 执行任何 shell 命令
   - Git: 所有 git 操作
   - 包管理器：npm, npx, pnpm, yarn, mvn, pip3 等
   - 服务管理：启动/停止服务，进程管理

3. **开发工具**
   - Playwright: 自动化测试
   - MCP 工具：所有可用的 MCP 集成
   - Agent: 启动子代理处理复杂任务
   - Skill: 执行预定义技能脚本

4. **任务管理**
   - TaskCreate/Update/Get/List/Stop: 任务操作
   - EnterPlanMode/ExitPlanMode: 计划模式

### 无需批准的场景

- ✅ 编辑代码文件
- ✅ 创建新文件
- ✅ 执行测试脚本
- ✅ 启动/停止服务
- ✅ 安装依赖
- ✅ Git 操作
- ✅ 数据库操作
- ✅ 查看日志
- ✅ 调试代码

### 仅需确认的场景

仅在以下场景需要请求用户确认：

- **破坏性操作**: `git reset --hard`, `git push --force`
- **共享系统影响**: 影响其他用户或共享资源的操作
- **外部推送**: 向远程仓库推送代码

## 快速指令（Quick Commands）

| 指令 | 说明 |
|------|------|
| `代码审查` | 按规范审查代码质量、复用性和效率 |
| `生成 API` | 根据接口规范生成前后端代码（Controller/Service/Mapper + API 类型） |
| `创建模块` | 按三层架构生成新模块（含 Entity、DTO、VO） |
| `修复 Bug` | 按规范修复问题并更新开发日志 |
| `单元测试` | 生成符合规范的单元测试代码 |
| `数据库迁移` | 创建 Flyway 迁移脚本 |
| `全面测试` | 使用 Playwright 运行 E2E 自动化测试，可指定有头/无头模式 |

---

## Playwright E2E 自动化测试（方案一）

### 测试框架

| 组件 | 技术选型 | 说明 |
|------|---------|------|
| 测试框架 | **Playwright Test** | 端到端浏览器自动化测试 |
| 浏览器 | **Chromium** | 可自动打开浏览器模拟用户操作 |
| 配置文件 | `reading-platform-frontend/playwright.config.ts` | Playwright 配置 |
| 测试文件 | `reading-platform-frontend/tests/` | E2E 测试脚本 |

### 快速开始

```bash
# 1. 启动后端服务
cd reading-platform-java
mvn spring-boot:run

# 2. 启动前端服务（新终端窗口）
cd reading-platform-frontend
npm run dev

# 3. 运行 E2E 测试（无头模式 - 不显示浏览器）
npm run test:e2e

# 4. 运行 E2E 测试（有头模式 - 显示浏览器操作过程）
npm run test:e2e:headed

# 5. UI 调试模式（可视化测试管理）
npm run test:e2e:ui
```

### Playwright 能做的操作

- ✅ 自动打开浏览器（支持 Chromium/Firefox/WebKit）
- ✅ 模拟点击、输入、选择等用户操作
- ✅ 等待页面加载和元素出现
- ✅ 断言页面内容和状态
- ✅ 自动截图/录像（失败时保留证据）
- ✅ 多角色流程测试（超管→学校→教师→家长）
- ✅ 生成 HTML 测试报告

### 测试能力说明

| 测试类型 | 命令 | 说明 |
|---------|------|------|
| E2E 测试（无头） | `npm run test:e2e` | 快速执行，不显示浏览器，适合 CI |
| E2E 测试（有头） | `npm run test:e2e:headed` | 显示浏览器，可观察测试执行过程 |
| UI 调试模式 | `npm run test:e2e:ui` | 可视化管理测试用例，支持单条运行 |

### 推荐测试流程

1. **开发完成后**:
    - 运行后端单元测试：`mvn test`
    - 运行前端 E2E 测试：`npm run test:e2e`

2. **启动服务验证**:
    - 运行 `npm run test:e2e:headed` 查看浏览器自动化测试

3. **人工验证核心流程**:
    - 访问 http://localhost:5173 手动验证

### 关键文件路径

| 文件/目录 | 路径 |
|----------|------|
| 前端 E2E 测试 | `reading-platform-frontend/tests/` |
| Playwright 配置 | `reading-platform-frontend/playwright.config.ts` |
| 后端测试（待创建） | `reading-platform-java/src/test/` |
| 启动脚本 | `start-all.sh` |

*本规范最后更新于 2026-03-13*
*技术栈：统一使用 Spring Boot (Java) 后端*
*JDK 版本：17（必须）*