311 lines
9.4 KiB
Markdown
311 lines
9.4 KiB
Markdown
# 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`
|