100 lines
3.6 KiB
Plaintext
100 lines
3.6 KiB
Plaintext
# Telegram Bot with Admin Panel Starter - Cursor Rules
|
|
|
|
## Project Overview
|
|
This is a starter template for building Telegram bots with web-based admin panels.
|
|
|
|
**Tech Stack:**
|
|
- Backend: NestJS 11, TypeORM, PostgreSQL, Grammy (Telegram Bot Framework)
|
|
- Frontend: React 18, Vite, Mantine UI 7, React Query, Zod
|
|
- Infrastructure: Docker Compose
|
|
|
|
## Code Style & Conventions
|
|
|
|
### TypeScript
|
|
- Use strict typing - avoid `any` when possible
|
|
- Prefer interfaces over types for object shapes
|
|
- Use enums for fixed sets of values
|
|
- Always define return types for functions
|
|
- Use JSDoc comments for public APIs
|
|
|
|
### NestJS Backend
|
|
- Follow NestJS module structure: Controller → Service → Repository pattern
|
|
- Use DTOs with class-validator for all request/response validation
|
|
- Use decorators from `@nestjs/common` consistently
|
|
- Services should contain business logic, controllers only handle HTTP
|
|
- Use dependency injection - avoid direct instantiation
|
|
- Use guards for authentication/authorization
|
|
- Use interceptors for response transformation
|
|
- Use custom decorators for common patterns (pagination, filtering, sorting)
|
|
|
|
### React Frontend
|
|
- Use functional components with hooks
|
|
- Use React Query for all API calls
|
|
- Use Zod schemas for type-safe API validation
|
|
- Use Mantine components consistently
|
|
- Create reusable hooks for common patterns
|
|
- Use TypeScript paths (@/*) for imports
|
|
- Keep components small and focused
|
|
|
|
### Database
|
|
- Use TypeORM entities with decorators
|
|
- All entities extend `AbstractEntity` (id, created_at, updated_at)
|
|
- Use migrations for all schema changes
|
|
- Never use `synchronize: true` in production
|
|
- Use relations properly (OneToOne, OneToMany, ManyToMany)
|
|
|
|
### API Design
|
|
- RESTful endpoints: GET, POST, PATCH, DELETE
|
|
- Use consistent response format: `{ statusCode, message, data }`
|
|
- Pagination: `page` (1-indexed) and `size` (default 25)
|
|
- Sorting: `sortBy` and `sortOrder` (asc/desc)
|
|
- Filtering: use `FilteringParams` decorator with filter rules (eq, neq, like, etc.)
|
|
- Use JWT for authentication
|
|
- Protect routes with `@UseGuards(AuthGuard)`
|
|
|
|
### File Naming
|
|
- Controllers: `*.controller.ts`
|
|
- Services: `*.service.ts`
|
|
- Entities: `*.entity.ts`
|
|
- DTOs: `*.dto.ts`
|
|
- Guards: `*.guard.ts`
|
|
- Decorators: `*.decorator.ts`
|
|
- Modules: `*.module.ts`
|
|
|
|
### Git
|
|
- Use conventional commits
|
|
- Keep commits focused and atomic
|
|
- Never commit `.env` files or secrets
|
|
|
|
## Common Patterns
|
|
|
|
### Creating a New Feature Module
|
|
1. Create module folder: `back/src/feature-name/`
|
|
2. Create entity: `entities/feature-name.entity.ts`
|
|
3. Create DTOs: `dto/create-feature-name.dto.ts`, `dto/update-feature-name.dto.ts`
|
|
4. Create service: `feature-name.service.ts`
|
|
5. Create controller: `feature-name.controller.ts`
|
|
6. Create module: `feature-name.module.ts`
|
|
7. Register in `app.module.ts`
|
|
8. Create migration: `pnpm migration:generate --name=create-feature-name`
|
|
|
|
### Adding Bot Commands
|
|
1. Add handler method in `BotService`
|
|
2. Register in `onModuleInit()`: `this.bot.command('command', this.handler.bind(this))`
|
|
3. Use Grammy Context types for type safety
|
|
|
|
### Adding Frontend Pages
|
|
1. Create page component in `front/src/pages/`
|
|
2. Add route in `front/src/routes/`
|
|
3. Create API hooks in `front/src/hooks/api/`
|
|
4. Create Zod schemas in `front/src/api/dtos/`
|
|
5. Use Mantine components for UI
|
|
|
|
## Important Notes
|
|
- Always validate environment variables in `config/env/env.validation.ts`
|
|
- Use `ConfigService` to access environment variables
|
|
- Static files served from `/uploads` endpoint
|
|
- Database migrations run automatically on container start
|
|
- Use `pnpm` as package manager (not npm or yarn)
|
|
- Node.js v20+ required (v22 recommended)
|