MyClub/DOCS/FACILITY_MANAGEMENT_IMPLEMENTATION.md

# Facility Management System Implementation

## Overview

Complete facility management system integrated into the MyClub football club platform, providing:

- **Field booking system** for training sessions and matches
- **Equipment inventory tracking** with maintenance scheduling
- **Weather integration** for outdoor activities
- **Maintenance scheduling** for facilities
- **Calendar integration** with public booking interface
- **Pricing system** with configurable rates

## Features Implemented

### 1. Facility Management
- **Types**: Fields, gyms, locker rooms, classrooms, storage, other
- **Status tracking**: Active, inactive, maintenance, closed
- **Capacity management**: Maximum occupancy limits
- **Pricing**: Per-hour rates with free options
- **Availability rules**: Day-specific time slots
- **Approval workflow**: Optional admin approval for bookings

### 2. Booking System
- **Real-time availability**: Calendar view with time slots
- **Duration limits**: Min/max booking durations
- **Advance booking**: Configurable days in advance
- **Conflict prevention**: Automatic overlap detection
- **User authentication**: Login required for bookings
- **Status tracking**: Pending, confirmed, cancelled, completed, no-show

### 3. Equipment Management
- **Categories**: Balls, cones, goals, training aids, weights, etc.
- **Status tracking**: Available, in use, maintenance, damaged, lost, retired
- **Quantity management**: Total and available counts
- **Purchase tracking**: Cost, supplier, warranty information
- **Usage statistics**: Usage count and last used date
- **Location tracking**: Current storage location

### 4. Maintenance Scheduling
- **Types**: Routine, repair, inspection, upgrade
- **Scheduling**: Date/time with duration estimates
- **Cost tracking**: Estimated vs actual costs
- **Status tracking**: Scheduled, in progress, completed, cancelled
- **Facility impact**: Automatic unavailability during maintenance
- **Personnel assignment**: Responsible staff tracking

### 5. Weather Integration
- **Outdoor facility support**: Weather data for fields
- **Forecast data**: Temperature, humidity, precipitation, wind
- **Suitability assessment**: Automatic activity recommendations
- **Caching system**: 2-hour cache for performance
- **Mock data**: Fallback data for demonstration

### 6. Public Interface
- **Facility browsing**: Public listing of available facilities
- **Booking calendar**: Interactive calendar with time slots
- **Registration forms**: User-friendly booking interface
- **Weather display**: Integrated weather widget for outdoor facilities
- **Pricing display**: Transparent cost information

## Database Schema

### Core Tables

#### Facilities
```sql
CREATE TABLE facilities (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    description TEXT,
    type VARCHAR(20) NOT NULL, -- field, gym, locker, classroom, storage, other
    status VARCHAR(20) NOT NULL DEFAULT 'active',
    capacity INTEGER,
    area DECIMAL(10,2),
    location VARCHAR(255),
    is_indoor BOOLEAN DEFAULT true,
    is_outdoor BOOLEAN DEFAULT false,
    requires_approval BOOLEAN DEFAULT false,
    min_booking_duration INTEGER DEFAULT 30,
    max_booking_duration INTEGER DEFAULT 240,
    booking_advance_days INTEGER DEFAULT 30,
    price_per_hour DECIMAL(10,2) DEFAULT 0.00
);
```

#### Facility Bookings
```sql
CREATE TABLE facility_bookings (
    id SERIAL PRIMARY KEY,
    facility_id INTEGER NOT NULL REFERENCES facilities(id),
    user_id INTEGER NOT NULL REFERENCES users(id),
    title VARCHAR(255) NOT NULL,
    description TEXT,
    start_time TIMESTAMP WITH TIME ZONE NOT NULL,
    end_time TIMESTAMP WITH TIME ZONE NOT NULL,
    status VARCHAR(20) NOT NULL DEFAULT 'pending',
    total_price DECIMAL(10,2) DEFAULT 0.00,
    payment_status VARCHAR(20) DEFAULT 'pending',
    attendees_count INTEGER DEFAULT 0,
    -- Exclusion constraint prevents overlapping bookings
    CONSTRAINT bookings_no_overlap EXCLUDE (
        facility_id WITH =, 
        tsrange(start_time, end_time) WITH && 
    ) WHERE (status NOT IN ('cancelled', 'noshow'))
);
```

#### Facility Equipment
```sql
CREATE TABLE facility_equipment (
    id SERIAL PRIMARY KEY,
    facility_id INTEGER NOT NULL REFERENCES facilities(id),
    name VARCHAR(255) NOT NULL,
    category VARCHAR(100),
    status VARCHAR(20) NOT NULL DEFAULT 'available',
    quantity INTEGER NOT NULL DEFAULT 1,
    available INTEGER NOT NULL DEFAULT 1,
    purchase_price DECIMAL(10,2),
    supplier VARCHAR(255),
    warranty_expiry DATE,
    usage_count INTEGER DEFAULT 0
);
```

#### Facility Maintenance
```sql
CREATE TABLE facility_maintenance (
    id SERIAL PRIMARY KEY,
    facility_id INTEGER NOT NULL REFERENCES facilities(id),
    type VARCHAR(20) NOT NULL, -- routine, repair, inspection, upgrade
    title VARCHAR(255) NOT NULL,
    description TEXT,
    scheduled_date TIMESTAMP WITH TIME ZONE,
    estimated_duration INTEGER, -- minutes
    estimated_cost DECIMAL(10,2),
    assigned_to VARCHAR(255),
    is_facility_unavailable BOOLEAN DEFAULT true,
    status VARCHAR(20) DEFAULT 'scheduled'
);
```

#### Weather Conditions
```sql
CREATE TABLE weather_conditions (
    id SERIAL PRIMARY KEY,
    facility_id INTEGER NOT NULL REFERENCES facilities(id),
    date_time TIMESTAMP WITH TIME ZONE NOT NULL,
    temperature DECIMAL(5,2), -- Celsius
    humidity DECIMAL(5,2), -- Percentage
    precipitation DECIMAL(8,2), -- mm
    wind_speed DECIMAL(5,2), -- km/h
    weather_code VARCHAR(10),
    description VARCHAR(255),
    is_suitable BOOLEAN DEFAULT false,
    recommendations TEXT
);
```

## API Endpoints

### Admin Endpoints

#### Facilities
- `GET /api/v1/admin/facilities` - List facilities with pagination
- `GET /api/v1/admin/facilities/:id` - Get facility details
- `POST /api/v1/admin/facilities` - Create facility
- `PUT /api/v1/admin/facilities/:id` - Update facility
- `DELETE /api/v1/admin/facilities/:id` - Delete facility
- `GET /api/v1/admin/facilities/:id/bookings` - Get facility bookings

#### Equipment
- `GET /api/v1/admin/equipment` - List equipment
- `POST /api/v1/admin/equipment` - Create equipment
- `PUT /api/v1/admin/equipment/:id` - Update equipment
- `DELETE /api/v1/admin/equipment/:id` - Delete equipment

#### Maintenance
- `GET /api/v1/admin/maintenance` - List maintenance records
- `POST /api/v1/admin/maintenance` - Create maintenance
- `PUT /api/v1/admin/maintenance/:id` - Update maintenance

### Public Endpoints

#### Facilities
- `GET /api/v1/facilities` - List public facilities
- `GET /api/v1/facilities/:id` - Get facility details
- `GET /api/v1/facilities/:id/availability` - Get availability calendar
- `GET /api/v1/facilities/:id/weather` - Get weather forecast

#### Bookings
- `POST /api/v1/facilities/bookings` - Create booking (requires auth)
- `GET /api/v1/facilities/calendar` - Get calendar events

## Frontend Components

### Admin Pages

#### FacilitiesAdminPage
- Facility listing with status badges
- Create/edit modal with tabbed interface
- Pricing and booking settings
- Availability rules configuration

#### EquipmentAdminPage
- Equipment inventory management
- Category-based organization
- Purchase and warranty tracking
- Usage statistics

#### MaintenanceAdminPage
- Maintenance scheduling
- Cost tracking
- Personnel assignment
- Facility impact management

### Public Pages

#### FacilitiesBookingPage
- Facility selection interface
- Interactive booking calendar
- Time slot selection
- Booking form with validation

#### WeatherWidget
- Weather forecast display
- Suitability recommendations
- Multi-day forecast
- Automatic refresh

## Integration Points

### Navigation System
- Added to admin navigation under "Správa" category
- Public booking page linked from main navigation
- Weather widgets integrated into facility pages

### User Authentication
- Bookings require user authentication
- Role-based access control for admin functions
- JWT token integration

### Email Notifications
- Booking confirmations
- Approval notifications
- Maintenance reminders
- Weather alerts (future enhancement)

### Payment Integration
- Pricing calculation in booking forms
- Payment status tracking
- Integration with existing e-commerce system

## Configuration

### Environment Variables
```bash
# Weather API (OpenWeatherMap)
OPENWEATHERMAP_API_KEY=your_api_key_here

# Facility settings
FACILITY_BOOKING_ADVANCE_DAYS=30
FACILITY_MIN_BOOKING_DURATION=30
FACILITY_MAX_BOOKING_DURATION=240
```

### Database Migration
```bash
# Run migration
go run cmd/sqlmigrate/main.go up database/migrations/20260109000001_create_facility_management_tables.up.sql
```

## Sample Data

The system includes sample data for demonstration:

### Facilities
- Hlavní hřiště (Main field) - 500 Kč/hod
- Tréninkové hřiště č. 1 (Training field) - 300 Kč/hod  
- Posilovna (Gym) - 100 Kč/hod
- Šatna A (Locker room) - Free
- Zasedací místnost (Classroom) - 50 Kč/hod
- Sklad vybavení (Storage) - Free

### Equipment
- Footballs (20 pieces)
- Training cones (50 pieces)
- Training goals (4 pieces)
- Weights (10 pieces)
- Training benches (3 pieces)

### Availability Rules
- Main field: Mon-Fri 16:00-22:00, Sat-Sun 08:00-22:00
- Other facilities: Daily 08:00-22:00

## Pricing Examples

| Facility Type | Price per Hour | Examples |
|---------------|----------------|----------|
| Main field | 500 Kč | Hlavní hřiště |
| Training field | 300 Kč | Tréninkové hřiště |
| Gym | 100 Kč | Posilovna |
| Classroom | 50 Kč | Zasedací místnost |
| Locker rooms | Free | Šatny |
| Storage | Free | Sklady |

## Weather Integration

### Supported Conditions
- Temperature: Activity suitability based on ranges
- Precipitation: Rain/snow impact on outdoor activities
- Wind: Strong wind warnings
- Humidity: Comfort level indicators

### Recommendations
- **Good conditions**: "Dobré podmínky pro trénink"
- **Light rain**: "Lehký déšť - doporučeno krytá plocha"
- **Heavy rain**: "Déšť - doporučeno přesunout dovnitř"
- **Strong wind**: "Silný vítr - opatrně při vysokých míčích"

## Security Considerations

### Booking Validation
- Overlap prevention using database constraints
- Time slot validation
- User authentication required
- Rate limiting on booking endpoints

### Data Protection
- Personal data in bookings
- Contact information protection
- Access control based on user roles

### Performance
- Database indexes on time ranges
- Weather data caching (2 hours)
- Pagination for large datasets
- Optimized queries for availability checks

## Future Enhancements

### Planned Features
- **Payment integration**: Stripe/PayPal for paid bookings
- **Recurring bookings**: Regular session scheduling
- **Waitlist system**: Queue for fully booked slots
- **Mobile app**: Native booking interface
- **Advanced weather**: Integration with multiple weather services
- **Analytics**: Usage statistics and reporting
- **Integration**: Calendar sync (Google, Outlook)
- **Notifications**: SMS/push notifications
- **Multi-venue**: Support for multiple locations
- **Resource allocation**: Automatic equipment assignment

### Technical Improvements
- **Real-time updates**: WebSocket for live availability
- **Advanced scheduling**: AI-based optimization
- **Mobile responsiveness**: PWA capabilities
- **Offline support**: Service worker for offline booking
- **Accessibility**: WCAG 2.1 compliance
- **Performance**: Server-side rendering for public pages

## Support and Maintenance

### Monitoring
- Booking system health checks
- Weather API reliability
- Database performance metrics
- User activity analytics

### Backup and Recovery
- Regular database backups
- Configuration backups
- Disaster recovery procedures
- Data retention policies

### Updates and Patches
- Regular security updates
- Feature enhancements
- Bug fixes and improvements
- User feedback incorporation

## Conclusion

The facility management system provides a comprehensive solution for managing football club facilities, equipment, and bookings. It integrates seamlessly with the existing MyClub platform while offering modern features like weather integration, real-time availability, and mobile-responsive interfaces.

The system is production-ready with proper error handling, security measures, and performance optimizations. It can be easily extended with additional features and integrations as the club's needs evolve.