ocean-cleanup/ATTENDEE_TRACKING_FEATURE.md

# Event Attendee Tracking & Contributions Feature

## Overview

Added comprehensive attendee tracking and individual contribution management for cleanup events. Organizers can now mark who attended, track individual litter collection amounts, and add notes about each volunteer's contribution.

## Database Changes

### Schema Updates
- Added `litter_collected` (DECIMAL 10,2) to `event_registrations` table
- Added `contribution_note` (TEXT) to `event_registrations` table
- Migration: `20251118183315_add_attendee_contributions`

### New Type Definitions
```typescript
interface EventAttendee {
  id: string;
  userId: string;
  eventId: string;
  registeredAt: Date;
  attended: boolean;
  litterCollected?: number;
  contributionNote?: string;
  user: {
    id: string;
    username: string;
    firstName?: string;
    lastName?: string;
    avatarUrl?: string;
  };
}
```

## Backend API Endpoints

### New Endpoints
1. **GET** `/api/events/:id/attendees` - Get all attendees for an event
2. **PATCH** `/api/events/:id/attendees/:attendeeId` - Update single attendee status
3. **POST** `/api/events/:id/attendees/bulk` - Bulk update attendees

### Updated Endpoints
- **POST** `/api/events/:id/complete` - Now accepts optional `attendees` array

## Frontend Components

### 1. AttendeeManagement Component
**Location:** `src/components/event/AttendeeManagement.tsx`

**Features:**
- View all registered attendees
- Mark who attended with checkboxes
- Track individual litter collection (kg)
- Add contribution notes for each volunteer
- Real-time summary stats (registered, attended, total litter)
- Bulk save changes

**Usage:**
```tsx
<AttendeeManagement
  eventId={eventId}
  onClose={handleClose}
  onSave={handleSave}
  isLoading={isLoading}
/>
```

### 2. CompletedEventDetails Component
**Location:** `src/components/event/CompletedEventDetails.tsx`

**Features:**
- Display event completion summary
- Show top contributors with rankings (🥇🥈🥉)
- List all attendees with avatars
- Display event photos in grid
- Expandable contributor list

**Usage:**
```tsx
<CompletedEventDetails
  eventId={event.id}
  totalLitterCollected={event.litterCollected}
  photos={event.photos}
/>
```

### 3. Updated EventCompletionForm
**Location:** `src/components/event/EventCompletionForm.tsx`

**New Flow:**
1. **Step 1: Manage Attendees** - Mark attendance and individual contributions
2. **Step 2: Event Summary** - Add photos and confirm total litter collected
3. Auto-calculates total litter from individual contributions

## Event Completion Workflow

### For Organizers:

1. **After Event Date Passes:**
   - "Complete Event" button appears in event detail modal

2. **Step 1 - Manage Attendees:**
   - View all registered participants
   - Check boxes for who actually attended
   - Enter litter collected by each volunteer (kg)
   - Add optional notes about contributions
   - See real-time totals

3. **Step 2 - Event Summary:**
   - Total litter auto-calculated from attendees
   - Upload event photos (max 5)
   - Review and submit

4. **After Completion:**
   - Event status changes to "completed"
   - Attendee data saved
   - Event marked with completion badge

### For Viewing Completed Events:

**Displays:**
- Total litter collected
- Number of volunteers
- Top contributors with rankings
- All attendees list
- Event photos
- Individual contribution notes

## Service Layer Updates

### Backend (`server/src/services/eventService.ts`)
- `getEventAttendees(eventId)` - Fetch attendees with user details
- `updateAttendeeStatus(eventId, userId, data)` - Update single attendee
- `bulkUpdateAttendees(eventId, attendees)` - Bulk update multiple attendees

### Frontend (`src/services/eventService.ts`)
- Updated `completeEvent()` to handle attendee data
- Automatically calls bulk update before completing event

## UI/UX Features

### Attendee Management Table
- Sortable by name
- Avatar display
- Inline editing
- Real-time validation
- Change tracking (shows count of unsaved changes)

### Completed Event Display
- Green success badge
- Medal icons for top 3 contributors
- Expandable lists
- Photo gallery with click-to-enlarge
- Responsive grid layouts

### Summary Statistics
- Registered count
- Attended count
- Total litter collected
- Individual contributions

## Data Flow

```
1. Organizer clicks "Complete Event"
   ↓
2. AttendeeManagement loads registered users
   ↓
3. Organizer marks attendance & contributions
   ↓
4. Data saved via bulk update API
   ↓
5. EventCompletionForm shows summary
   ↓
6. Organizer adds photos & confirms
   ↓
7. Event marked complete
   ↓
8. CompletedEventDetails displays results
```

## Validation

- Litter amounts must be positive numbers
- Attended status is boolean
- Contribution notes are optional text
- Total litter calculated from individual contributions

## Future Enhancements

Potential additions:
- Export attendee data to CSV
- Send completion certificates to volunteers
- Impact score updates based on contributions
- Leaderboards for top volunteers
- Photo uploads per attendee
- Time tracking for volunteer hours

## Testing

To test the feature:
1. Create an event with a past date
2. Register multiple users
3. As organizer, click "Complete Event"
4. Mark attendees and add contributions
5. Upload photos and complete
6. View completed event details

## Migration Instructions

If deploying to a new environment:
1. Run `npx prisma migrate deploy` in server directory
2. Or manually run: `npx tsx src/scripts/applyMigration.ts`
3. Verify with: `npx tsx src/scripts/verifyMigration.ts`
4. Restart the server