Add all files
This commit is contained in:
root
305
extensions/Others/SocialBase/docs/MESSAGE_REPORTING.md
Normal file
305
extensions/Others/SocialBase/docs/MESSAGE_REPORTING.md
Normal file
@@ -0,0 +1,305 @@
|
||||
# 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)
|
||||
|
||||
Reference in New Issue
Block a user