Building Management API with Property Hierarchy

[ysnarafat]

Description

Implement building management system that sits between properties and units in the hierarchy. Buildings belong to properties and contain multiple units, supporting both single-building and multi-building property scenarios.

Acceptance Criteria

Database Schema

• Create Building entity with fields: building_name, building_code, property_id, building_type (Residential/Commercial/Mixed), total_floors, has_elevator, construction_year, active_status
• Add JSONB metadata field for building-specific attributes (parking_spaces, amenities, security_system, etc.)
• Create foreign key relationship to Property with cascade rules
• Add composite indexes on (property_id, building_code) for uniqueness
• Add GIN index on metadata JSONB field for attribute queries

API Endpoints

• POST /api/buildings - Create building with property association
• GET /api/buildings - List buildings with property filtering
• GET /api/buildings/{id} - Get building with unit counts and property info
• PUT /api/buildings/{id} - Update building information and metadata
• DELETE /api/buildings/{id} - Soft delete building
• GET /api/properties/{propertyId}/buildings - Get all buildings for a property
• POST /api/properties/{propertyId}/buildings/bulk - Bulk create buildings

Business Logic

• Building code uniqueness within property validation
• Building type validation and metadata schema validation
• Property-building relationship validation
• Building-level aggregation (total units, occupancy rate, revenue)
• Prevent building deletion if has active units

Metadata Support

• Commercial building attributes: parking_spaces, loading_docks, security_system, business_hours
• Residential building attributes: amenities, security_type, maintenance_staff_count
• Mixed building attributes: combination of commercial and residential
• Validation for type-specific metadata fields

Testing

• Unit tests for CRUD operations and metadata handling
• Integration tests for building-property relationships
• Validation tests for building types and metadata
• Bulk creation tests for multi-building properties

Documentation

• API documentation with metadata examples
• Building type and metadata schema documentation
• Hierarchy relationship documentation

Technical Notes

• JSONB field for flexible building-specific attributes
• Proper foreign key constraints with property table
• Support for bulk operations for efficiency
• Metadata validation based on building_type

Dependencies

• Property Management API (Issue Initialize project structure and development environment #1)
• Database infrastructure
• Authentication system

Labels

backend, api, database, building-management, hierarchy