181 lines
5.5 KiB
Markdown
181 lines
5.5 KiB
Markdown
|
# CLAUDE.md
|
|||
|
|
|
|||
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|||
|
|
|
|||
|
|
## 项目概述
|
|||
|
|
|
|||
|
|
多租户少儿绘本创作活动/竞赛管理平台，前后端分离架构。
|
|||
|
|
|
|||
|
|
## 目录结构
|
|||
|
|
|
|||
|
|
| 目录 | 说明 |
|
|||
|
|
|------|------|
|
|||
|
|
| `backend-java/` | Spring Boot 后端（实际开发目录） |
|
|||
|
|
| `frontend/` | Vue 3 前端（实际开发目录） |
|
|||
|
|
| `lesingle-aicreate-client/` | AI 绘本创作客户端（独立模块） |
|
|||
|
|
|
|||
|
|
## 常用命令
|
|||
|
|
|
|||
|
|
### 后端 (backend-java/)
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
cd backend-java
|
|||
|
|
mvn spring-boot:run -Dspring.profiles.active=dev # 开发启动（端口 8580，上下文 /api）
|
|||
|
|
mvn flyway:migrate # 执行数据库迁移
|
|||
|
|
mvn clean package # 构建打包
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 前端 (frontend/)
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
cd frontend
|
|||
|
|
npm run dev # 开发模式（端口 3000，代理 /api → localhost:8580）
|
|||
|
|
npm run build # 生产构建（base: /web/）
|
|||
|
|
npm run build:test # 测试环境构建（base: /web-test/）
|
|||
|
|
npm run lint # ESLint 检查
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### AI创作客户端 (lesingle-aicreate-client/)
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
cd lesingle-aicreate-client
|
|||
|
|
npm install && npm run dev # 独立启动
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 技术栈
|
|||
|
|
|
|||
|
|
| 层级 | 技术 |
|
|||
|
|
|------|------|
|
|||
|
|
| 后端框架 | Spring Boot 3.2.5 + Java 17 |
|
|||
|
|
| ORM | MyBatis-Plus 3.5.7 |
|
|||
|
|
| 数据库 | MySQL 8.0 + Flyway 迁移 |
|
|||
|
|
| 认证 | Spring Security + JWT |
|
|||
|
|
| 缓存 | Redis |
|
|||
|
|
| 工具库 | Hutool 5.8 + FastJSON2 + Knife4j 4.4（API文档） |
|
|||
|
|
| 前端框架 | Vue 3 + TypeScript + Vite 5 |
|
|||
|
|
| UI | Ant Design Vue 4.1 |
|
|||
|
|
| 状态管理 | Pinia |
|
|||
|
|
| 样式 | Tailwind CSS + SCSS |
|
|||
|
|
| 表单验证 | VeeValidate + Zod |
|
|||
|
|
| 富文本 | WangEditor |
|
|||
|
|
| 图表 | ECharts |
|
|||
|
|
|
|||
|
|
## 后端架构 (backend-java/)
|
|||
|
|
|
|||
|
|
### 基础包: `com.competition`
|
|||
|
|
|
|||
|
|
### 三层架构
|
|||
|
|
|
|||
|
|
| 层级 | 职责 | 规范 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| Controller | HTTP 请求处理、参数校验、Entity↔VO 转换 | 统一返回 `Result<T>` |
|
|||
|
|
| Service | 业务逻辑、事务控制 | 接口 `I{Module}Service`，继承 `IService<T>` |
|
|||
|
|
| Mapper | 数据库 CRUD | 继承 `BaseMapper<T>` |
|
|||
|
|
|
|||
|
|
**核心原则**: Service/Mapper 层使用 Entity，VO 转换只在 Controller 层。
|
|||
|
|
|
|||
|
|
### 模块划分
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
com.competition.modules/
|
|||
|
|
├── biz/
|
|||
|
|
│ ├── contest/ # 赛事管理（/contests）
|
|||
|
|
│ ├── homework/ # 作业管理（/homework）
|
|||
|
|
│ ├── judge/ # 评委管理
|
|||
|
|
│ └── review/ # 评审管理（/contest-reviews, /contest-results）
|
|||
|
|
├── sys/ # 系统管理（用户/角色/权限/租户，/sys/*）
|
|||
|
|
├── user/ # 用户模块
|
|||
|
|
├── ugc/ # 用户生成内容
|
|||
|
|
├── pub/ # 公开接口（/public/*，无需认证）
|
|||
|
|
└── oss/ # 对象存储（/oss/upload）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 实体基类 (BaseEntity)
|
|||
|
|
|
|||
|
|
所有实体继承 `BaseEntity`，包含字段：`id`、`createBy`、`updateBy`、`createTime`、`modifyTime`、`deleted`、`validState`。
|
|||
|
|
|
|||
|
|
表名规范：业务表 `t_biz_*`、系统表 `t_sys_*`、用户表 `t_user_*`。
|
|||
|
|
|
|||
|
|
### 多租户
|
|||
|
|
|
|||
|
|
- 所有业务表包含 `tenant_id` 字段
|
|||
|
|
- 获取租户ID: `SecurityUtil.getCurrentTenantId()`
|
|||
|
|
- 超级管理员 `isSuperAdmin()` 可访问所有租户数据
|
|||
|
|
- 请求头通过 `X-Tenant-Code`、`X-Tenant-Id` 传递
|
|||
|
|
|
|||
|
|
### 认证与权限
|
|||
|
|
|
|||
|
|
- JWT Token payload: `{sub: userId, username, tenantId}`
|
|||
|
|
- 公开接口: `@Public` 注解或路径 `/public/**`
|
|||
|
|
- 权限控制: `@RequirePermission` 注解
|
|||
|
|
|
|||
|
|
### 统一响应格式
|
|||
|
|
|
|||
|
|
```java
|
|||
|
|
Result<T> → {code, message, data, timestamp, path}
|
|||
|
|
PageResult<T> → {list, total, page, pageSize}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 数据库迁移
|
|||
|
|
|
|||
|
|
- 位置: `src/main/resources/db/migration/`
|
|||
|
|
- 命名: `V{number}__description.sql`（注意双下划线）
|
|||
|
|
- 不使用外键约束，关联关系通过代码控制
|
|||
|
|
|
|||
|
|
## 前端架构 (frontend/)
|
|||
|
|
|
|||
|
|
### 路由与多租户
|
|||
|
|
|
|||
|
|
- 路由路径包含租户编码: `/:tenantCode/login`、`/:tenantCode/dashboard`
|
|||
|
|
- 动态路由: 根据用户权限菜单动态生成
|
|||
|
|
- 双模式: 管理端（需认证）+ 公众端（无需认证）
|
|||
|
|
|
|||
|
|
### 三种布局
|
|||
|
|
|
|||
|
|
| 布局 | 用途 |
|
|||
|
|
|------|------|
|
|||
|
|
| BasicLayout | 管理端（侧边栏+顶栏+面包屑） |
|
|||
|
|
| PublicLayout | 公众端（简洁导航） |
|
|||
|
|
| EmptyLayout | 全屏页面 |
|
|||
|
|
|
|||
|
|
### API 调用模式
|
|||
|
|
|
|||
|
|
API 模块位于 `src/api/`，Axios 实例在 `src/utils/request.ts`：
|
|||
|
|
- 请求拦截器自动添加 Authorization token 和租户头
|
|||
|
|
- 响应拦截器统一错误处理（401 跳转登录，403 提示）
|
|||
|
|
- 函数命名: `getXxx`、`createXxx`、`updateXxx`、`deleteXxx`
|
|||
|
|
|
|||
|
|
### 权限控制
|
|||
|
|
|
|||
|
|
- 路由级: `meta.permissions`
|
|||
|
|
- 组件级: `v-permission` 自定义指令
|
|||
|
|
- 方法级: `hasPermission()`、`hasAnyPermission()`、`isSuperAdmin()`
|
|||
|
|
|
|||
|
|
### 状态管理
|
|||
|
|
|
|||
|
|
- auth Store: 用户信息、token、菜单、权限检查
|
|||
|
|
- Token 存储在 Cookie 中
|
|||
|
|
|
|||
|
|
## 开发规范
|
|||
|
|
|
|||
|
|
- **日志/注释使用中文**
|
|||
|
|
- **Git 提交格式**: `类型: 描述`（如 `feat: 添加XX功能`、`fix: 修复XX问题`）
|
|||
|
|
- **组件语法**: `<script setup lang="ts">`
|
|||
|
|
- **文件命名**: 组件 PascalCase，其他 kebab-case
|
|||
|
|
- **数据库**: 不使用外键，关联通过代码控制
|
|||
|
|
- **逻辑删除**: `deleted` 字段
|
|||
|
|
|
|||
|
|
## 环境配置
|
|||
|
|
|
|||
|
|
| 环境 | 后端 Profile | 前端 base | 后端端口 |
|
|||
|
|
|------|-------------|-----------|---------|
|
|||
|
|
| 开发 | dev | `/` | 8580 |
|
|||
|
|
| 测试 | test | `/web-test/` | 8580 |
|
|||
|
|
| 生产 | prod | `/web/` | 8580 |
|
|||
|
|
|
|||
|
|
## 注意事项
|
|||
|
|
|
|||
|
|
- `.cursor/rules/` 中部分规范（如 NestJS、Prisma）是旧版配置，当前后端已迁移至 Spring Boot + MyBatis-Plus，以本文件为准
|
|||
|
|
- 当前项目未配置测试框架
|
|||
|
|
- 当前项目未配置 i18n，所有文本为中文硬编码
|