# ICTAZ Smart Register - System Guide

## Understanding Events & Event Categories

### Event Categories
Event Categories are **optional organizational tags** for grouping related events. Think of them as folders or labels.

**Examples:**
- Category: "AGM Events" → Events: AGM Day 1, AGM Day 2, AGM Day 3
- Category: "Training Programs" → Events: Python Workshop, Cloud Computing, Cybersecurity
- Category: "Conferences" → Events: Tech Summit 2026, Digital Transformation Forum

**You don't need categories** — they're purely for organization in the admin panel.

---

## Multi-Day Event Scenario: AGM Example

### The Problem
You have an **AGM spanning 3 days** with different activities:
- **Day 1:** Conference
- **Day 2:** Training
- **Day 3:** AGM Meeting

**Same attendees** should be tracked across all days.

### Solution: Create Separate Events

**Option 1: Individual Events (Recommended)**
```
Event 1: "AGM 2026 - Day 1 Conference"
  - Start: 2026-03-15 09:00
  - End: 2026-03-15 17:00
  - Category: AGM 2026

Event 2: "AGM 2026 - Day 2 Training"
  - Start: 2026-03-16 09:00
  - End: 2026-03-16 17:00
  - Category: AGM 2026

Event 3: "AGM 2026 - Day 3 Meeting"
  - Start: 2026-03-17 09:00
  - End: 2026-03-17 17:00
  - Category: AGM 2026
```

**Option 2: Parent-Child Events**
```
Parent Event: "AGM 2026"
  - Start: 2026-03-15
  - End: 2026-03-17
  - is_active: True

Sub-Event 1: "Day 1 - Conference"
  - parent_event: AGM 2026
  - Start: 2026-03-15 09:00
  - End: 2026-03-15 17:00

Sub-Event 2: "Day 2 - Training"
  - parent_event: AGM 2026
  - Start: 2026-03-16 09:00
  - End: 2026-03-16 17:00

Sub-Event 3: "Day 3 - Meeting"
  - parent_event: AGM 2026
  - Start: 2026-03-17 09:00
  - End: 2026-03-17 17:00
```

---

## Member Registration & Attendance Flow

### Step 1: Upload Members (One-Time)
Upload your member list **once** via CSV in Django Admin:
1. Go to **Admin → Attendance → Registered Members**
2. Click **"Import CSV"** button (top right)
3. Select Event: "AGM 2026 - Day 1 Conference" (or leave blank)
4. Upload CSV with columns:
   - Registration Code (barcode)
   - Full Name
   - Email
   - Status (approved)
   - Payment Status (paid)

**CSV Example:**
```csv
Registration Code,Full Name,Email,Status,Payment Status
MEM001,John Doe,john@example.com,approved,paid
MEM002,Jane Smith,jane@example.com,approved,paid
MEM003,Bob Johnson,bob@example.com,approved,paid
```

### Step 2: Track Attendance Per Event
**Each day/event has separate attendance tracking:**

**Day 1 (Conference):**
- Scanner selects "AGM 2026 - Day 1 Conference"
- Scans MEM001 → Attendance recorded for Day 1
- Scans MEM002 → Attendance recorded for Day 1

**Day 2 (Training):**
- Scanner selects "AGM 2026 - Day 2 Training"
- Scans MEM001 → **New** attendance record for Day 2
- Scans MEM003 → Attendance recorded for Day 2

**Day 3 (Meeting):**
- Scanner selects "AGM 2026 - Day 3 Meeting"
- Scans members → Attendance recorded for Day 3

### Step 3: View Reports
- **Dashboard** shows attendance stats per event
- **Attendance Records** in admin shows who attended which event
- **Export CSV** to see full attendance breakdown

---

## Key Points

✅ **Same members, different events** — Upload members once, track across multiple events
✅ **One barcode per member** — The Registration Code is the barcode (e.g., MEM001)
✅ **Event selection matters** — Scanner must select the correct event before scanning
✅ **No duplicate attendance** — System prevents scanning the same member twice for the same event
✅ **Cross-event tracking** — Member MEM001 can attend Day 1, Day 2, and Day 3 (separate records)

---

## CSV Upload Locations

### Django Admin (Jazzmin)
**Path:** `http://127.0.0.1:8000/admin/attendance/registeredmember/`
- Click **"Import CSV"** button (top right, next to "Add Registered Member")
- Select optional event to assign all imported members
- Upload CSV file
- View success/error messages

### Frontend Admin (Next.js)
**Path:** `http://localhost:3000/attendance`
- Click **"Upload CSV"** button
- Select event from dropdown
- Upload CSV file
- Real-time import feedback

**Both methods use the same API endpoint** (`/api/attendance/upload-csv/`)

---

## Workflow Summary

```
1. Create Events in Django Admin
   ↓
2. Upload Members via CSV (Django Admin or Frontend)
   ↓
3. Assign Scanners to Events (Django Admin → Scanner Assignments)
   ↓
4. Scan Attendance (Frontend /scanner)
   ↓
5. View Reports (Frontend /dashboard or Django Admin)
   ↓
6. Export Data (CSV export from Django Admin or Frontend)
```

---

## API Integration (Optional)

If you want to **pull members from an external API** instead of CSV:

1. Create a custom Django management command:
   ```python
   # backend/apps/attendance/management/commands/import_from_api.py
   from django.core.management.base import BaseCommand
   import requests
   from apps.attendance.models import RegisteredMember
   from apps.events.models import Event
   
   class Command(BaseCommand):
       def handle(self, *args, **options):
           response = requests.get('https://your-api.com/members')
           members = response.json()
           
           event = Event.objects.get(name="AGM 2026")
           
           for member in members:
               RegisteredMember.objects.update_or_create(
                   registration_code=member['barcode'],
                   defaults={
                       'full_name': member['name'],
                       'email': member['email'],
                       'event': event,
                       'status': 'approved',
                       'payment_status': 'paid',
                   }
               )
   ```

2. Run: `python manage.py import_from_api`

---

## Troubleshooting

**Q: I uploaded members but they don't show in the scanner**
- Check that the event is `is_active=True`
- Verify members have `status='approved'`
- Ensure scanner is assigned to the correct event

**Q: Barcode not recognized**
- Check that `Registration Code` in CSV matches the barcode value exactly
- No extra spaces or special characters

**Q: Can't see Import CSV button in Django Admin**
- Restart the Django server after adding the admin customization
- Clear browser cache
- Check that you're logged in as superuser

**Q: Dashboard shows "Can't load events"**
- Create at least one Event in Django Admin
- Ensure event has `is_active=True` and `is_archived=False`