# Quick Reference: Response Verification Feature

## Quick Start

### For Developers
```bash
# 1. Update database
./scripts/build-nocodb.sh

# 2. Update .env
echo 'APP_NAME="BNKops Influence"' >> .env
echo 'BASE_URL=http://localhost:3333' >> .env

# 3. Rebuild
docker compose build && docker compose up -d

# 4. Test at
open http://localhost:3333/response-wall.html?campaign=your-campaign-slug
```

### For Testers
1. Navigate to any campaign Response Wall
2. Click "Share a Response"
3. Enter postal code: **T5K 2J1**
4. Click Search
5. Select a representative
6. Fill in response details
7. Check "Send verification request"
8. Submit

## File Locations

### Frontend
- `app/public/response-wall.html` - Main page
- `app/public/js/response-wall.js` - Logic
- `app/public/css/response-wall.css` - Styles

### Backend
- `app/controllers/responses.js` - Main controller
- `app/services/email.js` - Email service
- `app/templates/email/response-verification.*` - Email templates
- `app/routes/api.js` - Route definitions

### Database
- `scripts/build-nocodb.sh` - Schema definitions

### Documentation
- `IMPLEMENTATION_SUMMARY.md` - Full implementation details
- `DEPLOYMENT_GUIDE.md` - Deployment instructions
- `RESPONSE_WALL_UPDATES.md` - Feature documentation

## Key Functions

### Frontend (`response-wall.js`)
```javascript
handlePostalLookup()              // Searches by postal code
displayRepresentativeOptions()    // Shows rep dropdown
handleRepresentativeSelect()      // Auto-fills form
handleSubmitResponse()            // Submits with verification
```

### Backend (`responses.js`)
```javascript
submitResponse()     // Handles submission + verification
verifyResponse()     // Verifies via token
reportResponse()     // Reports as invalid
```

### Email Service (`email.js`)
```javascript
sendResponseVerification()  // Sends verification email
```

## API Endpoints

```
POST   /api/campaigns/:slug/responses          # Submit response
GET    /api/responses/:id/verify/:token        # Verify response
GET    /api/responses/:id/report/:token        # Report response
```

## Database Fields

**Table:** influence_representative_responses

| Field | Type | Purpose |
|-------|------|---------|
| representative_email | Email | Rep's email address |
| verification_token | Text | 32-byte random hex |
| verification_sent_at | DateTime | When email sent |
| verified_at | DateTime | When verified |
| verified_by | Text | Who verified |

## Environment Variables

```bash
APP_NAME="BNKops Influence"
BASE_URL=https://yourdomain.com
SMTP_HOST=smtp.provider.com
SMTP_PORT=587
SMTP_USER=email@domain.com
SMTP_PASS=password
SMTP_FROM_EMAIL=sender@domain.com
SMTP_FROM_NAME="Campaign Name"
```

## Testing Checklist

**Frontend:**
- [ ] Postal search works
- [ ] Rep dropdown populates
- [ ] Form auto-fills
- [ ] Checkbox enables/disables
- [ ] Submission succeeds

**Backend:**
- [ ] Token generated
- [ ] Email sent
- [ ] Verification works
- [ ] Report works
- [ ] HTML pages display

**Security:**
- [ ] Invalid tokens rejected
- [ ] Duplicate verification handled
- [ ] XSS prevention working

## Common Issues

### Email Not Sending
- Check SMTP settings in `.env`
- Test at `/email-test.html`
- Check logs: `docker logs influence-app -f`

### Postal Search Fails
- Verify Represent API accessible
- Check postal code format (T5K 2J1)
- Check browser console for errors

### Verification Link Fails
- Verify BASE_URL is correct
- Check token in database
- Check application logs

## URLs for Testing

```
# Main page
http://localhost:3333/response-wall.html?campaign=test-campaign

# Verification (replace ID and TOKEN)
http://localhost:3333/api/responses/123/verify/abc123...

# Report (replace ID and TOKEN)
http://localhost:3333/api/responses/123/report/abc123...
```

## Support

- **Logs:** `docker logs influence-app -f`
- **Docs:** See markdown files in project root
- **Email Test:** http://localhost:3333/email-test.html

## Quick Troubleshooting

| Problem | Solution |
|---------|----------|
| No representatives found | Check postal code format (T5K 2J1) |
| Email not received | Check SMTP settings, spam folder |
| Verification fails | Check BASE_URL, token validity |
| Checkbox disabled | Representative has no email |
| Form won't submit | Check required fields, validation |

---

**Last Updated:** October 16, 2025
**Version:** 1.0.0