Tenant and Lease Management with Multi-Unit Support

[ysnarafat]

Description

Implement comprehensive tenant profile management and lease system supporting tenants who rent multiple units across different buildings and properties, with full historical tracking.

Acceptance Criteria

Database Schema

• Create Tenant entity: name, phone, email, nid_number, address, tenant_type (Individual/Business), active_status
• Create Lease entity: tenant_id, unit_id, start_date, duration_months, monthly_rent, security_deposit, lease_type (Residential/Commercial), active_status
• Add proper indexes for tenant and lease queries
• Add audit trail fields for change tracking

Tenant Management API

• POST /api/tenants - Create tenant profile with validation
• GET /api/tenants - List tenants with search and filtering
• GET /api/tenants/{id} - Get tenant with all lease history
• PUT /api/tenants/{id} - Update tenant information
• DELETE /api/tenants/{id} - Soft delete tenant
• GET /api/tenants/search - Advanced search by name, phone, NID

Lease Management API

• POST /api/leases - Create lease with unit assignment
• GET /api/leases - List leases with tenant and unit context
• GET /api/leases/{id} - Get lease with full hierarchy (Property → Building → Unit)
• PUT /api/leases/{id} - Update lease terms
• DELETE /api/leases/{id} - Terminate lease
• GET /api/tenants/{tenantId}/leases - Get all leases for a tenant
• GET /api/units/{unitId}/leases - Get lease history for a unit

Business Logic

• Tenant contact information validation (phone format, email format)
• NID number validation and uniqueness
• Lease date validation (start date, duration)
• Unit availability checking before lease creation
• Prevent overlapping leases for the same unit
• Support multiple concurrent leases per tenant
• Lease renewal workflow with historical preservation

Multi-Unit Support

• Tenant can have multiple active leases across different units
• Lease aggregation for tenants with multiple units
• Cross-property lease support (tenant renting in multiple properties)
• Combined billing for multi-unit tenants
• Lease relationship tracking (e.g., apartment + parking space)

Historical Data Management

• Complete lease history preservation
• Tenant change audit trail with timestamps
• Payment history preservation across lease changes
• Unit occupancy history tracking
• Tenant migration between units with data continuity

Frontend Integration

• Tenant profile creation and editing forms
• Lease management interface with unit selection
• Multi-unit lease creation workflow
• Tenant search with autocomplete
• Lease history display with hierarchy context
• Tenant dashboard showing all current leases

Testing

• Unit tests for tenant and lease business logic
• Integration tests for multi-unit scenarios
• Validation tests for all business rules
• Historical data integrity tests
• Performance tests for tenant search and lease queries

Documentation

• API documentation with multi-unit examples
• Business rule documentation
• Data model relationship documentation
• User workflow documentation

Technical Notes

• Support for complex tenant-unit relationships
• Historical data preservation for audit compliance
• Efficient queries for multi-unit tenant scenarios
• Integration with payment system for billing

Dependencies

• Unit Management API (Issue Set up authentication and security infrastructure #3)
• Property hierarchy (Issues Initialize project structure and development environment #1, Implement core database schema and migrations #2)
• Authentication system

Labels

backend, frontend, tenant-management, lease-management, multi-unit