library-picturebook-activity/CLAUDE.md

CLAUDE.md

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

快速开始

# 安装所有依赖（前端 + 后端）
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

核心命令

开发

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

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

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

数据库迁移

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

构建

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

测试

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

// ✅ 正确
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)

DATABASE_URL="mysql://user:password@localhost:3306/db_name"
JWT_SECRET="your-secret-key"
PORT=3001

前端 (.env.development)

VITE_API_BASE_URL=/api

初始化脚本（后端）

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 - 构建/工具相关