Skip to content

Commit a128192

Browse files
DavidsonGomesDavidsonGomes
committed
Merge branch 'release/2.3.3'
2 parents c2085b5 + 250cb61 commit a128192

File tree

68 files changed

+14427
-1807
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

68 files changed

+14427
-1807
lines changed

‎.cursor/rules/README.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Evolution API Cursor Rules
2+
3+
Este diretório contém as regras e configurações do Cursor IDE para o projeto Evolution API.
4+
5+
## Estrutura dos Arquivos
6+
7+
### Arquivos Principais (alwaysApply: true)
8+
- **`core-development.mdc`** - Princípios fundamentais de desenvolvimento
9+
- **`project-context.mdc`** - Contexto específico do projeto Evolution API
10+
- **`cursor.json`** - Configurações do Cursor IDE
11+
12+
### Regras Especializadas (alwaysApply: false)
13+
Estas regras são ativadas automaticamente quando você trabalha nos arquivos correspondentes:
14+
15+
#### Camadas da Aplicação
16+
- **`specialized-rules/service-rules.mdc`** - Padrões para services (`src/api/services/`)
17+
- **`specialized-rules/controller-rules.mdc`** - Padrões para controllers (`src/api/controllers/`)
18+
- **`specialized-rules/dto-rules.mdc`** - Padrões para DTOs (`src/api/dto/`)
19+
- **`specialized-rules/guard-rules.mdc`** - Padrões para guards (`src/api/guards/`)
20+
- **`specialized-rules/route-rules.mdc`** - Padrões para routers (`src/api/routes/`)
21+
22+
#### Tipos e Validação
23+
- **`specialized-rules/type-rules.mdc`** - Definições TypeScript (`src/api/types/`)
24+
- **`specialized-rules/validate-rules.mdc`** - Schemas de validação (`src/validate/`)
25+
26+
#### Utilitários
27+
- **`specialized-rules/util-rules.mdc`** - Funções utilitárias (`src/utils/`)
28+
29+
#### Integrações
30+
- **`specialized-rules/integration-channel-rules.mdc`** - Integrações de canal (`src/api/integrations/channel/`)
31+
- **`specialized-rules/integration-chatbot-rules.mdc`** - Integrações de chatbot (`src/api/integrations/chatbot/`)
32+
- **`specialized-rules/integration-storage-rules.mdc`** - Integrações de storage (`src/api/integrations/storage/`)
33+
- **`specialized-rules/integration-event-rules.mdc`** - Integrações de eventos (`src/api/integrations/event/`)
34+
35+
## Como Usar
36+
37+
### Referências Cruzadas
38+
Os arquivos principais fazem referência aos especializados usando a sintaxe `@specialized-rules/nome-do-arquivo.mdc`. Quando você trabalha em um arquivo específico, o Cursor automaticamente carrega as regras relevantes.
39+
40+
### Exemplo de Uso
41+
Quando você edita um arquivo em `src/api/services/`, o Cursor automaticamente:
42+
1. Carrega `core-development.mdc` (sempre ativo)
43+
2. Carrega `project-context.mdc` (sempre ativo)
44+
3. Carrega `specialized-rules/service-rules.mdc` (ativado pelo glob pattern)
45+
46+
### Padrões de Código
47+
Cada arquivo de regras contém:
48+
- **Estruturas padrão** - Como organizar o código
49+
- **Padrões de nomenclatura** - Convenções de nomes
50+
- **Exemplos práticos** - Código de exemplo
51+
- **Anti-padrões** - O que evitar
52+
- **Testes** - Como testar o código
53+
- **Padrões de Commit** - Conventional Commits com commitlint
54+
55+
## Configuração do Cursor
56+
57+
O arquivo `cursor.json` contém:
58+
- Configurações de formatação
59+
- Padrões de código específicos do Evolution API
60+
- Diretórios principais do projeto
61+
- Integrações e tecnologias utilizadas
62+
63+
## Manutenção
64+
65+
Para manter as regras atualizadas:
66+
1. Analise novos padrões no código
67+
2. Atualize as regras especializadas correspondentes
68+
3. Mantenha os exemplos sincronizados com o código real
69+
4. Documente mudanças significativas
70+
71+
## Tecnologias Cobertas
72+
73+
- **Backend**: Node.js 20+ + TypeScript 5+ + Express.js
74+
- **Database**: Prisma ORM (PostgreSQL/MySQL)
75+
- **Cache**: Redis + Node-cache
76+
- **Queue**: RabbitMQ + Amazon SQS
77+
- **Real-time**: Socket.io
78+
- **Storage**: AWS S3 + Minio
79+
- **Validation**: JSONSchema7
80+
- **Logging**: Pino
81+
- **WhatsApp**: Baileys + Meta Business API
82+
- **Integrations**: Chatwoot, Typebot, OpenAI, Dify
83+
84+
## Estrutura do Projeto
85+
86+
```
87+
src/
88+
├── api/
89+
│ ├── controllers/ # Controllers (HTTP handlers)
90+
│ ├── services/ # Business logic
91+
│ ├── dto/ # Data Transfer Objects
92+
│ ├── guards/ # Authentication/Authorization
93+
│ ├── routes/ # Express routers
94+
│ ├── types/ # TypeScript definitions
95+
│ └── integrations/ # External integrations
96+
│ ├── channel/ # WhatsApp channels (Baileys, Business API)
97+
│ ├── chatbot/ # Chatbot integrations
98+
│ ├── event/ # Event integrations
99+
│ └── storage/ # Storage integrations
100+
├── cache/ # Cache implementations
101+
├── config/ # Configuration files
102+
├── utils/ # Utility functions
103+
├── validate/ # Validation schemas
104+
└── exceptions/ # Custom exceptions
105+
```
106+
107+
Este sistema de regras garante consistência no código e facilita o desenvolvimento seguindo os padrões estabelecidos do Evolution API.

‎.cursor/rules/core-development.mdc‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
---
2+
description: Core development principles and standards for Evolution API development
3+
globs:
4+
alwaysApply: true
5+
---
6+
7+
# Evolution API Development Standards
8+
9+
## Cross-References
10+
- **Project Context**: @project-context.mdc for Evolution API-specific patterns
11+
- **Specialized Rules**:
12+
- @specialized-rules/service-rules.mdc for service layer patterns
13+
- @specialized-rules/controller-rules.mdc for controller patterns
14+
- @specialized-rules/dto-rules.mdc for DTO validation patterns
15+
- @specialized-rules/guard-rules.mdc for authentication/authorization
16+
- @specialized-rules/route-rules.mdc for router patterns
17+
- @specialized-rules/type-rules.mdc for TypeScript definitions
18+
- @specialized-rules/util-rules.mdc for utility functions
19+
- @specialized-rules/validate-rules.mdc for validation schemas
20+
- @specialized-rules/integration-channel-rules.mdc for channel integrations
21+
- @specialized-rules/integration-chatbot-rules.mdc for chatbot integrations
22+
- @specialized-rules/integration-storage-rules.mdc for storage integrations
23+
- @specialized-rules/integration-event-rules.mdc for event integrations
24+
- **TypeScript/Node.js**: Node.js 20+ + TypeScript 5+ best practices
25+
- **Express/Prisma**: Express.js + Prisma ORM patterns
26+
- **WhatsApp Integrations**: Baileys + Meta Business API patterns
27+
28+
## Senior Engineer Context - Evolution API Platform
29+
- You are a senior software engineer working on a WhatsApp API platform
30+
- Focus on Node.js + TypeScript + Express.js full-stack development
31+
- Specialized in real-time messaging, WhatsApp integrations, and event-driven architecture
32+
- Apply scalable patterns for multi-tenant API platform
33+
- Consider WhatsApp integration workflow implications and performance at scale
34+
35+
## Fundamental Principles
36+
37+
### Code Quality Standards
38+
- **Simplicity First**: Always prefer simple solutions over complex ones
39+
- **DRY Principle**: Avoid code duplication - check for existing similar functionality before implementing
40+
- **Single Responsibility**: Each function/class should have one clear purpose
41+
- **Readable Code**: Write code that tells a story - clear naming and structure
42+
43+
### Problem Resolution Approach
44+
- **Follow Existing Patterns**: Use established Service patterns, DTOs, and Integration patterns
45+
- **Event-Driven First**: Leverage EventEmitter2 for event publishing when adding new features
46+
- **Integration Pattern**: Follow existing WhatsApp integration patterns for new channels
47+
- **Conservative Changes**: Prefer extending existing services over creating new architecture
48+
- **Clean Migration**: Remove deprecated patterns when introducing new ones
49+
- **Incremental Changes**: Break large changes into smaller, testable increments with proper migrations
50+
51+
### File and Function Organization - Node.js/TypeScript Structure
52+
- **Services**: Keep services focused and under 200 lines
53+
- **Controllers**: Keep controllers thin - only routing and validation
54+
- **DTOs**: Use JSONSchema7 for all input validation
55+
- **Integrations**: Follow `src/api/integrations/` structure for new integrations
56+
- **Utils**: Extract common functionality into well-named utilities
57+
- **Types**: Define clear TypeScript interfaces and types
58+
59+
### Code Analysis and Reflection
60+
- After writing code, deeply reflect on scalability and maintainability
61+
- Provide 1-2 paragraph analysis of code changes
62+
- Suggest improvements or next steps based on reflection
63+
- Consider performance, security, and maintenance implications
64+
65+
## Development Standards
66+
67+
### TypeScript Standards
68+
- **Strict Mode**: Always use TypeScript strict mode
69+
- **No Any**: Avoid `any` type - use proper typing
70+
- **Interfaces**: Define clear contracts with interfaces
71+
- **Enums**: Use enums for constants and status values
72+
- **Generics**: Use generics for reusable components
73+
74+
### Error Handling Standards
75+
- **HTTP Exceptions**: Use appropriate HTTP status codes
76+
- **Logging**: Structured logging with context
77+
- **Retry Logic**: Implement retry for external services
78+
- **Graceful Degradation**: Handle service failures gracefully
79+
80+
### Security Standards
81+
- **Input Validation**: Validate all inputs with JSONSchema7
82+
- **Authentication**: Use API keys and JWT tokens
83+
- **Rate Limiting**: Implement rate limiting for APIs
84+
- **Data Sanitization**: Sanitize sensitive data in logs
85+
86+
### Performance Standards
87+
- **Caching**: Use Redis for frequently accessed data
88+
- **Database**: Optimize Prisma queries with proper indexing
89+
- **Memory**: Monitor memory usage and implement cleanup
90+
- **Async**: Use async/await properly with error handling
91+
92+
## Communication Standards
93+
94+
### Language Requirements
95+
- **User Communication**: Always respond in Portuguese (PT-BR)
96+
- **Code Comments**: English for technical documentation
97+
- **API Documentation**: English for consistency
98+
- **Error Messages**: Portuguese for user-facing errors
99+
100+
### Documentation Standards
101+
- **Code Comments**: Document complex business logic
102+
- **API Documentation**: Document all public endpoints
103+
- **README**: Keep project documentation updated
104+
- **Changelog**: Document breaking changes
105+
106+
## Quality Assurance
107+
108+
### Testing Standards
109+
- **Unit Tests**: Test business logic in services
110+
- **Integration Tests**: Test API endpoints
111+
- **Mocks**: Mock external dependencies
112+
- **Coverage**: Aim for 70%+ test coverage
113+
114+
### Code Review Standards
115+
- **Peer Review**: All code must be reviewed
116+
- **Automated Checks**: ESLint, Prettier, TypeScript
117+
- **Security Review**: Check for security vulnerabilities
118+
- **Performance Review**: Check for performance issues
119+
120+
### Commit Standards (Conventional Commits)
121+
- **Format**: `type(scope): subject` (max 100 characters)
122+
- **Types**:
123+
- `feat` - New feature
124+
- `fix` - Bug fix
125+
- `docs` - Documentation changes
126+
- `style` - Code style changes (formatting, etc)
127+
- `refactor` - Code refactoring
128+
- `perf` - Performance improvements
129+
- `test` - Adding or updating tests
130+
- `chore` - Maintenance tasks
131+
- `ci` - CI/CD changes
132+
- `build` - Build system changes
133+
- `revert` - Reverting changes
134+
- `security` - Security fixes
135+
- **Examples**:
136+
- `feat(api): add WhatsApp message status endpoint`
137+
- `fix(baileys): resolve connection timeout issue`
138+
- `docs(readme): update installation instructions`
139+
- `refactor(service): extract common message validation logic`
140+
- **Tools**: Use `npm run commit` (Commitizen) for guided commits
141+
- **Validation**: Enforced by commitlint on commit-msg hook
142+
143+
## Evolution API Specific Patterns
144+
145+
### WhatsApp Integration Patterns
146+
- **Connection Management**: One connection per instance
147+
- **Event Handling**: Proper event listeners for Baileys
148+
- **Message Processing**: Queue-based message processing
149+
- **Error Recovery**: Automatic reconnection logic
150+
151+
### Multi-Database Support
152+
- **Schema Compatibility**: Support PostgreSQL and MySQL
153+
- **Migration Sync**: Keep migrations synchronized
154+
- **Type Safety**: Use Prisma generated types
155+
- **Connection Pooling**: Proper database connection management
156+
157+
### Cache Strategy
158+
- **Redis Primary**: Use Redis for distributed caching
159+
- **Local Fallback**: Node-cache for local fallback
160+
- **TTL Strategy**: Appropriate TTL for different data types
161+
- **Cache Invalidation**: Proper cache invalidation patterns
162+
163+
### Event System
164+
- **EventEmitter2**: Use for internal events
165+
- **WebSocket**: Socket.io for real-time updates
166+
- **Queue Systems**: RabbitMQ/SQS for async processing
167+
- **Webhook Processing**: Proper webhook validation and processing

0 commit comments

Comments
 (0)