========================================
CHORE SYSTEM UPGRADE - Complete Guide
========================================

This upgrade adds:
✅ Multiple users per chore
✅ Birthday-based chore filtering
✅ Admin chore editing
✅ Points system display
✅ Improved chore assignment workflow

========================================
STEP 1: Run Database Migrations (if not done)
========================================

cd D:\Hosted\familyhub
run_migrations.bat

This creates the chore_assignments table.

========================================
STEP 2: Update Backend Files
========================================

The following backend files have been updated:

1. backend/app/schemas/chore.py
   - Added assigned_user_ids for multiple users
   - Added assigned_users list in response
   - Added points field

2. backend/app/api/v1/chores.py
   - Multi-user assignment support
   - Birthday filtering (exclude_birthdays parameter)
   - Admin-only editing for full chore details
   - Non-admins can only update status
   - Completion tracking per user
   - GET /api/v1/chores?user_id=X&exclude_birthdays=true
   - POST /api/v1/chores/{id}/assign - Assign multiple users

========================================
STEP 3: Update Frontend Files
========================================

The following files need to be updated:

📁 frontend/src/api/chores.ts
   ✅ Already updated in familyhub directory

📁 frontend/src/components/ChoreCard.tsx
   📄 New version: ChoreCard_updated.tsx
   - Shows multiple assigned users
   - Shows points value
   - Birthday indicator (🎂)
   - Completion status per user
   - Admin edit button

📁 frontend/src/components/CreateChoreModal.tsx
   📄 New version: CreateChoreModal_updated.tsx
   - Multi-select user assignment
   - Points input field
   - Improved validation

📁 frontend/src/components/EditChoreModal.tsx
   📄 NEW COMPONENT
   - Admin-only chore editing
   - Update all chore fields
   - Reassign users
   - Change points

📁 frontend/src/pages/Dashboard.tsx
   📄 New version: Dashboard_updated.tsx
   - Birthday filter toggle
   - User filter dropdown
   - Points display in stats
   - Edit button for admins

========================================
STEP 4: Copy Updated Files
========================================

Copy the following files to replace originals:

From: D:\Hosted\familyhub\ChoreCard_updated.tsx
To:   D:\Hosted\familyhub\frontend\src\components\ChoreCard.tsx

From: D:\Hosted\familyhub\CreateChoreModal_updated.tsx
To:   D:\Hosted\familyhub\frontend\src\components\CreateChoreModal.tsx

From: D:\Hosted\familyhub\EditChoreModal.tsx
To:   D:\Hosted\familyhub\frontend\src\components\EditChoreModal.tsx

From: D:\Hosted\familyhub\Dashboard_updated.tsx
To:   D:\Hosted\familyhub\frontend\src\pages\Dashboard.tsx

========================================
STEP 5: Restart Services
========================================

Backend:
cd D:\Hosted\familyhub
restart_backend.bat

Frontend:
cd D:\Hosted\familyhub\frontend
npm run dev

========================================
NEW FEATURES GUIDE
========================================

🎂 BIRTHDAY FILTERING
--------------------
- Chores automatically hidden for users with birthdays today
- Toggle "Hide Birthday Chores" on Dashboard
- API: GET /api/v1/chores?exclude_birthdays=true

👥 MULTIPLE USER ASSIGNMENT
---------------------------
- Assign one chore to multiple users
- Each user can complete independently
- Shows completion status per user
- Create chore: Select multiple users with checkboxes

✏️ ADMIN CHORE EDITING
----------------------
- Admins see "Edit" button on chore cards
- Update title, description, room, frequency
- Change points value
- Reassign users
- Non-admins can only mark complete/skip

⭐ POINTS SYSTEM
---------------
- Each chore has a points value
- Displayed on chore cards
- Dashboard shows total available points
- Track who earned what points

🎯 USER FILTERING
----------------
- Filter chores by assigned user
- Dropdown on Dashboard
- See only chores assigned to specific person

========================================
API ENDPOINTS (Updated)
========================================

GET /api/v1/chores
Query params:
- user_id (int): Filter by assigned user
- exclude_birthdays (bool): Skip birthday users

POST /api/v1/chores
Body:
{
  "title": "Clean kitchen",
  "room": "Kitchen",
  "frequency": "daily",
  "points": 10,
  "assigned_user_ids": [1, 2, 3]  // Multiple users!
}

PUT /api/v1/chores/{id}
Body (Admin):
{
  "title": "Updated title",
  "assigned_user_ids": [2, 3]  // Reassign
  "points": 15
}

Body (Non-admin):
{
  "status": "completed"  // Only this field allowed
}

POST /api/v1/chores/{id}/assign
Body: [1, 2, 3]  // Array of user IDs
Replaces current assignments

========================================
TESTING CHECKLIST
========================================

✅ Create chore with multiple users
✅ View chore showing all assigned users
✅ Complete chore as one user (others still pending)
✅ Edit chore as admin
✅ Try to edit chore as non-admin (should fail except status)
✅ Filter by user
✅ Toggle birthday filter
✅ Set someone's birthday to today, verify chores hidden
✅ View points on chore cards
✅ Check Dashboard stats show correct counts

========================================
TROUBLESHOOTING
========================================

❌ "assigned_user_ids" field error
- Make sure backend migrations ran
- Restart backend after updating schemas

❌ Chores not showing assigned users
- Check browser console for errors
- Verify API returns assigned_users array
- Clear cache (Ctrl+Shift+R)

❌ Birthday filter not working
- Verify user has birthday set in Settings
- Check birthday is set to today's date
- Backend must be restarted after migration

❌ Edit button not showing
- Only admins see edit button
- Make sure user is admin (check Settings)
- Frontend must be reloaded

========================================
DATABASE SCHEMA (Reference)
========================================

USERS TABLE:
- Added: birthday (DATE NULL)

CHORES TABLE:
- Existing: id, title, description, room, frequency, 
            points, status, due_date, completed_at
- Note: assigned_user_id is deprecated (kept for compatibility)

CHORE_ASSIGNMENTS TABLE (NEW):
id              INTEGER PRIMARY KEY
chore_id        INTEGER FK -> chores.id
user_id         INTEGER FK -> users.id
completed_at    DATETIME NULL
created_at      DATETIME

Relationships:
- One chore → Many assignments
- One user → Many assignments
- Assignment tracks individual completion

========================================
NEXT STEPS (Optional Future Enhancements)
========================================

Future features we can add:
- 📊 Points leaderboard
- 🏆 Badges and achievements
- 📧 Email/Discord notifications
- 📱 Home Assistant integration
- 🔄 Recurring chore auto-creation
- 📈 Completion history charts
- 💰 Reward redemption system

========================================