Virtnet.bond/extensions/Others/SocialBase/docs/MESSAGE_REPORTING.md

# Message Reporting System

The SocialBase messaging system includes comprehensive message reporting functionality with automatic notifications.

## Table of Contents
- [How to Report a Message](#how-to-report-a-message)
- [Notification System](#notification-system)
- [Admin Workflow](#admin-workflow)
- [Programmatic Usage](#programmatic-usage)

## How to Report a Message

### Using the Livewire Component

In your Blade views, you can add a report button for any message:

```blade
<livewire:socialbase.report-message :messageId="$message->id" />
```

This will render a "Report" button that opens a modal with:
- Reason selection (spam, harassment, inappropriate, scam, other)
- Optional description field (500 chars max)
- Submit and cancel buttons

### Using PHP/Helper Method

```php
use Paymenter\Extensions\Others\SocialBase\Helpers\MessagingHelper;

// Report a message
MessagingHelper::reportMessage(
    $messageId,           // ID of the message to report
    $reportedByUserId,    // ID of the user reporting
    'spam',               // Reason: spam, harassment, inappropriate, scam, other
    'Optional description' // Additional details (optional)
);
```

## Notification System

### When a User Reports a Message

The reporter automatically receives a **confirmation message**:

**Subject:** "Report Received - We're Reviewing It"

**Content:**
```
Thank you for reporting a message. We take all reports seriously and our moderation team will review it shortly.

Report Details:
- Reason: [Spam/Harassment/etc]
- Report ID: #123

You will receive another message once our team has reviewed your report.
```

**Message Type:** `message_report_confirmation`

### When Admin Reviews the Report

#### If Report is Dismissed (No Action)

**Subject:** "Report Update: No Action Taken"

**Content:**
```
Thank you for your report (ID: #123).

After review, our moderation team has determined that the reported message does not violate our community guidelines. The message will remain visible.

Report Reason: [Reason]

If you believe this decision was made in error, please contact our support team.
```

#### If Action is Taken

**Subject:** "Report Update: Action Taken"

**Content:**
```
Thank you for your report (ID: #123).

Our moderation team has reviewed your report and taken action.

Action Taken: [The reported message has been removed/flagged/etc]
Report Reason: [Reason]

We appreciate your help in keeping our community safe and respectful.
```

**Message Type:** `message_report_decision`

## Admin Workflow

### 1. Viewing Reports

Navigate to **Admin → Messaging → Message Reports**

The admin panel shows:
- Reporter information
- Reported message content
- Message sender
- Report reason and description
- Current status (pending/reviewed/dismissed)

### 2. Reviewing a Report

1. Click the edit icon on a report
2. Review the report details
3. Check the message content and context
4. Update the **Status** field:
   - **Pending** - Not yet reviewed
   - **Reviewed** - Action taken
   - **Dismissed** - No action needed
5. Optionally moderate the message itself (flag/delete/approve)
6. Click **Save**

### 3. Automatic Notifications

When you save a report with status changed from "pending":
- The reporter is automatically notified
- Notification includes action taken (based on message moderation status)
- Event `socialbase.message.report_reviewed` is dispatched

## Programmatic Usage

### Listening for Report Events

#### When Message is Reported

```php
Event::listen('socialbase.message.reported', function ($report) {
    // $report->id - Report ID
    // $report->message_id - Reported message ID
    // $report->reported_by - Reporter user ID
    // $report->reason - Report reason
    // $report->description - Additional details
});
```

#### When Report is Reviewed

```php
Event::listen('socialbase.message.report_reviewed', function ($report, $decision) {
    // $report - MessageReport model
    // $decision - 'reviewed' or 'dismissed'
    
    // Access related data
    $message = $report->message;
    $reporter = $report->reporter;
    $reviewer = $report->reviewer;
});
```

### Auto-Flagging

Messages with **3 or more pending reports** are automatically flagged for review:

```php
// This happens automatically in MessagingService::reportMessage()
$pendingReports = MessageReport::where('message_id', $messageId)
    ->where('status', 'pending')
    ->count();

if ($pendingReports >= 3) {
    $message->update(['moderation_status' => 'flagged']);
}
```

## Report Reasons

Available report reasons:

| Reason | Description |
|--------|-------------|
| `spam` | Unsolicited or repetitive messages |
| `harassment` | Abusive or threatening content |
| `inappropriate` | Content that violates guidelines |
| `scam` | Fraudulent or phishing attempts |
| `other` | Other violations not listed |

## Database Schema

### ext_social_message_reports

| Column | Type | Description |
|--------|------|-------------|
| id | bigint | Primary key |
| message_id | bigint | FK to ext_social_messages |
| reported_by | bigint | FK to users |
| reason | string | Report reason enum |
| description | text | Additional details (optional) |
| status | string | pending/reviewed/dismissed |
| reviewed_by | bigint | FK to users (nullable) |
| reviewed_at | timestamp | When reviewed (nullable) |
| created_at | timestamp | When reported |
| updated_at | timestamp | Last modified |

## Best Practices

### For Developers

1. **Always use the helper method** instead of creating reports directly
2. **Don't send duplicate reports** - check if user already reported before allowing
3. **Include context** in description field when possible
4. **Respect privacy** - only show necessary information to reporters

### For Administrators

1. **Review reports promptly** to maintain user trust
2. **Be consistent** with moderation decisions
3. **Document patterns** - use moderation notes
4. **Communicate clearly** - notifications explain your decisions
5. **Monitor auto-flagged messages** - 3+ reports deserve attention

## Security Considerations

- Users can only report messages in conversations they participate in
- System messages cannot be reported
- Reports are visible only to administrators with proper permissions
- Reporter identity is kept confidential from message sender
- All reports are logged for audit purposes

## Permissions

Required permissions for report management:

- `socialbase.reports.view` - View message reports
- `socialbase.reports.review` - Update report status
- `socialbase.reports.delete` - Delete reports

Set these in Admin → Roles & Permissions → [Role] → Social Base section.

## Integration Example

### Adding Report Button to Custom UI

```blade
<div class="message">
    <div class="message-content">{{ $message->content }}</div>
    <div class="message-actions">
        <!-- Other actions -->
        @if(!$message->is_system && Auth::id() !== $message->sender_id)
            <livewire:socialbase.report-message :messageId="$message->id" />
        @endif
    </div>
</div>
```

### Custom Report Handler

```php
use Paymenter\Extensions\Others\SocialBase\Helpers\MessagingHelper;

class CustomReportHandler
{
    public function reportSpam($messageId, $userId)
    {
        // Add custom logic before reporting
        $this->logReport($userId, $messageId);
        
        // Report the message
        MessagingHelper::reportMessage(
            $messageId,
            $userId,
            'spam',
            'Automated spam detection'
        );
        
        // Add custom logic after reporting
        $this->notifyModerators($messageId);
    }
}
```

## Troubleshooting

### Reports Not Sending Notifications

1. Check that `socialbase.message.reported` event is dispatched
2. Verify MessagingHelper is available
3. Check logs for error messages
4. Ensure user has valid email/account

### Auto-Flagging Not Working

1. Verify the reportMessage() method is being used
2. Check if message already flagged
3. Ensure at least 3 pending reports exist
4. Review logs for any errors

### Report Modal Not Showing

1. Ensure Livewire is properly loaded
2. Check JavaScript console for errors
3. Verify component is registered
4. Clear cache: `php artisan optimize:clear`

---

For more information about the messaging system, see [MESSAGING_SYSTEM.md](MESSAGING_SYSTEM.md)