bmc_hub/app/modules/locations/README.md

# Locations (Lokaliteter) Module

## Overview

The Locations Module provides central management of physical locations within BMC Hub. It tracks:

- **Physical Locations**: Kompleks, bygninger, etager, kundesites og rum
- **Address Management**: Standardized address storage with coordinates
- **Contact Persons**: Key contacts per location (managers, technicians, etc.)
- **Operating Hours**: Availability and service hours by day of week
- **Services**: Services offered at each location
- **Capacity Tracking**: Storage capacity, rack units, square meters, etc.
- **Audit Trail**: Complete history of all changes

## Status

🚧 **Under Construction** - Phase 1 Skeleton (Database + Config)

## Architecture

### Core Entities
- **Location**: Physical address with metadata (type, coordinates, contact info)
- **Contact**: Person associated with location (role, contact details)
- **Operating Hours**: When location is open (by day of week)
- **Service**: Services offered at location
- **Capacity**: Resource tracking (rack units, storage space, etc.)

### Key Features
✅ Soft deletes (all deletions set deleted_at timestamp)  
✅ Audit trail (all changes logged with before/after values)  
✅ Type validation (location_type must be one of: kompleks, bygning, etage, customer_site, rum, vehicle)  
✅ Address standardization (street, city, postal code, country)  
✅ Geocoding support (latitude/longitude)  
✅ Primary contact management  
✅ Operating hours by day of week  
✅ Capacity utilization tracking  

## Database Schema

| Table | Purpose | Rows |
|-------|---------|------|
| `locations_locations` | Main location data | Main |
| `locations_contacts` | Contact persons per location | 1:N |
| `locations_hours` | Operating hours by day of week | 1:N |
| `locations_services` | Services offered | 1:N |
| `locations_capacity` | Capacity tracking | 1:N |
| `locations_audit_log` | Audit trail | All changes |

## API Endpoints (Planned)

### Location CRUD
- `GET /api/v1/locations` - List all locations
- `POST /api/v1/locations` - Create location
- `GET /api/v1/locations/{id}` - Get location details
- `PATCH /api/v1/locations/{id}` - Update location
- `DELETE /api/v1/locations/{id}` - Soft-delete location
- `POST /api/v1/locations/{id}/restore` - Restore deleted location

### Contacts
- `GET /api/v1/locations/{id}/contacts` - List contacts
- `POST /api/v1/locations/{id}/contacts` - Add contact
- `PATCH /api/v1/locations/{id}/contacts/{cid}` - Update contact
- `DELETE /api/v1/locations/{id}/contacts/{cid}` - Delete contact

### Other Relationships
- `GET /api/v1/locations/{id}/hours` - Operating hours
- `GET /api/v1/locations/{id}/services` - Services offered
- `GET /api/v1/locations/{id}/capacity` - Capacity info

## Frontend Views

- **List View** (`/app/locations`) - All locations with filtering and pagination
- **Detail View** (`/app/locations/{id}`) - Full location profile with all relationships
- **Create Form** (`/app/locations/create`) - Create new location
- **Edit Form** (`/app/locations/{id}/edit`) - Modify location
- **Map View** (`/app/locations/map`) - Interactive map of all locations

## Development Phase

### ✅ Phase 1: Database & Skeleton (CURRENT)
- [x] Database migration (070_locations_module.sql)
- [x] Module configuration (module.json)
- [x] Directory structure

### 🔄 Phase 2: Backend API
- [ ] Pydantic models (schemas.py)
- [ ] Core CRUD endpoints
- [ ] Contacts endpoints
- [ ] Operating hours endpoints
- [ ] Services & capacity endpoints
- [ ] Bulk operations

### 🔄 Phase 3: Frontend
- [ ] View handlers (views.py)
- [ ] List template
- [ ] Detail template
- [ ] Forms (create/edit)
- [ ] Modals & inline editors

### 🔄 Phase 4: Integration
- [ ] Module registration (main.py)
- [ ] Navigation update
- [ ] QA testing & documentation

### 🔄 Phase 5: Optional Enhancements
- [ ] Map integration
- [ ] Analytics & reporting
- [ ] Import/export (CSV, PDF)

## Configuration

Location type options (enforced by database CHECK constraint):
- `kompleks` - Kompleks
- `bygning` - Bygning
- `etage` - Etage
- `customer_site` - Kundesite
- `rum` - Rum
- `vehicle` - Køretøj

## Integration

### Related Modules
- **Hardware Module**: Locations are linked to hardware assets
- **Cases Module**: Cases can be associated with locations (site visits, incidents, etc.)
- **Contacts Module**: Contacts linked to locations

## Known Limitations

- Phase 1: Only database schema and configuration present
- Map view requires geocoordinates (lat/long) to be populated
- Operating hours based on local timezone (not timezone-aware initially)

## Deployment

1. Apply database migration: `psql -d bmc_hub -f migrations/070_locations_module.sql`
2. Verify module loads: Check `/api/v1/system/health` for locations module
3. Access frontend: Navigate to `/app/locations`

## Future Enhancements

- [ ] Geolocation-based searches (within X km)
- [ ] Location hierarchy (parent/child relationships)
- [ ] QR code generation for location identification
- [ ] Capacity utilization analytics
- [ ] Automatic operating hours from external sources (Google Maps API)
- [ ] Export locations to CSV/PDF
- [ ] Hardware movement history at each location