# 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 约定 - 优先使用 `