Sindbad~EG File Manager

# District & Assembly Location System

## Overview

The Church Attendance Management System now uses a structured location system with districts and assemblies linked to a centralized locations database. This ensures data consistency and provides better reporting capabilities.

## Database Structure

### Locations Table
The `locations` table stores both districts and assemblies:

```sql
CREATE TABLE locations (
    id INT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    type ENUM('district', 'assembly') NOT NULL,
    parent_id INT NULL,                    -- Links assemblies to districts
    address TEXT,
    contact_person VARCHAR(100),
    contact_phone VARCHAR(20),
    contact_email VARCHAR(100),
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    FOREIGN KEY (parent_id) REFERENCES locations(id) ON DELETE SET NULL
);
```

### Attendance Records Integration
The `attendance_records` table now includes:
- `district_id` - Foreign key to locations table
- `assembly_id` - Foreign key to locations table
- `district_name` - Text field (for backward compatibility)
- `assembly_name` - Text field (for backward compatibility)

## Key Features

### 1. Hierarchical Structure
- **Districts** are parent locations (type='district', parent_id=NULL)
- **Assemblies** belong to districts (type='assembly', parent_id=district_id)

### 2. Smart Form Integration
- District dropdown loads all active districts
- Assembly dropdown filters based on selected district
- Auto-selection when only one assembly is available for a district

### 3. Data Consistency
- Prevents typos and inconsistent naming
- Standardizes location data across the system
- Enables better reporting and analytics

### 4. Backward Compatibility
- Existing text-based district/assembly names are preserved
- System uses IDs when available, falls back to text fields
- Migration script updates existing records

## Usage Guide

### For End Users (Attendance Forms)

1. **Select District**: Choose from dropdown of available districts
2. **Select Assembly**: Assembly options automatically filter based on district
3. **Required Fields**: Both district and assembly are now required

### For Administrators

#### Managing Locations
1. Go to **Admin Panel > Locations**
2. View districts and assemblies with usage statistics
3. Add, edit, or deactivate locations as needed

#### Adding New District
```
Name: North District
Type: District
Contact Person: John Doe
Phone: (555) 123-4567
Email: north@church.org
Address: 123 North Street
```

#### Adding New Assembly
```
Name: North Main Assembly
Type: Assembly
Parent District: North District
Contact Person: Pastor Smith
Phone: (555) 123-4568
Email: northmain@church.org
```

### For Developers

#### API Endpoints

**Get Locations**
```
GET /admin/api/manage_locations.php?type=district&active_only=true
GET /admin/api/manage_locations.php?type=assembly&active_only=true
```

**Create Location**
```
POST /admin/api/manage_locations.php
{
    "name": "New District",
    "type": "district",
    "contact_person": "Contact Name",
    "contact_phone": "(555) 123-4567",
    "contact_email": "contact@church.org",
    "address": "123 Main St"
}
```

#### Form Integration
```javascript
// Load assemblies based on selected district
function loadAssemblies() {
    const districtId = document.getElementById('district_id').value;
    const assemblySelect = document.getElementById('assembly_id');
    const allOptions = assemblySelect.querySelectorAll('option[data-district]');
    
    // Filter assembly options
    allOptions.forEach(option => {
        if (districtId === '' || option.dataset.district === districtId) {
            option.style.display = 'block';
        } else {
            option.style.display = 'none';
        }
    });
}
```

## Migration Guide

### For New Installations
1. Run the complete `database/schema.sql`
2. System includes all location features by default

### For Existing Installations
1. **Backup your database first!**
2. Visit `/admin/migrate_database.php` as superuser
3. Migration will:
   - Add `district_id` and `assembly_id` columns
   - Create foreign key relationships
   - Update existing records where possible
   - Add database indexes for performance

### Manual Migration (Advanced)
```sql
-- Run the migration script
SOURCE database/migrate_locations.sql;

-- Verify migration
SELECT 
    COUNT(*) as total_records,
    COUNT(district_id) as with_district_id,
    COUNT(assembly_id) as with_assembly_id
FROM attendance_records;
```

## Troubleshooting

### Common Issues

**Q: Assembly dropdown is empty**
A: Ensure the selected district has assemblies assigned to it. Check the locations table.

**Q: Migration failed**
A: Check database permissions and ensure no foreign key conflicts exist.

**Q: Old attendance records show "N/A"**
A: Run the migration script to link existing text-based records to location IDs.

### Database Maintenance

**Check Location Usage**
```sql
SELECT 
    l.name,
    l.type,
    COUNT(DISTINCT ar.id) as attendance_records,
    COUNT(DISTINCT p.id) as programs
FROM locations l
LEFT JOIN attendance_records ar ON (ar.district_id = l.id OR ar.assembly_id = l.id)
LEFT JOIN programs p ON p.location_id = l.id
GROUP BY l.id;
```

**Find Orphaned Records**
```sql
-- Attendance records without valid location IDs
SELECT * FROM attendance_records 
WHERE (district_id IS NOT NULL AND district_id NOT IN (SELECT id FROM locations))
   OR (assembly_id IS NOT NULL AND assembly_id NOT IN (SELECT id FROM locations));
```

## Best Practices

### Data Entry
1. Always use the dropdown selections rather than typing
2. Ensure district-assembly relationships are logical
3. Keep contact information up to date

### Administration
1. Deactivate rather than delete locations with existing records
2. Regularly review and clean up unused locations
3. Monitor usage statistics to identify popular locations

### Development
1. Always check for both ID and text-based location data
2. Use proper foreign key relationships
3. Implement cascading updates carefully

## Testing

### Test Locations System
Visit `/admin/test_locations.php` to:
- Verify database structure
- Check location data integrity
- Test form integration
- Validate API endpoints

### Sample Test Data
The system includes sample districts and assemblies:
- Central District → Central Assembly
- North District → North Assembly

## Support

For technical issues:
1. Check the test page: `/admin/test_locations.php`
2. Review migration status: `/admin/migrate_database.php`
3. Verify database structure matches the schema
4. Check browser console for JavaScript errors

---

**Version**: 1.0  
**Last Updated**: 2024  
**Compatibility**: Church Attendance Management System v1.0+