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)

• Database migration (070_locations_module.sql)
• Module configuration (module.json)
• 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