# Response Wall - Usage Guide

## Overview
The Response Wall is now fully implemented! It allows campaign participants to share and vote on responses they receive from elected representatives.

## How to Access the Response Wall

The Response Wall requires a campaign slug to function. You must access it with a URL parameter:

### URL Format
```
http://localhost:3333/response-wall.html?campaign=YOUR-CAMPAIGN-SLUG
```

### Example URLs
```
http://localhost:3333/response-wall.html?campaign=climate-action
http://localhost:3333/response-wall.html?campaign=healthcare-reform
http://localhost:3333/response-wall.html?campaign=education-funding
```

## Setup Instructions

### 1. Create a Campaign First
Before using the Response Wall, you need to have an active campaign:

1. Go to http://localhost:3333/admin.html
2. Create a new campaign with a slug (e.g., "climate-action")
3. Note the campaign slug you created

### 2. Access the Response Wall
Use the campaign slug in the URL:
```
http://localhost:3333/response-wall.html?campaign=YOUR-SLUG-HERE
```

## Features

### For Public Users
- **View Responses**: See all approved responses from representatives
- **Filter & Sort**: 
  - Filter by government level (Federal, Provincial, Municipal, School Board)
  - Sort by Most Recent, Most Upvoted, or Verified First
- **Submit Responses**: Share responses you've received from representatives
  - Required: Representative name, level, response type, response text
  - Optional: Representative title, your comment, screenshot, your name/email
  - Can post anonymously
- **Upvote Responses**: Show appreciation for helpful responses
- **View Statistics**: See total responses, verified count, and total upvotes

### For Administrators
Access via the admin panel at http://localhost:3333/admin.html:

1. Navigate to the "Response Moderation" tab
2. Filter by status: Pending, Approved, Rejected, or All
3. Moderate submissions:
   - **Approve**: Make response visible to public
   - **Reject**: Hide inappropriate responses
   - **Verify**: Add verification badge to authentic responses
   - **Edit**: Modify response content if needed
   - **Delete**: Remove responses permanently

## Moderation Workflow

1. User submits a response (status: "pending")
2. Admin reviews in admin panel → "Response Moderation" tab
3. Admin approves → Response appears on public Response Wall
4. Admin can mark as "verified" for authenticity badge
5. Public can upvote helpful responses

## Integration with Campaigns

### Link from Campaign Pages
You can add links to the Response Wall from your campaign pages:

```html
<a href="/response-wall.html?campaign=YOUR-SLUG">
  View Community Responses
</a>
```

### Embed in Campaign Flow
Consider adding a "Share Your Response" call-to-action after users send emails to representatives.

## Testing the Feature

### 1. Create Test Campaign
```bash
# Via admin panel or API
POST /api/admin/campaigns
{
  "title": "Test Campaign",
  "slug": "test-campaign",
  "email_subject": "Test",
  "email_body": "Test body"
}
```

### 2. Submit Test Response
Navigate to:
```
http://localhost:3333/response-wall.html?campaign=test-campaign
```

Click "Share a Response" and fill out the form.

### 3. Moderate Response
1. Go to admin panel: http://localhost:3333/admin.html
2. Click "Response Moderation" tab
3. Change filter to "Pending"
4. Approve the test response

### 4. View Public Response
Refresh the Response Wall page to see your approved response.

## API Endpoints

### Public Endpoints
- `GET /api/campaigns/:slug/responses` - Get approved responses
- `GET /api/campaigns/:slug/response-stats` - Get statistics
- `POST /api/campaigns/:slug/responses` - Submit new response
- `POST /api/responses/:id/upvote` - Upvote a response
- `DELETE /api/responses/:id/upvote` - Remove upvote

### Admin Endpoints (require authentication)
- `GET /api/admin/responses` - Get all responses (any status)
- `PATCH /api/admin/responses/:id/status` - Update status
- `PATCH /api/admin/responses/:id` - Update response details
- `DELETE /api/admin/responses/:id` - Delete response

## Database Tables

The feature uses two new NocoDB tables:

### `influence_representative_responses`
Stores submitted responses with fields:
- Representative details (name, title, level)
- Response content (type, text, screenshot)
- Submitter info (name, email, anonymous flag)
- Moderation (status, verified flag)
- Engagement (upvote count)

### `influence_response_upvotes`
Tracks upvotes with fields:
- Response ID
- User ID / Email (if authenticated)
- IP address (for anonymous upvotes)

## Troubleshooting

### "No campaign specified" Error
**Problem**: Accessing `/response-wall.html` without campaign parameter

**Solution**: Add `?campaign=YOUR-SLUG` to the URL

### No Responses Showing
**Problem**: Responses exist but not visible

**Possible Causes**:
1. Responses are in "pending" status (not yet approved by admin)
2. Wrong campaign slug in URL
3. Responses filtered out by current filter settings

**Solution**: 
- Check admin panel → Response Moderation tab
- Verify campaign slug matches
- Clear filters (set to "All Levels")

### Button Not Working
**Problem**: "Share a Response" button doesn't open modal

**Solution**: 
- Check browser console for JavaScript errors
- Verify you're accessing with a valid campaign slug
- Hard refresh the page (Ctrl+F5)

### Images Not Uploading
**Problem**: Screenshot upload fails

**Possible Causes**:
1. File too large (max 5MB)
2. Wrong file type (only JPEG/PNG/GIF/WebP allowed)
3. Upload directory permissions

**Solution**:
- Resize image to under 5MB
- Convert to supported format
- Check `/app/public/uploads/responses/` directory exists with write permissions

## Next Steps

1. **Run Database Setup**: `./scripts/build-nocodb.sh` (if not already done)
2. **Restart Application**: `docker compose down && docker compose up --build`
3. **Create Test Campaign**: Via admin panel
4. **Test Response Submission**: Submit and moderate a test response
5. **Integrate with Campaigns**: Add Response Wall links to your campaign pages

## Notes

- All submissions require admin moderation (status: "pending" → "approved")
- Anonymous upvotes are tracked by IP address to prevent duplicates
- Authenticated upvotes are tracked by user ID
- Screenshots are stored in `/app/public/uploads/responses/`
- The feature respects NocoDB best practices (column titles, system fields, etc.)