211 lines
6.7 KiB
Markdown
211 lines
6.7 KiB
Markdown
# Response Wall Verification Feature - Deployment Guide
|
|
|
|
## Overview
|
|
This guide walks you through deploying the new Response Wall verification features that were added to the Influence Campaign Tool.
|
|
|
|
## Features Implemented
|
|
|
|
### 1. Postal Code Lookup for Response Submission
|
|
- Users can search by postal code to find their representatives
|
|
- Auto-fills representative details when selected
|
|
- Validates Alberta postal codes (T prefix)
|
|
- Fallback to manual entry if needed
|
|
|
|
### 2. Representative Verification System
|
|
- Optional email verification for submitted responses
|
|
- Representatives receive verification emails with unique tokens
|
|
- Representatives can verify or report responses
|
|
- Verified responses display with special badge
|
|
- Disputed responses are hidden from public view
|
|
|
|
## Deployment Steps
|
|
|
|
### Step 1: Update Database Schema
|
|
|
|
Run the NocoDB setup script to create/update tables with new verification fields:
|
|
|
|
```bash
|
|
cd /path/to/influence
|
|
./scripts/build-nocodb.sh
|
|
```
|
|
|
|
**If you already have existing tables**, you'll need to manually add the new columns through NocoDB UI:
|
|
|
|
1. Log into your NocoDB instance
|
|
2. Open the `influence_representative_responses` table
|
|
3. Add these columns:
|
|
- `representative_email` - Type: Email, Required: No
|
|
- `verification_token` - Type: SingleLineText, Required: No
|
|
- `verification_sent_at` - Type: DateTime, Required: No
|
|
- `verified_at` - Type: DateTime, Required: No
|
|
- `verified_by` - Type: SingleLineText, Required: No
|
|
|
|
### Step 2: Update Environment Variables
|
|
|
|
Add these variables to your `.env` file:
|
|
|
|
```bash
|
|
# Application Name (used in emails)
|
|
APP_NAME="BNKops Influence"
|
|
|
|
# Base URL for verification links
|
|
BASE_URL=https://yourdomain.com
|
|
|
|
# Existing variables to verify:
|
|
SMTP_HOST=your-smtp-host
|
|
SMTP_PORT=587
|
|
SMTP_USER=your-email@domain.com
|
|
SMTP_PASS=your-password
|
|
SMTP_FROM_EMAIL=your-email@domain.com
|
|
SMTP_FROM_NAME="Your Campaign Name"
|
|
```
|
|
|
|
⚠️ **Important:** The `BASE_URL` must be your production domain for verification links to work correctly.
|
|
|
|
### Step 3: Rebuild Docker Container (if using Docker)
|
|
|
|
```bash
|
|
cd /path/to/influence
|
|
docker compose build
|
|
docker compose up -d
|
|
```
|
|
|
|
### Step 4: Verify Email Templates
|
|
|
|
Ensure the email templates are in place:
|
|
|
|
```bash
|
|
ls -la app/templates/email/
|
|
```
|
|
|
|
You should see:
|
|
- `response-verification.html`
|
|
- `response-verification.txt`
|
|
|
|
### Step 5: Test the Feature
|
|
|
|
#### Test Postal Code Lookup:
|
|
1. Go to any campaign's Response Wall
|
|
2. Click "Share a Response"
|
|
3. Enter postal code (e.g., T5K 2J1)
|
|
4. Click Search
|
|
5. Verify representatives appear
|
|
6. Select a representative
|
|
7. Confirm form auto-fills
|
|
|
|
#### Test Verification Email:
|
|
1. Complete the form with all required fields
|
|
2. Check "Send verification request to representative"
|
|
3. Submit the response
|
|
4. Check that confirmation message mentions email sent
|
|
5. Check representative's email inbox for verification email
|
|
|
|
#### Test Verification Flow:
|
|
1. Open verification email
|
|
2. Click "Verify This Response" button
|
|
3. Should see green success page
|
|
4. Check Response Wall - response should have verified badge
|
|
5. Check admin panel - response should be auto-approved
|
|
|
|
#### Test Report Flow:
|
|
1. Open verification email for a different response
|
|
2. Click "Report as Invalid" button
|
|
3. Should see warning page
|
|
4. Check Response Wall - response should be hidden
|
|
5. Check admin panel - response should be marked as rejected
|
|
|
|
## Production Checklist
|
|
|
|
- [ ] Database schema updated with new verification fields
|
|
- [ ] Environment variables configured (APP_NAME, BASE_URL)
|
|
- [ ] Email templates exist and are readable
|
|
- [ ] SMTP settings are correct and tested
|
|
- [ ] Docker container rebuilt and running
|
|
- [ ] Postal code search tested successfully
|
|
- [ ] Verification email sent and received
|
|
- [ ] Verification link works and updates database
|
|
- [ ] Report link works and hides response
|
|
- [ ] Verified badge displays on Response Wall
|
|
- [ ] Admin panel shows verification status correctly
|
|
|
|
## Security Notes
|
|
|
|
1. **Token Security**: Verification tokens are 32-byte cryptographically secure random strings
|
|
2. **Token Expiry**: Consider implementing token expiration (currently no expiry - tokens work indefinitely)
|
|
3. **Rate Limiting**: Existing rate limiting applies to submission endpoint
|
|
4. **Email Validation**: Representative emails are validated on backend
|
|
5. **XSS Prevention**: All user inputs are sanitized before display
|
|
|
|
## Troubleshooting
|
|
|
|
### Verification Emails Not Sending
|
|
- Check SMTP settings in `.env`
|
|
- Verify SMTP credentials are correct
|
|
- Check application logs: `docker logs influence-app -f`
|
|
- Test email connection: Use email test page at `/email-test.html`
|
|
|
|
### Postal Code Search Returns No Results
|
|
- Verify Represent API is accessible
|
|
- Check `REPRESENT_API_BASE` in `.env`
|
|
- Ensure postal code is Alberta format (starts with T)
|
|
- Check browser console for errors
|
|
|
|
### Verification Links Don't Work
|
|
- Verify `BASE_URL` in `.env` matches your domain
|
|
- Check that verification token was saved to database
|
|
- Ensure response ID is correct
|
|
- Check application logs for errors
|
|
|
|
### Representative Dropdown Not Populating
|
|
- Check browser console for JavaScript errors
|
|
- Verify `api-client.js` is loaded in HTML
|
|
- Ensure API endpoint `/api/representatives/by-postal/:code` is accessible
|
|
- Check network tab for API response
|
|
|
|
## Rollback Plan
|
|
|
|
If you need to rollback this feature:
|
|
|
|
1. **Frontend Only Rollback**:
|
|
```bash
|
|
# Restore old files
|
|
git checkout HEAD~1 -- app/public/response-wall.html
|
|
git checkout HEAD~1 -- app/public/js/response-wall.js
|
|
git checkout HEAD~1 -- app/public/css/response-wall.css
|
|
```
|
|
|
|
2. **Full Rollback** (including backend):
|
|
```bash
|
|
# Restore all files
|
|
git checkout HEAD~1
|
|
docker compose build
|
|
docker compose up -d
|
|
```
|
|
|
|
3. **Database Cleanup** (optional):
|
|
- The new columns don't hurt anything if left in place
|
|
- You can manually remove them through NocoDB UI if desired
|
|
|
|
## Support
|
|
|
|
For issues or questions:
|
|
- Check application logs: `docker logs influence-app -f`
|
|
- Review `RESPONSE_WALL_UPDATES.md` for implementation details
|
|
- Check `files-explainer.md` for file structure information
|
|
|
|
## Next Steps
|
|
|
|
### Recommended Enhancements:
|
|
1. **Token Expiration**: Implement 30-day expiration for verification tokens
|
|
2. **Email Notifications**: Notify submitter when representative verifies
|
|
3. **Analytics Dashboard**: Track verification rates and response authenticity
|
|
4. **Bulk Verification**: Allow representatives to verify multiple responses at once
|
|
5. **Representative Dashboard**: Create dedicated portal for representatives to manage responses
|
|
|
|
### Future Features:
|
|
1. Support for other provinces beyond Alberta
|
|
2. SMS verification option
|
|
3. Representative accounts for ongoing engagement
|
|
4. Response comment system for public discussion
|
|
5. Export verified responses for accountability reporting
|