# 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，所有文本为中文硬编码