Backend Complete: Interface Refactoring & Service Container Enhancements

Repository Interface Optimization: - Created IBaseRepository.ts and IPaginatedRepository.ts - Refactored all 7 repository interfaces to extend base interfaces - Eliminated ~200 lines of redundant code (70% reduction) - Improved type safety and maintainability Dependency Injection Improvements: - Added EmailService and GameTokenService to DIContainer - Updated CreateUserCommandHandler constructor for DI - Updated RequestPasswordResetCommandHandler constructor for DI - Enhanced testability and service consistency Environment Configuration: - Created comprehensive .env.example with 40+ variables - Organized into 12 logical sections (Database, Security, Email, etc.) - Added security guidelines and best practices - Documented all backend environment requirements Documentation: - Added comprehensive codebase review - Created refactoring summary report - Added frontend implementation guide Impact: Improved code quality, reduced maintenance overhead, enhanced developer experience
2025-09-21 03:27:57 +02:00
parent 5b7c3ba4b2
commit 86211923db
306 changed files with 52956 additions and 0 deletions
@@ -0,0 +1,392 @@
+# 🗄️ SerpentRace Database Management Guide
+
+## 🎯 Overview
+
+This guide provides comprehensive information about managing all database services in the SerpentRace project, including PostgreSQL, Redis, MinIO, and administration tools.
+
+## 📊 Quick Status Check
+
+### Check All Services
+```bash
+npm run db:status
+```
+
+### Check Individual Services
+```bash
+npm run db:status:pg      # PostgreSQL only
+npm run db:status:redis   # Redis only
+npm run db:status:docker  # Docker containers only
+```
+
+### Simple Connection Test
+```bash
+npm run test:connections
+```
+
+## 🐘 PostgreSQL Database
+
+### Connection Details
+- **Host**: localhost:5432
+- **Database**: serpentrace
+- **Username**: postgres
+- **Password**: postgres
+- **Admin Tool**: pgAdmin at http://localhost:8080
+
+### Database Operations
+
+#### Run Migrations
+```bash
+npm run migration:run
+```
+
+#### Create New Migration
+```bash
+npm run migration:create src/migrations/YourMigrationName
+```
+
+#### Generate Migration from Entity Changes
+```bash
+npm run migration:generate src/migrations/YourMigrationName
+```
+
+#### Check Migration Status
+```bash
+npm run migration:show
+```
+
+#### Rollback Last Migration
+```bash
+npm run migration:revert
+```
+
+### Direct Database Access
+
+#### Using psql (if installed)
+```bash
+psql -h localhost -p 5432 -U postgres -d serpentrace
+```
+
+#### Using pgAdmin
+1. Open http://localhost:8080
+2. Login with: admin@serpentrace.dev / admin
+3. Server should be pre-configured as "SerpentRace"
+
+### Common SQL Queries
+
+#### Check Database Size
+```sql
+SELECT pg_size_pretty(pg_database_size('serpentrace')) as size;
+```
+
+#### List All Tables
+```sql
+SELECT tablename FROM pg_tables WHERE schemaname = 'public';
+```
+
+#### Check Active Connections
+```sql
+SELECT count(*) FROM pg_stat_activity WHERE datname = 'serpentrace';
+```
+
+## 🔴 Redis Cache
+
+### Connection Details
+- **Host**: localhost:6379
+- **No Authentication**: Default Redis setup
+- **Admin Tool**: Redis Commander at http://localhost:8081
+
+### Redis Operations
+
+#### Direct Redis Access (if redis-cli installed)
+```bash
+redis-cli -h localhost -p 6379
+```
+
+#### Common Redis Commands
+```bash
+# Get all keys
+KEYS *
+
+# Get key count
+DBSIZE
+
+# Check memory usage
+INFO memory
+
+# Flush all data (careful!)
+FLUSHALL
+```
+
+### Using Redis Commander
+1. Open http://localhost:8081
+2. Browse keys, view data, execute commands
+
+## 🗄️ MinIO Object Storage
+
+### Connection Details
+- **Endpoint**: localhost:9000
+- **Console**: http://localhost:9001
+- **Access Key**: serpentrace
+- **Secret Key**: serpentrace123
+- **Default Bucket**: serpentrace
+
+### MinIO Operations
+
+#### Access MinIO Console
+1. Open http://localhost:9001
+2. Login with: serpentrace / serpentrace123
+3. Create buckets, upload files, manage storage
+
+#### Health Check
+```bash
+curl http://localhost:9000/minio/health/live
+```
+
+### File Upload Example (Node.js)
+```javascript
+const Minio = require('minio');
+
+const minioClient = new Minio.Client({
+    endPoint: 'localhost',
+    port: 9000,
+    useSSL: false,
+    accessKey: 'serpentrace',
+    secretKey: 'serpentrace123'
+});
+
+// Upload file
+minioClient.fPutObject('serpentrace', 'test-file.txt', './file.txt');
+```
+
+## 🐳 Docker Container Management
+
+### View All Containers
+```bash
+docker ps -a
+```
+
+### View SerpentRace Containers Only
+```bash
+docker ps -a --filter "name=serpentrace"
+```
+
+### Container Operations
+
+#### Restart All Services
+```bash
+cd d:\munka\SzeSnake\SerpentRace_Docker
+docker-compose -f docker-compose.dev.yml restart
+```
+
+#### Restart Individual Service
+```bash
+docker restart serpentrace-postgres-dev    # PostgreSQL
+docker restart serpentrace-redis-dev       # Redis
+docker restart serpentrace-minio-dev       # MinIO
+docker restart serpentrace-pgadmin-dev     # pgAdmin
+```
+
+#### View Container Logs
+```bash
+docker logs serpentrace-postgres-dev
+docker logs serpentrace-redis-dev -f     # Follow logs
+```
+
+#### Stop All Services
+```bash
+cd d:\munka\SzeSnake\SerpentRace_Docker
+docker-compose -f docker-compose.dev.yml down
+```
+
+#### Start All Services
+```bash
+cd d:\munka\SzeSnake\SerpentRace_Docker
+docker-compose -f docker-compose.dev.yml up -d
+```
+
+## 🛠️ Troubleshooting
+
+### PostgreSQL Issues
+
+#### Connection Refused
+```bash
+# Check if container is running
+docker ps | grep postgres
+
+# Check container logs
+docker logs serpentrace-postgres-dev
+
+# Restart if needed
+docker restart serpentrace-postgres-dev
+```
+
+#### Migration Errors
+```bash
+# Check migration status
+npm run migration:show
+
+# Revert last migration if problematic
+npm run migration:revert
+
+# Re-run migrations
+npm run migration:run
+```
+
+### Redis Issues
+
+#### Cannot Connect
+```bash
+# Check Redis container
+docker ps | grep redis
+
+# Test connection
+redis-cli -h localhost -p 6379 ping
+# Expected response: PONG
+```
+
+### MinIO Issues
+
+#### Health Check Failed
+```bash
+# Check MinIO container
+docker ps | grep minio
+
+# Test health endpoint
+curl http://localhost:9000/minio/health/live
+# Expected response: 200 OK
+```
+
+### pgAdmin Issues
+
+#### Cannot Login
+- Default credentials: admin@serpentrace.dev / admin
+- If issues persist, restart container:
+  ```bash
+  docker restart serpentrace-pgladmin-dev
+  ```
+
+#### Server Not Found
+- pgAdmin should auto-configure the PostgreSQL server
+- If not visible, add manually:
+  - Host: postgres
+  - Port: 5432
+  - Database: serpentrace
+  - Username: postgres
+  - Password: postgres
+
+## 🔧 Environment Variables
+
+### Default Development Settings
+```bash
+# PostgreSQL
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=serpentrace
+DB_USERNAME=postgres
+DB_PASSWORD=postgres
+
+# Redis
+REDIS_HOST=localhost
+REDIS_PORT=6379
+
+# MinIO
+MINIO_ENDPOINT=localhost
+MINIO_PORT=9000
+MINIO_ACCESS_KEY=serpentrace
+MINIO_SECRET_KEY=serpentrace123
+```
+
+### Production Configuration
+Create `.env.production` with secure values:
+```bash
+DB_HOST=your-production-host
+DB_PASSWORD=secure-password
+REDIS_PASSWORD=secure-redis-password
+MINIO_SECRET_KEY=secure-minio-secret
+```
+
+## 📈 Monitoring & Maintenance
+
+### Daily Health Check
+```bash
+npm run db:status
+```
+
+### Weekly Maintenance
+```bash
+# Check database size growth
+npm run db:status:pg
+
+# Review Redis memory usage
+npm run db:status:redis
+
+# Clean up old Docker logs
+docker system prune
+```
+
+### Backup Procedures
+
+#### PostgreSQL Backup
+```bash
+docker exec serpentrace-postgres-dev pg_dump -U postgres serpentrace > backup.sql
+```
+
+#### Redis Backup
+```bash
+docker exec serpentrace-redis-dev redis-cli BGSAVE
+```
+
+#### MinIO Backup
+Use MinIO Console or mc client to backup buckets.
+
+## 🎯 Performance Optimization
+
+### PostgreSQL
+- Monitor active connections with `npm run db:status:pg`
+- Use connection pooling in production
+- Regular VACUUM and ANALYZE operations
+
+### Redis
+- Monitor memory usage
+- Configure appropriate eviction policies
+- Use Redis persistence (RDB/AOF) in production
+
+### MinIO
+- Configure appropriate bucket policies
+- Use lifecycle management for old files
+- Monitor storage usage through console
+
+## 🚀 Quick Reference Commands
+
+```bash
+# Status and Health
+npm run db:status              # Full system status
+npm run test:connections       # Quick connection test
+
+# Database Operations  
+npm run migration:run          # Apply migrations
+npm run migration:show         # Check migration status
+
+# Docker Management
+docker ps                      # Show running containers
+docker logs <container>        # View logs
+docker restart <container>     # Restart service
+
+# Direct Access
+psql -h localhost -U postgres -d serpentrace    # PostgreSQL CLI
+redis-cli -h localhost                          # Redis CLI
+```
+
+## 🌐 Web Interfaces Summary
+
+| Service | URL | Credentials |
+|---------|-----|------------|
+| pgAdmin | http://localhost:8080 | admin@serpentrace.dev / admin |
+| Redis Commander | http://localhost:8081 | No auth required |
+| MinIO Console | http://localhost:9001 | serpentrace / serpentrace123 |
+| Backend API | http://localhost:3000 | When running |
+| Frontend | http://localhost:5173 | When running |
+
+---
+
+*This guide is automatically updated when database configurations change. Last updated: 2025-08-23*