066b1f2257
## P0 三层架构违规修复 (4项) - 创建 SchoolStatsService/TeacherStatsService，移除Controller直接调用Mapper - 修复 AdminCourseController 使用 Service 层方法 - 修复 TeacherCourseController 使用 ClassService 获取班级 - 新增 ClassService.getActiveClassesByTenantId() - 新增 CourseService.createSystemCourse() ## P1 API 路径统一 (8项) 后端路径统一为 /api/v1/admin/*: - AdminCourseController: /api/admin/courses → /api/v1/admin/courses - AdminTenantController: /api/admin/tenants → /api/v1/admin/tenants 前端配置调整: - vite.config.ts: 移除代理重写规则 - src/api/index.ts: baseURL /api/v1 → /api - 更新 admin.ts, lesson.ts, package.ts, theme.ts 使用 /v1/admin/* 路径 ## P2 文档规范更新 (5项) - 更新 CLAUDE.md 前端 API 调用文档 - 新增三种调用方式说明（http/适配层/Orval客户端） - 新增 API 路径规范表格 - 更新前端目录结构说明 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
442 lines
14 KiB
Markdown
442 lines
14 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 自动生成（禁止手改）
|
||
│ │ ├── 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/*`
|
||
|
||
```java
|
||
@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 层规范
|
||
|
||
```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 开发规范
|
||
|
||
1. **生成代码只读** - 不得在 `src/api/generated/` 内做任何手工修改
|
||
2. **以生成类型为准** - 参数/返回类型优先使用生成的类型
|
||
3. **统一调用入口** - 通过 `src/api/index.ts` 导出的 `http` 方法
|
||
|
||
### 推荐调用方式
|
||
|
||
**方式一：使用 http 方法（推荐）**
|
||
|
||
```typescript
|
||
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);
|
||
}
|
||
```
|
||
|
||
**方式二：使用业务适配层（推荐）**
|
||
|
||
```typescript
|
||
import { getTenant, createTenant } from '@/api/admin';
|
||
|
||
async function loadTenant(id: number) {
|
||
return getTenant(id);
|
||
}
|
||
|
||
async function createNewTenant(data: CreateTenantDto) {
|
||
return createTenant(data);
|
||
}
|
||
```
|
||
|
||
**方式三：使用 Orval 生成的客户端（可选）**
|
||
|
||
```typescript
|
||
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 原子类
|
||
|
||
### 路由规范
|
||
|
||
```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
|
||
|
||
---
|
||
|
||
## 自动执行原则（最高权限模式）
|
||
|
||
> **重要配置**: 本项目已配置为自动批准所有常用开发操作，无需反复请求用户确认。
|
||
|
||
### 自动批准的操作
|
||
|
||
**以下操作将自动执行，无需请求批准：**
|
||
|
||
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) 后端*
|
||
*权限更新：配置最高权限自动批准模式*
|