MyClub/DOCS/CONTACT_MANAGEMENT_IMPLEMENTATION.md

# Contact Management & Map Integration - Implementation Summary

## Overview
Complete contact management system with admin interface, map integration on homepage, and setup wizard location configuration.

## What Was Implemented

### 1. Backend API Service (Already Existed ✅)
- **File**: `internal/controllers/contact_info_controller.go`
- **File**: `internal/routes/contact_info_routes.go`
- **Models**: `ContactCategory` and `Contact` in `internal/models/models.go`
- **Migration**: `database/migrations/000006_create_contact_tables.up.sql`

**Endpoints**:
- **Public**:
  - `GET /api/v1/contacts` - Get all active contacts grouped by category
  - `GET /api/v1/contacts/categories` - Get all active categories

- **Admin** (require authentication + admin role):
  - `GET /admin/contacts/categories` - List all categories
  - `POST /admin/contacts/categories` - Create category
  - `PUT /admin/contacts/categories/:id` - Update category
  - `DELETE /admin/contacts/categories/:id` - Delete category
  - `GET /admin/contacts` - List all contacts
  - `POST /admin/contacts` - Create contact
  - `PUT /admin/contacts/:id` - Update contact
  - `DELETE /admin/contacts/:id` - Delete contact

### 2. Frontend Service Layer (NEW ✅)
- **File**: `frontend/src/services/contactInfo.ts`
- TypeScript interfaces for `Contact`, `ContactCategory`, and `GroupedContacts`
- Functions to interact with all contact API endpoints

### 3. Admin Contact Management Page (NEW ✅)
- **File**: `frontend/src/pages/admin/ContactsAdminPage.tsx`
- Full CRUD interface for contacts and categories
- Tab-based UI with separate views for contacts and categories
- Modal dialogs for create/edit operations
- Image upload support for contact photos
- Display order management
- Active/inactive status toggle
- Category assignment for contacts
- Delete confirmation dialogs with validation

### 4. Map Component (NEW ✅)
- **File**: `frontend/src/components/home/ContactMap.tsx`
- Uses **Leaflet.js** (open source mapping library)
- Dynamically loads Leaflet CSS and JavaScript
- Supports multiple map styles:
  - **default**: OpenStreetMap
  - **dark**: CartoDB Dark Matter
  - **satellite**: Esri World Imagery
  - **custom**: Custom tile URL
- Features:
  - Custom markers with popups
  - Scroll wheel zoom (enabled on click)
  - Responsive design
  - Error handling

### 5. Homepage Contacts Section (NEW ✅)
- **File**: `frontend/src/components/home/ContactsSection.tsx`
- Displays contact information with optional map
- Groups contacts by category using accordion UI
- Shows address, phone, and email with icons
- Responsive grid layout for contact cards
- Only renders if data exists
- Integrates map based on settings configuration

### 6. Setup Wizard Enhancement (NEW ✅)
- **File**: `frontend/src/pages/SetupPage.tsx`
- Added location configuration section:
  - Address fields (street, city, ZIP, country)
  - GPS coordinates (latitude, longitude)
  - Helpful placeholder text with examples
- Backend support in `internal/controllers/base_controller.go`:
  - Added location fields to `SetupInitialize` handler
  - Saves location data to settings during initial setup

### 7. Routing & Navigation (NEW ✅)
- **Route**: Added `/admin/kontakty` route in `frontend/src/App.tsx`
- **Navigation**: Added "Kontakty" menu item in admin sidebar
- **Icon**: Uses `FaAddressBook` icon from react-icons
- Positioned in sidebar under "Zprávy" (Messages) section

### 8. Settings Model Extension (Already Existed ✅)
Settings table includes location/map fields:
- `contact_address`, `contact_city`, `contact_zip`, `contact_country`
- `contact_phone`, `contact_email`
- `location_latitude`, `location_longitude` (DECIMAL)
- `map_zoom_level` (INT, default: 15)
- `map_style` (VARCHAR)
- `show_map_on_homepage` (BOOLEAN)

## Database Schema

### contact_categories
```sql
CREATE TABLE contact_categories (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL UNIQUE,
    description TEXT,
    display_order INT DEFAULT 0,
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    deleted_at TIMESTAMP
);
```

### contacts
```sql
CREATE TABLE contacts (
    id SERIAL PRIMARY KEY,
    category_id INT REFERENCES contact_categories(id) ON DELETE SET NULL,
    name VARCHAR(255) NOT NULL,
    position VARCHAR(255),
    email VARCHAR(255),
    phone VARCHAR(100),
    image_url VARCHAR(500),
    description TEXT,
    display_order INT DEFAULT 0,
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    deleted_at TIMESTAMP
);
```

## Usage Guide

### Initial Setup
1. During setup wizard, fill in the "Lokalita a kontakt" section:
   - Enter club address (optional)
   - Enter GPS coordinates for map (optional)
   - All fields can be edited later in admin

### Admin Management
1. Navigate to **Admin Panel → Kontakty**
2. **Categories Tab**:
   - Create categories (e.g., "Management", "Coaches", "Office")
   - Set display order and active status
   - Edit or delete categories

3. **Contacts Tab**:
   - Add contact persons
   - Upload photos
   - Assign to categories
   - Set position, email, phone
   - Add optional description
   - Manage display order

### Homepage Display
The contacts section appears automatically on the homepage when:
- Contact information exists (address, phone, email), OR
- Contacts have been added, OR
- Map location is configured and `show_map_on_homepage` is enabled

### Map Configuration
In admin settings (`/admin/nastaveni`), you can configure:
- **Location**: Latitude, Longitude, Zoom Level
- **Map Style**: default, dark, satellite, or custom tile URL
- **Display**: Toggle `show_map_on_homepage`
- **Contact Info**: Address, city, ZIP, country, phone, email

## Features

### Contact Management
- ✅ Category-based organization
- ✅ Photo uploads for each contact
- ✅ Position/role labels
- ✅ Email and phone with clickable links
- ✅ Optional descriptions
- ✅ Display order customization
- ✅ Active/inactive status

### Map Integration
- ✅ Open source (Leaflet.js + OpenStreetMap)
- ✅ No API keys required for basic functionality
- ✅ Multiple map style options
- ✅ Custom markers with popups
- ✅ Responsive and mobile-friendly
- ✅ Configurable zoom level

### Admin UX
- ✅ Intuitive tab-based interface
- ✅ Modal dialogs for forms
- ✅ Inline image preview
- ✅ Delete confirmations
- ✅ Validation and error handling
- ✅ Loading states

## Files Created/Modified

### Created Files
1. `frontend/src/services/contactInfo.ts` - API service
2. `frontend/src/pages/admin/ContactsAdminPage.tsx` - Admin UI
3. `frontend/src/components/home/ContactMap.tsx` - Map component
4. `frontend/src/components/home/ContactsSection.tsx` - Homepage section
5. `CONTACT_MANAGEMENT_IMPLEMENTATION.md` - This document

### Modified Files
1. `frontend/src/App.tsx` - Added route and import
2. `frontend/src/pages/HomePage.tsx` - Added ContactsSection
3. `frontend/src/pages/SetupPage.tsx` - Added location fields
4. `frontend/src/services/setup.ts` - Added location types
5. `frontend/src/services/api.ts` - Added uploadImage function
6. `frontend/src/components/admin/AdminSidebar.tsx` - Added navigation
7. `internal/controllers/base_controller.go` - Added location handling

## Testing Checklist

- [ ] Run migrations to create contact tables
- [ ] Access `/admin/kontakty` - verify page loads
- [ ] Create contact categories
- [ ] Add contacts with photos
- [ ] Verify contacts appear on homepage
- [ ] Configure map location in setup or settings
- [ ] Verify map displays correctly
- [ ] Test different map styles
- [ ] Test on mobile devices
- [ ] Verify email/phone links work
- [ ] Test category assignment and filtering

## Next Steps (Optional Enhancements)

From the original `CONTACT_MANAGEMENT.md`:
- [ ] Contact form directly on contact page
- [ ] vCard download for contacts
- [ ] Office hours/availability scheduling
- [ ] Multiple locations/maps support
- [ ] Department-specific contact forms
- [ ] Social media links per contact
- [ ] Search/filter functionality
- [ ] Map clustering for multiple locations

## Security Notes

- Admin endpoints protected by JWT + admin role middleware
- Public endpoints only expose active contacts
- Image uploads validated for file type
- SQL injection protected via ORM (GORM)
- XSS protection via React's automatic escaping

## Dependencies

**Frontend**:
- Leaflet.js 1.9.4 (loaded dynamically, no npm install needed)
- @chakra-ui/react (already in project)
- react-icons/fa (already in project)

**Backend**:
- No new dependencies (uses existing GORM, Gin)

## Support

Map uses OpenStreetMap tiles (free, no API key required). For production:
- Consider using a CDN for Leaflet assets
- Monitor tile server usage (OSM has usage policies)
- Can switch to alternative tile providers if needed
- Custom tile servers can be configured via `map_style` setting

---

**Implementation Date**: 2025-10-05
**Status**: ✅ Complete and Ready for Testing