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
This commit is contained in:
Roo
267
readme.md
Normal file
267
readme.md
Normal file
@@ -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*
|
||||||
Reference in New Issue
Block a user