Community 93 Premium feature complete

2025-12-21 11:31:10 -06:00
parent 1bde31247f
commit 95f5e89e48
60 changed files with 8061 additions and 350 deletions
--- a/COMMUNITY-STATIONS-INTEGRATION-GUIDE.md
+++ b/COMMUNITY-STATIONS-INTEGRATION-GUIDE.md
@@ -0,0 +1,310 @@
+# Community Gas Stations - Integration Guide
+
+Quick reference for integrating the community gas stations feature into MotoVaultPro.
+
+## 1. Add Routes to App.tsx
+
+Add these imports at the top of your main App.tsx or routing file:
+
+```typescript
+import { CommunityStationsPage } from './features/stations/pages/CommunityStationsPage';
+import { CommunityStationsMobileScreen } from './features/stations/mobile/CommunityStationsMobileScreen';
+import { AdminCommunityStationsPage } from './features/admin/pages/AdminCommunityStationsPage';
+import { AdminCommunityStationsMobileScreen } from './features/admin/mobile/AdminCommunityStationsMobileScreen';
+```
+
+Add these routes in your route configuration:
+
+```typescript
+// User routes
+<Route path="/stations/community" element={<CommunityStationsPage />} />
+<Route path="/mobile/stations/community" element={<CommunityStationsMobileScreen />} />
+
+// Admin routes
+<Route path="/admin/community-stations" element={<AdminCommunityStationsPage />} />
+<Route path="/mobile/admin/community-stations" element={<AdminCommunityStationsMobileScreen />} />
+```
+
+## 2. Update Navigation
+
+### User Navigation
+Add link to Community Stations:
+```tsx
+<NavLink to="/stations/community">
+  Community Stations
+</NavLink>
+```
+
+### Admin Navigation
+Add link to Admin Community Stations:
+```tsx
+<NavLink to="/admin/community-stations">
+  Community Station Reviews
+</NavLink>
+```
+
+## 3. Backend API Implementation
+
+### Required Endpoints
+
+Implement these endpoints in your backend API:
+
+#### User Endpoints
+```
+POST /api/stations/community/submit
+  Body: SubmitStationData
+  Response: CommunityStation
+
+GET /api/stations/community/mine
+  Response: CommunityStation[]
+
+DELETE /api/stations/community/:id
+  Response: 204 No Content
+
+GET /api/stations/community/approved?page=0&limit=50
+  Response: { stations: CommunityStation[], total: number, page: number, limit: number }
+
+POST /api/stations/community/nearby
+  Body: { latitude, longitude, radiusMeters }
+  Response: CommunityStation[]
+```
+
+#### Admin Endpoints
+```
+GET /api/stations/community/admin/submissions?status=&page=0&limit=50
+  Response: CommunityStationsListResponse
+
+GET /api/stations/community/admin/pending?page=0&limit=50
+  Response: CommunityStationsListResponse
+
+PATCH /api/stations/community/admin/:id/review
+  Body: { status: 'approved' | 'rejected', rejectionReason?: string }
+  Response: CommunityStation
+
+POST /api/stations/community/admin/bulk-review
+  Body: { ids: string[], status: 'approved' | 'rejected', rejectionReason?: string }
+  Response: CommunityStation[]
+```
+
+### Database Schema
+
+The backend should have migrations for the `community_stations` table:
+
+```sql
+CREATE TABLE community_stations (
+  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+  submitted_by VARCHAR(255) NOT NULL,
+  name VARCHAR(200) NOT NULL,
+  address TEXT NOT NULL,
+  city VARCHAR(100),
+  state VARCHAR(50),
+  zip_code VARCHAR(20),
+  latitude DECIMAL(10, 8) NOT NULL,
+  longitude DECIMAL(11, 8) NOT NULL,
+  brand VARCHAR(100),
+  has_93_octane BOOLEAN DEFAULT true,
+  has_93_octane_ethanol_free BOOLEAN DEFAULT false,
+  price_93 DECIMAL(5, 3),
+  notes TEXT,
+  status VARCHAR(20) DEFAULT 'pending' CHECK (status IN ('pending', 'approved', 'rejected')),
+  reviewed_by VARCHAR(255),
+  reviewed_at TIMESTAMP WITH TIME ZONE,
+  rejection_reason TEXT,
+  created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX idx_community_stations_status ON community_stations(status);
+CREATE INDEX idx_community_stations_submitted_by ON community_stations(submitted_by);
+CREATE INDEX idx_community_stations_location ON community_stations(latitude, longitude);
+CREATE INDEX idx_community_stations_created_at ON community_stations(created_at DESC);
+```
+
+## 4. Environment Variables
+
+No additional environment variables required. The API client uses the existing `VITE_API_BASE_URL`.
+
+## 5. Testing
+
+### Run Component Tests
+```bash
+npm test -- features/stations/community
+npm test -- features/admin/community
+```
+
+### Test Mobile Viewport
+```bash
+# Open DevTools and set viewport to 375x667 (mobile)
+# Test on: Browse, Submit, My Submissions tabs
+# Verify: Form submission, withdrawal, pagination
+```
+
+### Test Desktop Viewport
+```bash
+# Open on 1920x1080 (desktop)
+# Test on: Browse All, My Submissions, Near Me tabs
+# Verify: Submit dialog, status filtering, nearby stations
+```
+
+## 6. Manual Testing Checklist
+
+### User Features
+- [ ] Navigate to /stations/community
+- [ ] Submit new station with geolocation
+- [ ] Submit station with manual coordinates
+- [ ] Submit station with all optional fields
+- [ ] View approved stations
+- [ ] View personal submissions
+- [ ] Withdraw pending submission
+- [ ] View rejected submission with reason
+- [ ] Browse nearby approved stations
+- [ ] Test pagination
+- [ ] Test form validation (missing fields)
+- [ ] Test location permission denied
+- [ ] Test on mobile viewport
+- [ ] Test on desktop viewport
+- [ ] Test tab switching
+
+### Admin Features
+- [ ] Navigate to /admin/community-stations
+- [ ] View pending submissions
+- [ ] Approve submission
+- [ ] Reject submission with reason
+- [ ] Filter submissions by status
+- [ ] View all submissions
+- [ ] View approval statistics
+- [ ] Test pagination
+- [ ] Test on mobile viewport
+- [ ] Test on desktop viewport
+- [ ] Test tab switching
+- [ ] Verify admin-only access
+
+## 7. Deployment
+
+### Prerequisites
+1. Backend API endpoints implemented
+2. Database migrations applied
+3. Admin role configured in authentication
+4. Test on staging environment
+
+### Deployment Steps
+1. Merge to main branch
+2. Run full test suite
+3. Build and deploy frontend
+4. Verify routes are accessible
+5. Monitor logs for errors
+6. Test on mobile and desktop
+
+## 8. Monitoring
+
+### Key Metrics
+- Form submission success rate
+- Approval/rejection ratio
+- Pending submissions count
+- Error rate on API endpoints
+- Mobile vs desktop usage
+
+### Common Issues
+
+**Form submission fails**
+- Check backend API endpoints are implemented
+- Verify JWT authentication is working
+- Check CORS settings
+
+**Geolocation not working**
+- Check browser permissions
+- Test on HTTPS only (required for geolocation)
+- Verify GPS access on mobile device
+
+**Admin endpoints return 403**
+- Verify user has admin role
+- Check authentication token is valid
+- Check admin authorization middleware
+
+**Images/photos not loading**
+- Verify station photo API endpoints
+- Check CloudFront/CDN cache
+- Check CORS headers
+
+## 9. Performance Optimization
+
+### Implemented
+- React Query caching
+- Lazy loading of routes
+- Code splitting
+- Image optimization
+
+### Optional Enhancements
+- Implement infinite scroll for stations list
+- Add offline support with service workers
+- Implement map tile caching
+- Add predictive prefetching
+
+## 10. Security Considerations
+
+### Already Implemented
+- JWT authentication on all endpoints
+- User-scoped data isolation
+- Admin role-based access control
+- Form validation (Zod)
+- Input sanitization via axios
+
+### Verify
+- SQL injection prevention (parameterized queries)
+- XSS prevention (React's built-in escaping)
+- CSRF token validation
+- Rate limiting on API endpoints
+- Admin operations audit logging
+
+## Quick Troubleshooting
+
+### Components not rendering
+1. Check routes are added to App.tsx
+2. Verify imports are correct
+3. Check browser console for errors
+4. Verify React Query is initialized
+
+### API calls failing
+1. Check backend endpoints are implemented
+2. Verify base URL is correct (VITE_API_BASE_URL)
+3. Check authentication token is included
+4. Verify CORS headers
+
+### Tests failing
+1. Mock API responses correctly
+2. Use React Query's test utilities
+3. Check for missing wait() calls
+4. Verify Zod schema matches types
+
+### Mobile layout broken
+1. Check viewport settings
+2. Verify MUI breakpoints are used
+3. Check responsive classes
+4. Test on actual mobile device
+
+## Support
+
+For detailed documentation, see:
+- `/frontend/src/features/stations/COMMUNITY-STATIONS-README.md`
+- `/COMMUNITY-STATIONS-IMPLEMENTATION.md`
+- `/COMMUNITY-STATIONS-FILES.md`
+
+## File References
+
+All absolute paths to files:
+
+### User Features
+- Desktop Page: `/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/src/features/stations/pages/CommunityStationsPage.tsx`
+- Mobile Screen: `/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/src/features/stations/mobile/CommunityStationsMobileScreen.tsx`
+- Submit Form: `/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/src/features/stations/components/SubmitStationForm.tsx`
+- Station Card: `/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/src/features/stations/components/CommunityStationCard.tsx`
+- Hooks: `/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/src/features/stations/hooks/useCommunityStations.ts`
+
+### Admin Features
+- Desktop Page: `/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/src/features/admin/pages/AdminCommunityStationsPage.tsx`
+- Mobile Screen: `/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/src/features/admin/mobile/AdminCommunityStationsMobileScreen.tsx`
+- Review Card: `/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/src/features/admin/components/CommunityStationReviewCard.tsx`
+
+### API & Types
+- API Client: `/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/src/features/stations/api/community-stations.api.ts`
+- Types: `/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/src/features/stations/types/community-stations.types.ts`