diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 7a108bf..9769735 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -1,6 +1,265 @@ # 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> list(PageQueryDto dto) { + PageResult pageResult = xxxService.page(dto); + return Result.success(convertToVO(pageResult)); + } +} +``` + +### Service 层规范 + +```java +public interface XxxService extends IService { + PageResult page(PageQueryDto dto); +} + +@Service +@RequiredArgsConstructor +public class XxxServiceImpl extends ServiceImpl + implements XxxService { + + @Override + public PageResult page(PageQueryDto dto) { + // 只使用 Entity，不使用 DTO + Page 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 { + // 继承 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 约定 + +- 优先使用 `