kindergarten_java/.claude/CLAUDE.md

# Claude 开发规范

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

---

## 技术栈决策

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

⚠️ **严禁使用 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 职责清晰

---

## 项目结构

```
ccProgram_0312/
├── 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 自动生成（禁止手改）
│   │   ├── client.ts                      # 统一入口
│   │   └── *.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 层规范

```java
@RestController
@RequestMapping("/api/v1/xxx")
@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 开发规范（Orval）

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

### 推荐调用方式

```typescript
import { readingApi } from '@/api/client';

async function loadTenant(id: number) {
  const res = await readingApi.getTenant({ id });
  return res.data;
}
```

### 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 | admin123 |
| 学校 | school1 | 123456 |
| 教师 | teacher1 | 123456 |
| 家长 | parent1 | 123456 |

---

## UI 设计规范

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

---

## 服务启动

```bash
cd /Users/retirado/Program/ccProgram_0312
./start-all.sh
```

---

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

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

---

*本规范创建于 2026-02-22*
*最后更新于 2026-03-12*
*技术栈更新：统一使用 Spring Boot (Java) 后端*