Fixes #2: readme.md fájl létrehozása a projekt főkönyvtárában

- Átfogó README dokumentáció készítése - Projekt áttekintés, architektúra leírás - Telepítési és használati útmutató - Robot rendszer dokumentálása - API dokumentáció vázlat
2026-03-06 19:10:23 +00:00
parent 6c359040e2
commit cead60f4e2
1 changed files with 267 additions and 0 deletions
--- a/readme.md
+++ b/readme.md
@@ -0,0 +1,267 @@
+# Service Finder Platform
+
+## 📋 Overview
+Service Finder is a comprehensive vehicle service and fleet management platform that connects vehicle owners with service providers across Europe. The system combines real-time service discovery, historical data analytics, and automated workflow management.
+
+## 🚀 Features
+
+### Core Capabilities
+- **Vehicle Master Data Management** - Centralized catalog with European vehicle specifications
+- **Service Discovery Engine** - Automated search for service providers across multiple countries
+- **Fleet Management** - Complete TCO (Total Cost of Ownership) tracking and analytics
+- **Historical Data Integration** - Past service records and expense tracking with occurrence dates
+- **Multi-language Support** - Hungarian and English interfaces
+
+### Technical Features
+- **Hybrid AI Gateway** - Local Ollama (14B Qwen) for text processing with Gemini/Groq fallback
+- **Dual Entity Model** - Separate Person (human) and User (technical account) entities
+- **Triple Wallet Economy** - Integrated financial system for transactions
+- **MDM Deduplication** - Smart merging based on make, technical_code, and cylinder capacity
+- **Real-time OCR Processing** - Automated document analysis for service receipts
+
+## 🏗️ Architecture
+
+### Tech Stack
+- **Backend**: FastAPI v2 (async), SQLAlchemy (Async), PostgreSQL with PostGIS
+- **Frontend**: Vue.js 3 with Vite, Tailwind CSS
+- **Database**: PostgreSQL 15+ with spatial extensions
+- **Message Queue**: Redis for background job processing
+- **Containerization**: Docker Compose V2
+- **Reverse Proxy**: Nginx Proxy Manager
+
+### Database Schema
+The system uses a sophisticated schema with:
+- **Identity & Auth**: Dual entity model with JWT-based authentication
+- **Vehicle Catalog**: European vehicle definitions with RDW/DVLA integration
+- **Service Marketplace**: Provider listings with geospatial search
+- **Fleet Operations**: Asset tracking, maintenance scheduling, cost analysis
+- **Gamification**: User engagement system with badges and rewards
+
+## 🤖 Robot Ecosystem
+
+### Discovery Robots
+- **Robot-0-GB**: GB Discovery Engine - Processes UK MOT CSV data
+- **Robot-1-GB**: GB Hunter - Queries DVLA VES API for technical specifications
+- **Service Robots**: Automated service provider discovery and validation
+
+### Processing Robots
+- **OCR Processor**: Extracts data from service receipts and documents
+- **Service Auditor**: Validates service provider information
+- **Research Bots**: Enrich vehicle and service data from external sources
+
+## 📊 Data Sources
+
+### Vehicle Data
+- **RDW API** (Netherlands) - Official Dutch vehicle registry
+- **DVLA VES API** (UK) - British vehicle technical specifications
+- **OpenStreetMap** - Service provider locations and details
+- **Google Places API** - Business information and reviews
+
+### Service Data
+- **Historical Service Records** - Imported from user uploads
+- **Provider Directories** - Aggregated from multiple European sources
+- **Real-time Availability** - Dynamic scheduling integration
+
+## 🔧 Installation & Setup
+
+### Prerequisites
+- Docker and Docker Compose
+- PostgreSQL 15+
+- Python 3.11+
+- Redis 7+
+
+### Quick Start
+```bash
+# Clone the repository
+git clone <repository-url>
+cd service_finder
+
+# Copy environment configuration
+cp .env.example .env
+# Edit .env with your settings
+
+# Start the services
+docker-compose up -d
+
+# Run database migrations
+docker-compose exec api alembic upgrade head
+
+# Seed initial data
+docker-compose exec api python -m app.scripts.seed_v1_9_system
+```
+
+### Development Setup
+```bash
+# Backend development
+cd backend
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+
+# Run tests
+pytest app/tests_internal/
+
+# Start development server
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+## 📁 Project Structure
+
+```
+service_finder/
+├── backend/                 # FastAPI application
+│   ├── app/
+│   │   ├── api/            # API endpoints
+│   │   ├── models/         # SQLAlchemy models
+│   │   ├── schemas/        # Pydantic schemas
+│   │   ├── services/       # Business logic
+│   │   ├── workers/        # Background robots
+│   │   └── tests_internal/ # Test suite
+│   ├── migrations/         # Alembic migrations
+│   └── requirements.txt
+├── frontend/               # Vue.js application
+│   ├── src/
+│   │   ├── components/     # Vue components
+│   │   ├── views/         # Page views
+│   │   └── router/        # Vue Router
+│   └── package.json
+├── docker-compose.yml      # Service definitions
+└── readme.md              # This file
+```
+
+## 🔐 Authentication & Authorization
+
+### User Roles
+- **Super Admin**: Full system access
+- **Organization Admin**: Manages fleet and users within organization
+- **Fleet Manager**: Views and manages vehicle assets
+- **Service Provider**: Manages service listings and appointments
+- **Vehicle Owner**: Basic user with personal vehicle management
+
+### Security Features
+- JWT token-based authentication
+- Role-based access control (RBAC)
+- API rate limiting
+- Input validation and sanitization
+- SQL injection prevention
+- CORS configuration
+
+## 📈 API Documentation
+
+### Available Endpoints
+- **/api/v1/auth/** - Authentication and user management
+- **/api/v1/vehicles/** - Vehicle catalog and operations
+- **/api/v1/services/** - Service discovery and booking
+- **/api/v1/fleet/** - Fleet management endpoints
+- **/api/v1/admin/** - Administrative functions
+- **/api/v1/analytics/** - Data analysis and reporting
+
+### API Versioning
+The API uses URL versioning (`/api/v1/`) with semantic versioning for breaking changes.
+
+## 🧪 Testing
+
+### Test Types
+- **Unit Tests**: Individual component testing
+- **Integration Tests**: API endpoint testing
+- **Database Tests**: Data persistence validation
+- **Robot Tests**: Background job verification
+
+### Running Tests
+```bash
+# Run all tests
+docker-compose exec api pytest
+
+# Run specific test category
+docker-compose exec api pytest app/tests_internal/ -v
+
+# Generate coverage report
+docker-compose exec api pytest --cov=app --cov-report=html
+```
+
+## 📊 Monitoring & Logging
+
+### Logging Strategy
+- Structured JSON logging for all services
+- Centralized log aggregation
+- Error tracking and alerting
+- Performance metrics collection
+
+### Health Checks
+- **/health**: Basic service health
+- **/health/db**: Database connectivity
+- **/health/redis**: Redis connection status
+- **/health/workers**: Background worker status
+
+## 🔄 Deployment
+
+### Production Considerations
+- Use environment-specific configuration
+- Enable HTTPS with valid certificates
+- Configure proper backup strategies
+- Set up monitoring and alerting
+- Implement CI/CD pipeline
+
+### Scaling
+- Horizontal scaling of API instances
+- Database connection pooling
+- Redis clustering for session management
+- CDN for static assets
+
+## 🤝 Contributing
+
+### Development Workflow
+1. Check the Kanban board for active tasks
+2. Create a feature branch from `main`
+3. Implement changes with tests
+4. Submit pull request for review
+5. Move Kanban card to "Done" after merge
+
+### Code Standards
+- Follow PEP 8 for Python code
+- Use TypeScript for frontend components
+- Write comprehensive docstrings
+- Include unit tests for new features
+- Update documentation as needed
+
+## 📚 Documentation
+
+### Additional Resources
+- [Architecture Documentation](./docs/V02/02_Architecture.md)
+- [API Specifications](./docs/V02/07_API_Service.md)
+- [Database Schema](./docs/V02/06_Database_MDM.md)
+- [Robot Ecosystem](./docs/V02/22_Robot_Ecosystem.md)
+
+### Wiki
+Comprehensive documentation is maintained in the project Wiki with:
+- Technical specifications
+- User guides
+- API references
+- Deployment guides
+
+## 📞 Support
+
+### Issue Reporting
+- Use the issue tracker for bugs and feature requests
+- Include detailed reproduction steps
+- Provide relevant logs and screenshots
+
+### Community
+- Join the development discussions
+- Share feedback and suggestions
+- Contribute to documentation
+
+## 📄 License
+
+This project is proprietary software. All rights reserved.
+
+## 🏆 Acknowledgments
+
+- European vehicle data providers (RDW, DVLA)
+- OpenStreetMap community
+- FastAPI and Vue.js communities
+- All contributors and testers
+
+---
+
+*Last Updated: March 2026*