En
98e9ad1d28
通过 VITE_AUTO_FILL_TEST 环境变量控制，在 .env.test 中启用， 使测试环境构建后登录框也能自动填充测试账号，方便测试人员使用。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
181 lines
5.6 KiB
Markdown
181 lines
5.6 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 项目概述
|
||
|
||
多租户少儿绘本创作活动/竞赛管理平台，前后端分离架构。
|
||
|
||
## 目录结构
|
||
|
||
| 目录 | 说明 |
|
||
|------|------|
|
||
| `lesingle-creation-backend/` | Spring Boot 后端（实际开发目录） |
|
||
| `lesingle-creation-frontend/` | Vue 3 前端（实际开发目录） |
|
||
| `lesingle-aicreate-client/` | AI 绘本创作客户端（独立模块） |
|
||
|
||
## 常用命令
|
||
|
||
### 后端 (lesingle-creation-backend/)
|
||
|
||
```bash
|
||
cd lesingle-creation-backend
|
||
mvn spring-boot:run -Dspring.profiles.active=dev # 开发启动（端口 8580，上下文 /api）
|
||
mvn flyway:migrate # 执行数据库迁移
|
||
mvn clean package # 构建打包
|
||
```
|
||
|
||
### 前端 (lesingle-creation-frontend/)
|
||
|
||
```bash
|
||
cd lesingle-creation-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 |
|
||
|
||
## 后端架构 (lesingle-creation-backend/)
|
||
|
||
### 基础包: `com.lesingle`
|
||
|
||
### 三层架构
|
||
|
||
| 层级 | 职责 | 规范 |
|
||
|------|------|------|
|
||
| Controller | HTTP 请求处理、参数校验、Entity↔VO 转换 | 统一返回 `Result<T>` |
|
||
| Service | 业务逻辑、事务控制 | 接口 `I{Module}Service`，继承 `IService<T>` |
|
||
| Mapper | 数据库 CRUD | 继承 `BaseMapper<T>` |
|
||
|
||
**核心原则**: Service/Mapper 层使用 Entity，VO 转换只在 Controller 层。
|
||
|
||
### 模块划分
|
||
|
||
```
|
||
com.lesingle.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`（注意双下划线）
|
||
- 不使用外键约束，关联关系通过代码控制
|
||
|
||
## 前端架构 (lesingle-creation-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，所有文本为中文硬编码
|