128 lines
4.9 KiB
Markdown
128 lines
4.9 KiB
Markdown
# Report Verification System Implementation
|
|
|
|
## Overview
|
|
Implemented a comprehensive report verification system that allows authenticated users to verify or dispute litter reports, maintaining data quality through community-driven validation.
|
|
|
|
## Features Implemented
|
|
|
|
### Backend (Server)
|
|
|
|
#### 1. Verification Service (`server/src/services/reportService.ts`)
|
|
- **`verifyReport(reportId, userId, comment?)`**: Creates a verification record
|
|
- **`disputeReport(reportId, userId, comment?)`**: Creates a dispute record
|
|
- **`updateReportVerificationStatus(reportId)`**: Auto-updates report status based on counts
|
|
- Status becomes "verified" with 2+ verifications
|
|
- Status becomes "disputed" with 3+ disputes (auto-hide)
|
|
- **Enhanced `getReports()`**: Filters out disputed reports from public view by default
|
|
- **Enhanced `getReportById()`**: Returns verification/dispute counts and full audit log
|
|
|
|
#### 2. Verification Controller (`server/src/controllers/reportController.ts`)
|
|
- **POST `/api/reports/:id/verify`**: Verify a report endpoint
|
|
- **POST `/api/reports/:id/dispute`**: Dispute a report endpoint
|
|
- Both endpoints:
|
|
- Require authentication
|
|
- Accept optional comment
|
|
- Prevent duplicate verifications from same user
|
|
- Return updated report with new counts
|
|
|
|
#### 3. Routes (`server/src/routes/reportRoutes.ts`)
|
|
- Added verification endpoints to report routes
|
|
- Protected with `requireAuth` middleware
|
|
|
|
### Frontend (Client)
|
|
|
|
#### 1. Updated Types (`src/types/index.ts`)
|
|
- Added `Verification` interface with user details
|
|
- Extended `ReportResponseDTO` to include:
|
|
- `verificationCount`: Number of verifications
|
|
- `disputeCount`: Number of disputes
|
|
- `verifications`: Array of verification records with user info
|
|
|
|
#### 2. Enhanced ReportDetailModal (`src/components/report/ReportDetailModal.tsx`)
|
|
- **Verification Buttons**: Verify/Dispute buttons for authenticated users
|
|
- **Comment Forms**: Optional comment input for both verify and dispute actions
|
|
- **Verification Stats**: Display counts with icons
|
|
- **Auto-hide Warning**: Red alert banner for reports with 3+ disputes
|
|
- **Audit Log**: Collapsible verification history showing:
|
|
- Username of verifier/disputer
|
|
- Action type (verify/dispute)
|
|
- Timestamp
|
|
- Optional comment
|
|
- Sorted by most recent first
|
|
|
|
#### 3. Updated MapPage (`src/pages/MapPage.tsx`)
|
|
- Integrated ReportDetailModal for full report display
|
|
- Added verification handlers:
|
|
- `handleVerify()`: Calls API and refreshes data
|
|
- `handleDispute()`: Calls API and refreshes data
|
|
- Auto-refreshes report list after verification actions
|
|
- Shows loading state while fetching report details
|
|
- Only shows verify/dispute buttons to signed-in users
|
|
|
|
#### 4. Report Service (`src/services/reportService.ts`)
|
|
- Added `verifyReport(reportId, comment?)` method
|
|
- Added `disputeReport(reportId, comment?)` method
|
|
|
|
## Auto-Hide Logic
|
|
|
|
Reports are automatically hidden from public view when they receive 3 or more disputes:
|
|
|
|
1. **Backend**: `updateReportVerificationStatus()` sets status to "disputed"
|
|
2. **Backend**: `getReports()` filters out disputed reports by default
|
|
3. **Frontend**: Displays warning banner on disputed reports
|
|
4. **Frontend**: Report still accessible via direct link but marked as disputed
|
|
|
|
## Verification Status Flow
|
|
|
|
```
|
|
pending (default)
|
|
↓
|
|
├─→ verified (2+ verifications)
|
|
└─→ disputed (3+ disputes) → auto-hidden
|
|
```
|
|
|
|
## User Experience
|
|
|
|
1. User clicks on a report marker on the map
|
|
2. ReportDetailModal opens with full report details
|
|
3. If signed in, user sees "Verify Report" and "Dispute Report" buttons
|
|
4. Clicking either button shows a comment form
|
|
5. User can optionally add a comment explaining their action
|
|
6. After submission:
|
|
- Report status updates automatically
|
|
- Verification counts update
|
|
- Audit log shows the new entry
|
|
- Report list refreshes to reflect changes
|
|
|
|
## Security & Validation
|
|
|
|
- All verification endpoints require authentication
|
|
- Users cannot verify/dispute the same report twice
|
|
- Comments are optional but stored for transparency
|
|
- Verification history is immutable (audit trail)
|
|
- Disputed reports are hidden but not deleted
|
|
|
|
## Testing
|
|
|
|
Created `server/src/scripts/testVerification.ts` to verify:
|
|
- Verification count calculations
|
|
- Dispute count calculations
|
|
- Auto-hide logic for 3+ disputes
|
|
- Status updates based on counts
|
|
|
|
## Requirements Satisfied
|
|
|
|
✅ **7.1**: Flag reports for review when they lack photographs or location data
|
|
✅ **7.2**: Allow designated users to mark reports as verified or disputed
|
|
✅ **7.3**: Auto-hide reports with 3+ dispute flags
|
|
✅ **7.4**: Display verification status indicators on report details
|
|
✅ **7.5**: Maintain audit log of all verification actions with user identifier and timestamp
|
|
|
|
## Future Enhancements
|
|
|
|
- Admin panel to review disputed reports
|
|
- Email notifications for report authors when their report is disputed
|
|
- Reputation system based on verification accuracy
|
|
- Bulk verification for trusted users
|
|
- Appeal process for disputed reports
|