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 自动生成（禁止手改）
│   │   ├── 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/v1/admin/*
• 学校端：/api/school/*
• 教师端：/api/teacher/*
• 家长端：/api/parent/*
• 认证：/api/auth/*

@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 开发规范

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

推荐调用方式

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

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);
}

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

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

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

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

方式三：使用 Orval 生成的客户端（可选）

import { getReadingPlatformAPI } from '@/api/generated';

const api = getReadingPlatformAPI();

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

API 路径规范

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

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

---

每日开发流程

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 提供的图标组件。

---

服务启动

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

---

变更边界（必须遵守）

• 不做无关重构 - 只改与需求相关的文件
• 不引入新依赖 - 除非需求明确且必要
• 不改公共行为 - 如请求、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
• 共享系统影响: 影响其他用户或共享资源的操作
• 外部推送: 向远程仓库推送代码

---

本规范创建于 2026-02-22 最后更新于 2026-03-13 技术栈更新：统一使用 Spring Boot (Java) 后端 权限更新：配置最高权限自动批准模式