# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 快速开始

```bash
# 安装所有依赖（前端 + 后端）
pnpm install

# 同时启动前后端开发服务器
pnpm dev

# 或分别启动
pnpm dev:frontend   # 前端 http://localhost:3000
pnpm dev:backend    # 后端 http://localhost:3001
```

## 技术栈

### 后端
- **框架**: NestJS + TypeScript
- **数据库**: MySQL 8.0 + Prisma ORM
- **认证**: JWT + RBAC (基于角色的访问控制)
- **多租户**: 数据隔离架构（每个租户独立 tenantId）

### 前端
- **框架**: Vue 3 + TypeScript + Vite
- **UI 组件**: Ant Design Vue
- **状态管理**: Pinia
- **样式**: Tailwind CSS + SCSS

## 核心命令

### 开发
```bash
# 根目录
pnpm dev                    # 同时启动前后端
pnpm dev:frontend           # 只启动前端
pnpm dev:backend            # 只启动后端

# 前端目录
pnpm dev                    # 启动前端

# 后端目录
pnpm start:dev              # 启动后端
pnpm prisma:studio          # Prisma 数据库可视化
```

### 数据库迁移
```bash
cd backend
pnpm prisma:generate        # 生成 Prisma Client
pnpm prisma:migrate         # 开发环境迁移
pnpm prisma:migrate:deploy  # 生产环境部署
```

### 构建
```bash
pnpm build                  # 构建前后端
pnpm build:frontend         # 只构建前端
pnpm build:backend          # 只构建后端
```

### 测试
```bash
cd backend
pnpm test                   # 运行单元测试
pnpm test:cov               # 测试覆盖率
```

## 架构概览

### 目录结构
```
library-picturebook-activity/
├── backend/                    # NestJS 后端
│   ├── prisma/                 # Prisma schema 和 migrations
│   ├── src/
│   │   ├── auth/               # 认证模块 (JWT)
│   │   ├── users/              # 用户管理
│   │   ├── roles/              # 角色权限
│   │   ├── menus/              # 菜单管理
│   │   ├── tenants/            # 租户管理
│   │   ├── contests/           # 竞赛模块
│   │   │   ├── contests/       # 竞赛管理
│   │   │   ├── works/          # 作品管理
│   │   │   ├── teams/          # 团队管理
│   │   │   ├── registrations/  # 报名管理
│   │   │   └── reviews/        # 评审管理
│   │   ├── school/             # 学校模块
│   │   │   ├── schools/
│   │   │   ├── grades/
│   │   │   ├── classes/
│   │   │   ├── teachers/
│   │   │   └── students/
│   │   └── prisma/             # Prisma 服务
│   └── package.json
│
└── frontend/                   # Vue 3 前端
    ├── src/
    │   ├── api/                # API 接口
    │   ├── views/              # 页面组件
    │   ├── components/         # 公共组件
    │   ├── stores/             # Pinia 状态
    │   ├── router/             # 路由配置
    │   └── composables/        # 组合式函数
    └── package.json
```

### 模块结构（后端）
每个功能模块包含：
- `module.ts` - 模块定义
- `controller.ts` - REST 控制器
- `service.ts` - 业务逻辑
- `dto/` - 数据传输对象

### 多租户架构
- 所有业务数据必须包含 `tenantId` 字段
- 查询必须包含租户隔离条件
- 超级租户（`isSuper = 1`）可访问所有数据

## 关键开发规范

### 后端规范

1. **租户隔离（强制）**：所有数据库查询必须包含 `tenantId`
```typescript
// ✅ 正确
const data = await prisma.model.findMany({ where: { tenantId } });

// ❌ 错误 - 缺少 tenantId
const data = await prisma.model.findMany({});
```

2. **审计字段**：所有表必须包含
   - `tenantId` - 租户 ID
   - `creator`/`modifier` - 创建/修改人
   - `createTime`/`modifyTime` - 时间戳
   - `validState` - 有效状态（1-有效，2-失效）

3. **权限控制**：使用 `@RequirePermission('module:action')` 装饰器

4. **DTO 验证**：使用 `class-validator` 装饰器

### 前端规范

1. **路由包含租户编码**：`/:tenantCode/xxx`

2. **API 调用**：放在 `api/` 目录，按模块组织

3. **状态管理**：使用 Pinia，store 命名 `xxxStore`

4. **组件语法**：使用 `<script setup lang="ts">`

## 环境变量

### 后端 (.env)
```env
DATABASE_URL="mysql://user:password@localhost:3306/db_name"
JWT_SECRET="your-secret-key"
PORT=3001
```

### 前端 (.env.development)
```env
VITE_API_BASE_URL=/api
```

## 初始化脚本（后端）

```bash
pnpm init:admin              # 初始化管理员账户
pnpm init:menus              # 初始化菜单
pnpm init:super-tenant       # 初始化超级租户
pnpm init:tenant-admin       # 初始化租户管理员
pnpm init:roles:all          # 初始化所有角色权限
```

## Cursor Rules

项目使用 `.cursor/rules/` 目录定义开发规范：
- `project-overview.mdc` - 项目概述
- `backend-architecture.mdc` - 后端架构规范
- `frontend-architecture.mdc` - 前端架构规范
- `database-design.mdc` - 数据库设计规范
- `multi-tenant.mdc` - 多租户数据隔离规范
- `code-review-checklist.mdc` - 代码审查清单

## Git 提交规范

格式：`类型: 描述`

类型：
- `feat` - 新功能
- `fix` - 修复 bug
- `docs` - 文档更新
- `style` - 代码格式调整
- `refactor` - 代码重构
- `test` - 测试相关
- `chore` - 构建/工具相关