081fac9d97
完成从Node.js/NestJS到Java Spring Boot的后端迁移，修复资源管理API错误。 **核心修复：** - 修复资源库API 500错误 - ResourceLibrary/ResourceItem实体与数据库表结构对齐 - 更新ID类型从Long改为String，匹配数据库varchar(32) - 修正字段映射（libraryType → type） **新增Java实体（7个）：** - CoursePackage, CoursePackageCourse, TenantPackage - CourseLesson, LessonStep, LessonStepResource - Theme **新增API控制器（5个）：** - AdminResourceController - 资源库管理 - AdminPackageController - 课程套餐管理 - AdminCourseLessonController - 课程环节管理 - AdminThemeController - 主题字典管理 - SchoolPackageController - 学校套餐管理 **新增服务层（5个）：** - ResourceLibraryService, CoursePackageService, CourseLessonService - ThemeService, FileStorageService **文档更新：** - 新增 Java环境配置与启动指南.md - 新增 Java后端启动完整指南.md - 新增 数据库迁移指南.md - 更新 CHANGELOG.md 和开发日志 **前端修复：** - 解决package.json合并冲突 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
340 lines
11 KiB
Markdown
340 lines
11 KiB
Markdown
# 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) 后端*
|