En 6e11c874d2 chore: 忽略 target 目录和 .class 文件

- 添加 target/ 到 .gitignore
- 从 git 暂存区移除已追踪的 target 目录

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-14 16:50:54 +08:00

20 KiB

Raw Blame History

CLAUDE.md - 开发规范

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

常用命令

启动服务

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

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

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

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

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

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

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

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

# 运行测试
mvn test

JDK 版本要求

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

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

# 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 版本：

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

环境切换方式

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

# 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

方式二：命令行参数

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

方式三：Maven 启动

# 开发环境
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 路由

核心原则

OpenAPI 规范驱动 - 前后端通过接口规范对齐，零沟通成本
类型安全优先 - TypeScript 强制类型校验，早发现早修复
约定大于配置 - 统一代码风格和目录结构，降低认知负担
自动化优先 - 能自动化的绝不手动（代码生成、部署、测试）
三层架构分离 - 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/*

@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 层规范

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 层规范

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

前端开发规范

API 开发规范

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

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 原子类

路由规范

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
更新时机: 完成重要功能或修复时更新

每日开发流程

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

功能测试流程

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

测试账号

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

UI 设计规范

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

变更边界（必须遵守）

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

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

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

自动批准的操作

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

文件操作
- Read: 读取任何文件
- Write: 创建或覆盖任何文件
- Edit: 编辑任何文件
- Glob: 文件模式匹配
- Grep: 内容搜索
命令执行
- Bash: 执行任何 shell 命令
- Git: 所有 git 操作
- 包管理器：npm, npx, pnpm, yarn, mvn, pip3 等
- 服务管理：启动/停止服务，进程管理
开发工具
- Playwright: 自动化测试
- MCP 工具：所有可用的 MCP 集成
- Agent: 启动子代理处理复杂任务
- Skill: 执行预定义技能脚本
任务管理
- 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 测试脚本

快速开始

# 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`	可视化管理测试用例，支持单条运行

关键文件路径

文件/目录	路径
前端 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（必须）

20 KiB Raw Blame History Unescape Escape

CLAUDE.md - 开发规范

常用命令

启动服务

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

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

JDK 版本要求

多环境配置规范

配置文件目录结构

环境配置说明

环境切换方式

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

方式二：命令行参数

方式三：Maven 启动

环境变量列表

技术栈

后端技术栈（必须遵守）

前端技术栈

核心原则

项目结构

后端目录结构（Spring Boot）

前端目录结构（Vue 3）

三层架构规范

核心原则

Controller 层规范

Service 层规范

Mapper 层规范

前端开发规范

API 开发规范

推荐调用方式

API 路径规范

Vue SFC 约定

路由规范

文档规范

开发日志

测试记录

变更日志

每日开发流程

功能测试流程

测试账号

UI 设计规范

变更边界（必须遵守）

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

自动批准的操作

无需批准的场景

仅需确认的场景

快速指令（Quick Commands）

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

测试框架

快速开始

Playwright 能做的操作

测试能力说明

推荐测试流程

关键文件路径

20 KiB

Raw Blame History