203 lines
5.5 KiB
Markdown
203 lines
5.5 KiB
Markdown
|
|
|||
|
|
# 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` - 构建/工具相关
|