# Community Gas Stations Feature

Complete implementation of the community gas station submission and review feature for MotoVaultPro. Users can submit 93 octane gas station locations, and admins can review and approve submissions.

## Implementation Complete

All user and admin interfaces have been fully implemented with mobile + desktop parity.

### User Features
- Submit new 93 octane gas stations with location, price, and notes
- View approved community-submitted stations
- Browse nearby approved stations (with geolocation)
- Manage and withdraw pending submissions
- View submission status (pending/approved/rejected)

### Admin Features
- Review pending station submissions
- Approve or reject submissions with optional rejection reasons
- Bulk review multiple submissions
- Filter submissions by status
- View submission statistics

## File Structure

```
frontend/src/features/stations/
├── types/
│   └── community-stations.types.ts      # Type definitions
├── api/
│   └── community-stations.api.ts        # API client
├── hooks/
│   └── useCommunityStations.ts          # React Query hooks
├── components/
│   ├── CommunityStationCard.tsx         # Station display card
│   ├── SubmitStationForm.tsx            # Submission form
│   ├── CommunityStationsList.tsx        # List component
│   └── index-community.ts               # Component exports
├── pages/
│   └── CommunityStationsPage.tsx        # Desktop page
├── mobile/
│   └── CommunityStationsMobileScreen.tsx # Mobile screen
└── __tests__/
    ├── api/
    │   └── community-stations.api.test.ts
    ├── hooks/
    │   └── useCommunityStations.test.ts
    └── components/
        └── CommunityStationCard.test.ts

frontend/src/features/admin/
├── components/
│   ├── CommunityStationReviewCard.tsx   # Review card
│   └── CommunityStationReviewQueue.tsx  # Review queue
├── pages/
│   └── AdminCommunityStationsPage.tsx   # Admin desktop page
└── mobile/
    └── AdminCommunityStationsMobileScreen.tsx # Admin mobile screen
```

## Types

### CommunityStation
Main entity representing a community-submitted gas station.

```typescript
interface CommunityStation {
  id: string;
  submittedBy: string;
  name: string;
  address: string;
  city?: string;
  state?: string;
  zipCode?: string;
  latitude: number;
  longitude: number;
  brand?: string;
  has93Octane: boolean;
  has93OctaneEthanolFree: boolean;
  price93?: number;
  notes?: string;
  status: 'pending' | 'approved' | 'rejected';
  reviewedBy?: string;
  reviewedAt?: string;
  rejectionReason?: string;
  createdAt: string;
  updatedAt: string;
}
```

### SubmitStationData
Form data for submitting a new station.

```typescript
interface SubmitStationData {
  name: string;
  address: string;
  city?: string;
  state?: string;
  zipCode?: string;
  latitude: number;
  longitude: number;
  brand?: string;
  has93Octane: boolean;
  has93OctaneEthanolFree: boolean;
  price93?: number;
  notes?: string;
}
```

## API Endpoints

### User Endpoints
- `POST /stations/community/submit` - Submit new station
- `GET /stations/community/mine` - Get user's submissions
- `DELETE /stations/community/:id` - Withdraw submission
- `GET /stations/community/approved` - Get approved stations (paginated)
- `POST /stations/community/nearby` - Get approved stations nearby

### Admin Endpoints
- `GET /stations/community/admin/submissions` - Get all submissions (with filtering)
- `GET /stations/community/admin/pending` - Get pending submissions
- `PATCH /stations/community/admin/:id/review` - Review submission (approve/reject)
- `POST /stations/community/admin/bulk-review` - Bulk review submissions

## React Query Hooks

All data fetching is handled via React Query with automatic cache invalidation.

### useSubmitStation()
Submit a new community gas station.

```typescript
const { mutate, isPending } = useSubmitStation();
await mutate(formData);
```

### useMySubmissions()
Fetch user's submitted stations.

```typescript
const { data, isLoading } = useMySubmissions();
```

### useWithdrawSubmission()
Withdraw a pending submission.

```typescript
const { mutate } = useWithdrawSubmission();
await mutate(stationId);
```

### useApprovedStations(page, limit)
Fetch approved community stations with pagination.

```typescript
const { data, isLoading } = useApprovedStations(0, 50);
```

### useApprovedNearbyStations(lat, lng, radiusMeters)
Fetch approved stations near user's location.

```typescript
const { data } = useApprovedNearbyStations(latitude, longitude, 5000);
```

### usePendingSubmissions(page, limit)
Fetch pending submissions for admin review.

```typescript
const { data, isLoading } = usePendingSubmissions(0, 50);
```

### useReviewStation()
Approve or reject a submission.

```typescript
const { mutate } = useReviewStation();
await mutate({
  id: stationId,
  decision: { status: 'approved' }
});
```

### useBulkReviewStations()
Bulk approve/reject multiple submissions.

```typescript
const { mutate } = useBulkReviewStations();
await mutate({
  ids: ['1', '2', '3'],
  decision: { status: 'approved' }
});
```

## Components

### CommunityStationCard
Displays a single community station with details and action buttons.

Props:
- `station` - CommunityStation object
- `isAdmin?` - Show admin controls
- `onWithdraw?` - Callback for withdrawal
- `onApprove?` - Callback for approval
- `onReject?` - Callback for rejection
- `distance?` - Distance from user location

### SubmitStationForm
Form for submitting new stations with validation.

Props:
- `onSuccess?` - Callback on successful submission
- `onError?` - Callback on error
- `isLoading?` - Loading state

Features:
- Zod validation
- Geolocation integration
- Mobile-friendly layout
- 44px+ touch targets

### CommunityStationsList
Grid list of community stations with pagination.

Props:
- `stations` - Array of stations
- `loading?` - Loading state
- `error?` - Error message
- `isAdmin?` - Show admin controls
- `page?` - Current page
- `totalPages?` - Total pages
- `onPageChange?` - Page change callback

### CommunityStationReviewCard
Admin review card with approve/reject buttons.

Props:
- `station` - CommunityStation
- `onApprove` - Approve callback
- `onReject` - Reject callback
- `isLoading?` - Loading state

### CommunityStationReviewQueue
Queue of pending submissions for admin review.

Props:
- `stations` - Array of pending stations
- `loading?` - Loading state
- `onApprove` - Approve callback
- `onReject` - Reject callback
- `page?` - Current page
- `totalPages?` - Total pages

## Pages and Screens

### CommunityStationsPage (Desktop)
Main user interface for browsing and submitting stations.

Features:
- Browse all approved stations (paginated)
- View personal submissions
- Browse nearby stations (with geolocation)
- Submit new station via dialog
- Withdraw pending submissions

Layout:
- Header with submit button
- Tab navigation: Browse All, My Submissions, Near Me
- Station cards in responsive grid

### CommunityStationsMobileScreen (Mobile)
Mobile-optimized interface with bottom tab navigation.

Features:
- Same as desktop but optimized for touch
- Bottom tab navigation: Browse, Submit, My Submissions
- Full-screen form dialog
- Touch-friendly spacing and buttons

### AdminCommunityStationsPage (Desktop)
Admin interface for reviewing submissions.

Features:
- Pending submissions tab
- All submissions tab with status filter
- Approval/rejection workflow
- Statistics dashboard
- Status filtering

Layout:
- Header with title
- Tab navigation: Pending, All
- Review cards in grid
- Stats panel

### AdminCommunityStationsMobileScreen (Mobile)
Mobile admin interface.

Features:
- Same as desktop but optimized for touch
- Bottom tab navigation: Pending, All
- Status filter dropdown
- Mobile-friendly review workflow

## Mobile + Desktop Considerations

### Mobile-First Design
- Minimum 44px x 44px touch targets for all buttons
- Full-width forms on mobile
- Bottom tab navigation for mobile screens
- Touch-friendly spacing (16px+ gaps)
- Optimized keyboard input types (email, tel, number)

### Responsive Breakpoints
- Mobile: 320px - 599px
- Tablet: 600px - 1023px
- Desktop: 1024px+

### Validation
- Form validation with Zod schema
- Real-time error display
- Touch-friendly input fields
- Required field indicators

### Accessibility
- ARIA labels on interactive elements
- Keyboard navigation support
- Screen reader friendly
- Proper heading hierarchy

## Testing

### Component Tests
All components have unit tests with:
- Rendering tests
- User interaction tests
- Mobile viewport tests
- Error state tests

### Hook Tests
React Query hooks tested with:
- Mock API responses
- Mutation handling
- Cache invalidation
- Error scenarios

### API Client Tests
API client tested with:
- Successful requests
- Error handling
- Parameter validation
- Pagination

Run tests:
```bash
npm test -- features/stations/community
npm test -- features/admin/community
```

## Integration

To use the community stations feature:

1. **User Page**: Add route to `CommunityStationsPage`
   ```tsx
   <Route path="/stations/community" element={<CommunityStationsPage />} />
   ```

2. **Mobile**: Add route to `CommunityStationsMobileScreen`
   ```tsx
   <Route path="/mobile/stations/community" element={<CommunityStationsMobileScreen />} />
   ```

3. **Admin Page**: Add route to `AdminCommunityStationsPage`
   ```tsx
   <Route path="/admin/community-stations" element={<AdminCommunityStationsPage />} />
   ```

4. **Admin Mobile**: Add route to `AdminCommunityStationsMobileScreen`
   ```tsx
   <Route path="/mobile/admin/community-stations" element={<AdminCommunityStationsMobileScreen />} />
   ```

## Backend API Requirements

The backend must implement the following endpoints:

### User Endpoints
```
POST /api/stations/community/submit
GET /api/stations/community/mine
DELETE /api/stations/community/:id
GET /api/stations/community/approved
POST /api/stations/community/nearby
```

### Admin Endpoints
```
GET /api/stations/community/admin/submissions
GET /api/stations/community/admin/pending
PATCH /api/stations/community/admin/:id/review
POST /api/stations/community/admin/bulk-review
```

See backend documentation for detailed implementation.

## Future Enhancements

- Real-time map view for community stations
- Edit submissions (before approval)
- Community ratings/feedback on stations
- Price history tracking
- Station verification badges
- Duplicate detection and merging
- Admin moderation tools
- Email notifications for reviewers
- Analytics dashboard

## Notes

- All coordinates are decimal degrees (latitude -90 to 90, longitude -180 to 180)
- Prices are in USD per gallon
- Timestamps are ISO 8601 format
- All endpoints require JWT authentication
- Admin endpoints require admin role
- Soft delete is used for submissions
