# 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