Phase 3.1: Enhanced Chore Logging and Reporting System

2026-02-05 12:33:51 +11:00
commit e3cae7bfbb
178 changed files with 30105 additions and 0 deletions
--- a/CHORE_SYSTEM_UPGRADE_GUIDE.txt
+++ b/CHORE_SYSTEM_UPGRADE_GUIDE.txt
@@ -0,0 +1,257 @@
+========================================
+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
+
+========================================