272 lines
6.0 KiB
Markdown
272 lines
6.0 KiB
Markdown
# Volunteer Pages
|
|
|
|
Volunteer pages provide the volunteer portal interface for canvassing activities. These pages require authentication and are optimized for field use with GPS tracking and mobile responsiveness.
|
|
|
|
## Route Context
|
|
|
|
- **Prefix:** `/volunteer/*`
|
|
- **Layout:** [VolunteerLayout](../../layouts/index.md) (top navigation)
|
|
- **Auth Required:** Yes (any role)
|
|
- **Theme:** Dark theme (consistent with public pages)
|
|
- **Mobile:** Optimized for mobile/tablet use
|
|
|
|
## Dashboard
|
|
|
|
### Volunteer Dashboard
|
|
|
|
**Route:** `/volunteer/dashboard`
|
|
|
|
Volunteer overview with:
|
|
|
|
- Personal statistics
|
|
- Upcoming assignments
|
|
- Recent activity
|
|
- Quick actions
|
|
|
|
**Features:**
|
|
- Visit count and outcomes
|
|
- Next shift information
|
|
- Activity summary
|
|
- Mobile responsive
|
|
|
|
## Shift Management
|
|
|
|
### [Volunteer Shifts Page](volunteer-shifts-page.md)
|
|
|
|
**Route:** `/volunteer/assignments`
|
|
|
|
Assigned shifts for logged-in volunteer:
|
|
|
|
- Upcoming shifts list
|
|
- Cut information
|
|
- Start canvass button
|
|
- Shift details
|
|
|
|
**Features:**
|
|
- Filter by date
|
|
- Cut assignment display
|
|
- Quick start canvassing
|
|
- Email notifications
|
|
- Mobile responsive
|
|
|
|
**Note:** Only shows shifts with `cutId` assigned (required for canvassing).
|
|
|
|
## Canvassing
|
|
|
|
### [Volunteer Map Page](volunteer-map-page.md)
|
|
|
|
**Route:** `/volunteer/canvass/:cutId`
|
|
|
|
Full-screen GPS canvass map:
|
|
|
|
- Leaflet map with GPS tracking
|
|
- Location markers by status
|
|
- Walking route polyline
|
|
- Bottom sheet toolbar
|
|
- Visit recording form
|
|
- Session timer
|
|
|
|
**Features:**
|
|
- GPS position tracking
|
|
- Auto-center on position
|
|
- Color-coded markers:
|
|
- Red - Not visited
|
|
- Blue - Next in route
|
|
- Green - Visited (success outcomes)
|
|
- Orange - Visited (neutral outcomes)
|
|
- Red - Visited (negative outcomes)
|
|
- Click marker to record visit
|
|
- Walking route algorithm
|
|
- Session management
|
|
- Mobile optimized
|
|
|
|
**Full-Screen:**
|
|
- No layout wrapper
|
|
- Custom header with timer
|
|
- Bottom sheet controls
|
|
- Optimized for field use
|
|
|
|
**GPS Tracking:**
|
|
- Watch position API
|
|
- Blue GPS marker
|
|
- Accuracy circle
|
|
- Auto-update every 5 seconds
|
|
|
|
**Visit Recording:**
|
|
- Outcome selection (NOT_HOME, MOVED, REFUSED, etc.)
|
|
- Notes field
|
|
- GPS coordinates captured
|
|
- Rate limited (30/min)
|
|
|
|
**Session Management:**
|
|
- Start/end session
|
|
- Elapsed timer
|
|
- Abandoned session cleanup (12h)
|
|
- Progress tracking
|
|
|
|
## Activity Tracking
|
|
|
|
### [My Activity Page](my-activity-page.md)
|
|
|
|
**Route:** `/volunteer/activity`
|
|
|
|
Visit history and statistics:
|
|
|
|
- Visit list by date
|
|
- Outcome breakdown
|
|
- Session summary
|
|
- Export options
|
|
|
|
**Features:**
|
|
- Filter by date range
|
|
- Group by session
|
|
- Outcome pie chart
|
|
- Total visit count
|
|
- Mobile responsive
|
|
|
|
### [My Routes Page](my-routes-page.md)
|
|
|
|
**Route:** `/volunteer/routes`
|
|
|
|
Walking route history:
|
|
|
|
- Route list by session
|
|
- Distance traveled
|
|
- Time elapsed
|
|
- Location count
|
|
|
|
**Features:**
|
|
- Route visualization
|
|
- Session details
|
|
- Statistics summary
|
|
- Mobile responsive
|
|
|
|
## Volunteer Page Count
|
|
|
|
Total: **4 volunteer pages**
|
|
|
|
## Common Features
|
|
|
|
Volunteer pages share:
|
|
|
|
- **Mobile First** - Touch-friendly controls
|
|
- **GPS Integration** - Location tracking
|
|
- **Dark Theme** - Low-light visibility
|
|
- **Session State** - Zustand canvass store
|
|
- **Real-time Updates** - Auto-refresh data
|
|
- **Offline Support** (future) - Service worker caching
|
|
|
|
## Authentication
|
|
|
|
All volunteer pages require authentication:
|
|
|
|
```typescript
|
|
// Volunteer routes use authenticate middleware
|
|
router.get('/api/canvass/session', authenticate, ...)
|
|
```
|
|
|
|
Role-based redirect after login:
|
|
- **ADMIN roles** → `/app/dashboard`
|
|
- **USER/TEMP roles** → `/volunteer/dashboard`
|
|
|
|
## State Management
|
|
|
|
Volunteer pages use Zustand canvass store:
|
|
|
|
```typescript
|
|
// stores/canvass.store.ts
|
|
interface CanvassStore {
|
|
session: CanvassSession | null;
|
|
locations: CanvassLocation[];
|
|
route: WalkingRoute | null;
|
|
gpsPosition: { lat: number; lng: number } | null;
|
|
currentLocationIndex: number;
|
|
// ... actions
|
|
}
|
|
```
|
|
|
|
## GPS Tracking
|
|
|
|
GPS tracking uses browser Geolocation API:
|
|
|
|
```typescript
|
|
navigator.geolocation.watchPosition(
|
|
(position) => {
|
|
setGpsPosition({
|
|
lat: position.coords.latitude,
|
|
lng: position.coords.longitude,
|
|
});
|
|
},
|
|
(error) => console.error('GPS error:', error),
|
|
{
|
|
enableHighAccuracy: true,
|
|
timeout: 5000,
|
|
maximumAge: 0,
|
|
}
|
|
);
|
|
```
|
|
|
|
## Walking Route Algorithm
|
|
|
|
Routes are calculated server-side using nearest-neighbor algorithm:
|
|
|
|
1. Start at closest location to shift start
|
|
2. For each subsequent location:
|
|
- Find nearest unvisited location
|
|
- Add to route
|
|
3. Return ordered location list
|
|
|
|
Frontend displays route as blue polyline connecting locations.
|
|
|
|
## Visit Outcomes
|
|
|
|
Available outcomes in recording form:
|
|
|
|
- **SUCCESS** - Successful contact
|
|
- **NOT_HOME** - No one home
|
|
- **MOVED** - Resident moved
|
|
- **REFUSED** - Contact refused
|
|
- **WRONG_ADDRESS** - Address error
|
|
- **INACCESSIBLE** - Cannot access
|
|
- **OTHER** - Other outcome
|
|
|
|
## Session Lifecycle
|
|
|
|
1. **Start Session** - Create session record, generate route
|
|
2. **GPS Tracking** - Track position, update markers
|
|
3. **Visit Locations** - Record outcomes, update route
|
|
4. **End Session** - Close session, save statistics
|
|
5. **Abandoned Cleanup** - Auto-close after 12 hours
|
|
|
|
## Mobile Optimization
|
|
|
|
Volunteer pages are optimized for mobile:
|
|
|
|
- **Touch Targets** - Minimum 44px touch areas
|
|
- **GPS Integration** - Native geolocation
|
|
- **Offline Maps** (future) - Cached tiles
|
|
- **Battery Optimization** - Efficient GPS polling
|
|
- **Low-Light Mode** - Dark theme
|
|
- **Network Resilience** - Queue failed requests
|
|
|
|
## Performance
|
|
|
|
GPS canvass map optimizations:
|
|
|
|
- Marker clustering for large datasets
|
|
- Route simplification
|
|
- Debounced position updates
|
|
- Lazy loading location details
|
|
- Service worker caching (future)
|
|
|
|
## Related Documentation
|
|
|
|
- [Frontend Pages Overview](../index.md)
|
|
- [Admin Pages](../admin/index.md)
|
|
- [Public Pages](../public/index.md)
|
|
- [Volunteer Layout](../../layouts/index.md)
|
|
- [Canvass Components](../../components/index.md)
|
|
- [Canvassing Feature](../../../features/map/canvassing.md)
|
|
- [Backend Canvass Module](../../../backend/modules/canvass.md)
|
|
- [Volunteer User Guide](../../../user-guides/volunteer-guide.md)
|