En
48fc71b41d
- 修复 sys-config 接口参数对齐（configKey/configValue） - 添加 dict 字典项管理 API - 修复 logs 接口参数格式（批量删除/清理日志） - 添加 request.ts postForm/putForm 方法支持 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
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` - 构建/工具相关
|