204 lines
5.7 KiB
Markdown
204 lines
5.7 KiB
Markdown
# Multi-Household Implementation - Quick Reference
|
|
|
|
## Implementation Status
|
|
|
|
### ✅ Sprint 1: Database Foundation (COMPLETE)
|
|
- [x] Created migration script: `multi_household_architecture.sql`
|
|
- [x] Created migration guide: `MIGRATION_GUIDE.md`
|
|
- [x] Created migration runner scripts: `run-migration.sh` / `run-migration.bat`
|
|
- [x] **Tested migration on 'grocery' database (copy of Costco)**
|
|
- [x] Migration successful - all data migrated correctly
|
|
- [x] Verification passed - 0 data integrity issues
|
|
|
|
**Migration Results:**
|
|
- ✅ 1 Household created: "Main Household" (invite code: MAIN755114)
|
|
- ✅ 7 Users migrated (2 system_admins, 5 standard users)
|
|
- ✅ 122 Items extracted to master catalog
|
|
- ✅ 122 Household lists created
|
|
- ✅ 27 Classifications migrated
|
|
- ✅ 273 History records preserved
|
|
- ✅ All users assigned to household (admin/user roles)
|
|
- ✅ 0 orphaned records or data loss
|
|
|
|
**Database:** `grocery` (using Costco as template for safety)
|
|
|
|
### ⏳ Sprint 2: Backend API (NEXT - READY TO START)
|
|
- [ ] Create household.model.js
|
|
- [ ] Create store.model.js
|
|
- [ ] Update list.model.js for household+store scope
|
|
- [ ] Create householdAccess middleware
|
|
- [ ] Create storeAccess middleware
|
|
- [ ] Create households.controller.js
|
|
- [ ] Create stores.controller.js
|
|
- [ ] Update lists.controller.js
|
|
- [ ] Update users.controller.js
|
|
- [ ] Create/update routes for new structure
|
|
|
|
### ⏳ Sprint 3: Frontend Core (PENDING)
|
|
- [ ] Refactor contexts
|
|
- [ ] Create household UI
|
|
- [ ] Create store UI
|
|
|
|
## New Database Schema
|
|
|
|
### Core Tables
|
|
1. **households** - Household entities with invite codes
|
|
2. **stores** - Store types (Costco, Target, etc.)
|
|
3. **household_members** - User membership with per-household roles
|
|
4. **household_stores** - Which stores each household uses
|
|
5. **items** - Master item catalog (shared)
|
|
6. **household_lists** - Lists scoped to household + store
|
|
7. **household_item_classifications** - Classifications per household + store
|
|
8. **household_list_history** - History tracking
|
|
|
|
### Key Relationships
|
|
- User → household_members → Household (many-to-many)
|
|
- Household → household_stores → Store (many-to-many)
|
|
- Household + Store → household_lists → Item (unique per combo)
|
|
- household_lists → household_list_history (one-to-many)
|
|
|
|
## Role System
|
|
|
|
### System-Wide (users.role)
|
|
- **system_admin**: App infrastructure control
|
|
- **user**: Standard user
|
|
|
|
### Household-Scoped (household_members.role)
|
|
- **admin**: Full household control
|
|
- **user**: Standard member
|
|
|
|
## Migration Steps
|
|
|
|
1. **Backup**: `pg_dump grocery_list > backup.sql`
|
|
2. **Run**: `psql -d grocery_list -f backend/migrations/multi_household_architecture.sql`
|
|
3. **Verify**: Check counts, run integrity queries
|
|
4. **Test**: Ensure app functionality
|
|
5. **Cleanup**: Drop old tables after verification
|
|
|
|
## API Changes (Planned)
|
|
|
|
### Old Format
|
|
```
|
|
GET /api/list
|
|
POST /api/list/add
|
|
```
|
|
|
|
### New Format
|
|
```
|
|
GET /api/households/:hId/stores/:sId/list
|
|
POST /api/households/:hId/stores/:sId/list/add
|
|
```
|
|
|
|
## Frontend Changes (Planned)
|
|
|
|
### New Contexts
|
|
```jsx
|
|
const { user, isSystemAdmin } = useAuth();
|
|
const { activeHousehold, isAdmin } = useHousehold();
|
|
const { activeStore, householdStores } = useStore();
|
|
```
|
|
|
|
### New Routes
|
|
```
|
|
/households - List households
|
|
/households/:id/stores/:sId - Grocery list
|
|
/households/:id/members - Manage members
|
|
/join/:inviteCode - Join household
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
### Phase 1: Database (Current)
|
|
1. Review migration script
|
|
2. Test on local dev database
|
|
3. Run verification queries
|
|
4. Document any issues
|
|
|
|
### Phase 2: Backend API (Next)
|
|
1. Create household.model.js
|
|
2. Create store.model.js
|
|
3. Update list.model.js for household scope
|
|
4. Create middleware for household access
|
|
5. Update routes
|
|
|
|
### Phase 3: Frontend
|
|
1. Refactor AuthContext → useAuth()
|
|
2. Create HouseholdContext → useHousehold()
|
|
3. Create StoreContext → useStore()
|
|
4. Build household switcher
|
|
5. Build store tabs
|
|
|
|
## Testing Checklist
|
|
|
|
### Database Migration
|
|
- [ ] All tables created
|
|
- [ ] All indexes created
|
|
- [ ] Users migrated to household
|
|
- [ ] Items deduplicated correctly
|
|
- [ ] Lists migrated with correct references
|
|
- [ ] Classifications preserved
|
|
- [ ] History preserved
|
|
- [ ] No NULL foreign keys
|
|
|
|
### Backend API
|
|
- [ ] Household CRUD works
|
|
- [ ] Member management works
|
|
- [ ] Invite codes work
|
|
- [ ] Store management works
|
|
- [ ] List operations scoped correctly
|
|
- [ ] Permissions enforced
|
|
- [ ] History tracked correctly
|
|
|
|
### Frontend UI
|
|
- [ ] Login/logout works
|
|
- [ ] Household switcher works
|
|
- [ ] Store tabs work
|
|
- [ ] Can create household
|
|
- [ ] Can join household
|
|
- [ ] Can add items
|
|
- [ ] Can mark bought
|
|
- [ ] Roles respected in UI
|
|
|
|
## Rollback Strategy
|
|
|
|
If migration fails:
|
|
```sql
|
|
ROLLBACK;
|
|
```
|
|
|
|
If issues found after:
|
|
```bash
|
|
psql -d grocery_list < backup.sql
|
|
```
|
|
|
|
## Support Resources
|
|
|
|
- **Migration Script**: `backend/migrations/multi_household_architecture.sql`
|
|
- **Guide**: `backend/migrations/MIGRATION_GUIDE.md`
|
|
- **Architecture**: `docs/multi-household-architecture-plan.md`
|
|
- **Status**: This file
|
|
|
|
## Key Decisions
|
|
|
|
1. ✅ Keep users.role for system admin
|
|
2. ✅ Simplify household roles to admin/user
|
|
3. ✅ Preserve user names in history (no anonymization)
|
|
4. ✅ Shared item catalog with household-specific lists
|
|
5. ✅ Context pattern refactoring (internal context + custom hooks)
|
|
|
|
## Timeline
|
|
|
|
- **Week 1-2**: Database migration + testing
|
|
- **Week 3-4**: Backend API implementation
|
|
- **Week 5-6**: Frontend core implementation
|
|
- **Week 7**: Member management
|
|
- **Week 8-9**: Testing & polish
|
|
- **Week 10**: Production migration
|
|
|
|
## Contact
|
|
|
|
For questions or issues during implementation, refer to:
|
|
- Architecture plan for design decisions
|
|
- Migration guide for database steps
|
|
- This file for quick status updates
|