library-picturebook-activity/AGENTS.md

Competition Management System - Agent Instructions

这是一个多租户的竞赛管理系统，采用 NestJS + Vue 3 技术栈。

🚨 最重要的规则

多租户数据隔离

所有数据库查询必须包含 tenantId 条件！ 这是系统安全的核心。

// ✅ 正确
const users = await prisma.user.findMany({
  where: { tenantId, validState: 1 }
});

// ❌ 错误 - 绝对不允许
const users = await prisma.user.findMany();

后端开发

模块结构

• 使用 NestJS 标准模块结构：module、controller、service、dto
• 所有数据操作通过 Prisma，禁止直接 SQL
• 使用 @Injectable()、@Controller() 装饰器

权限控制

• 使用 @RequirePermission('module:action') 装饰器
• 格式：user:create、contest:update、role:delete
• 所有路由默认需要认证，公开接口使用 @Public()

DTO 验证

export class CreateUserDto {
  @IsString()
  username: string;

  @IsEmail()
  @IsOptional()
  email?: string;
}

错误处理

• 使用 NestJS 内置异常，消息用中文
• NotFoundException、BadRequestException、ForbiddenException

前端开发

组件开发

• 使用 Vue 3 <script setup lang="ts"> 语法
• 页面组件放在 views/ 目录，按模块组织
• 使用 Ant Design Vue 组件库

API 调用

• API 文件放在 api/ 目录，按模块组织
• 函数命名：getXxx、createXxx、updateXxx、deleteXxx
• 使用 TypeScript 类型定义

路由

• 路由路径必须包含租户编码：/:tenantCode/users
• 使用动态路由（基于菜单权限）

状态管理

• 使用 Pinia，store 命名：useAuthStore、useUserStore

数据库设计

必需字段

所有业务表必须包含：

model YourModel {
  id          Int      @id @default(autoincrement())
  tenantId    Int      @map("tenant_id")
  validState  Int      @default(1) @map("valid_state")
  creator     Int?
  modifier    Int?
  createTime  DateTime @default(now()) @map("create_time")
  modifyTime  DateTime @updatedAt @map("modify_time")
}

性能优化

• 使用 include 预加载，避免 N+1 查询
• 使用 select 精简字段
• 实现分页查询

代码风格

• TypeScript 严格模式
• 使用 async/await，避免 Promise.then()
• 使用中文注释
• Git 提交信息：类型: 描述（如 feat: 添加用户管理）

快速参考

创建新模块

1. 在 Prisma schema 定义模型
2. 运行 pnpm prisma:migrate:dev
3. 创建 NestJS 模块（module、controller、service、dto）
4. 在 app.module.ts 注册
5. 创建前端 API 和页面

常用装饰器

• @CurrentTenantId() - 获取租户ID
• @CurrentUser() - 获取当前用户
• @RequirePermission() - 权限检查
• @Public() - 公开接口

开发命令

# 后端
cd backend
pnpm start:dev              # 启动开发服务器
pnpm prisma:migrate:dev     # 数据库迁移
pnpm init:admin             # 初始化管理员

# 前端
cd frontend
pnpm dev                    # 启动开发服务器
pnpm build                  # 构建生产版本

---

💡 记住：租户隔离是系统的核心安全机制，所有数据操作都必须验证 tenantId！