# Admin API — Latest Updates

## Overview

This document covers the latest updates to the Admin API including settings management for social links and contact information, and order report filtering enhancements.

---

## Table of Contents

1. [Settings Management — Social Links & Contact](#settings-management--social-links--contact)
2. [Order Reports — Provider vs Client Filtering](#order-reports--provider-vs-client-filtering)

---

## 1. Settings Management — Social Links & Contact

### Overview

Admins can now manage **social media links** and **contact information** that will be displayed in all provider and client profile responses.

### New Settings Keys Added

#### Contact Settings

| Key | Type | Group | Nullable | Default | Description |
|-----|------|-------|----------|---------|-------------|
| `phone` | `phone` | `system` | ✅ Yes | `null` | Main company phone number |
| `whatsapp` | `phone` | `social_media` | ✅ Yes | `null` | WhatsApp contact number |

#### Social Media Settings

| Key | Type | Group | Nullable | Default | Description |
|-----|------|-------|----------|---------|-------------|
| `facebook` | `url` | `social_media` | ✅ Yes | `null` | Facebook page URL |
| `twitter` | `url` | `social_media` | ✅ Yes | `null` | Twitter/X profile URL |
| `instagram` | `url` | `social_media` | ✅ Yes | `null` | Instagram profile URL |
| `snapchat` | `url` | `social_media` | ✅ Yes | `null` | Snapchat profile URL |
| `tiktok` | `url` | `social_media` | ✅ Yes | `null` | TikTok profile URL |
| `linkedin` | `url` | `social_media` | ✅ Yes | `null` | LinkedIn company/profile URL |
| `youtube` | `url` | `social_media` | ✅ Yes | `null` | YouTube channel URL |

### Important Notes

⚠️ **All settings are nullable**
- Values can be set to `null` to remove them
- Frontend applications must check for `null` values before displaying
- URLs must include protocol (`https://` or `http://`)
- Phone numbers must include country code (e.g., `+966500000000`)

### API Endpoints

#### Get All Settings

```http
GET /api/dashboard/admin/settings
Authorization: Bearer {admin_token}
```

**Response:**
```json
{
    "status": "success",
    "message": "Data retrieved successfully",
    "data": [
        {
            "key": "phone",
            "value": "+966500000000",
            "group": "system",
            "type": "phone",
            "label": "Phone",
            "is_public": false
        },
        {
            "key": "facebook",
            "value": "https://facebook.com/company",
            "group": "social_media",
            "type": "url",
            "label": "Facebook",
            "is_public": false
        }
    ]
}
```

#### Get Settings by Group

```http
GET /api/dashboard/admin/settings?group=social_media
Authorization: Bearer {admin_token}
```

**Response:**
```json
{
    "status": "success",
    "message": "Data retrieved successfully",
    "data": [
        {
            "key": "whatsapp",
            "value": "+966500000000",
            "group": "social_media",
            "type": "phone",
            "label": "WhatsApp"
        },
        {
            "key": "facebook",
            "value": "https://facebook.com/company",
            "group": "social_media",
            "type": "url",
            "label": "Facebook"
        },
        {
            "key": "twitter",
            "value": null,
            "group": "social_media",
            "type": "url",
            "label": "Twitter"
        }
    ]
}
```

#### Update Settings

```http
POST /api/dashboard/admin/settings
Authorization: Bearer {admin_token}
Content-Type: application/json

{
    "phone": "+966500000000",
    "whatsapp": "+966501234567",
    "facebook": "https://facebook.com/company",
    "twitter": "https://twitter.com/company",
    "instagram": "https://instagram.com/company",
    "snapchat": null,
    "tiktok": null,
    "linkedin": "https://linkedin.com/company/company-name",
    "youtube": "https://youtube.com/@company"
}
```

**Response:**
```json
{
    "status": "success",
    "message": "Settings updated successfully",
    "data": null
}
```

### Validation Rules

#### Phone Numbers
- Format: Must include country code
- Example: `+966500000000`
- Validation: `nullable|string|max:20`
- Can be set to `null`

#### URLs
- Format: Must include protocol (`https://` or `http://`)
- Example: `https://facebook.com/company`
- Validation: `nullable|url|max:255`
- Can be set to `null`

### How Settings Appear in User Profiles

When providers or clients request their profile, these settings are automatically included:

```json
{
    "id": 123,
    "full_name": "Ahmed Mohamed",
    "email": "ahmed@example.com",
    
    "app_settings": {
        "contact": {
            "phone": "+966500000000",
            "whatsapp": "+966501234567"
        },
        "social_links": {
            "facebook": "https://facebook.com/company",
            "twitter": "https://twitter.com/company",
            "instagram": "https://instagram.com/company",
            "snapchat": null,
            "tiktok": null,
            "linkedin": "https://linkedin.com/company/company-name",
            "youtube": "https://youtube.com/@company"
        }
    }
}
```

### Admin UI Recommendations

#### Social Media Settings Section

**Suggested Layout:**
- Group all social media settings together
- Use URL input fields with validation
- Provide "Clear" button to set values to `null`
- Show placeholder examples (e.g., `https://facebook.com/yourpage`)
- Display active/inactive status indicators

**Example Structure:**
```
Social Media Links
├── Facebook: [https://facebook.com/company    ] [Clear]
├── Twitter:  [                                ] [Clear]
├── Instagram:[https://instagram.com/company   ] [Clear]
├── Snapchat: [                                ] [Clear]
├── TikTok:   [                                ] [Clear]
├── LinkedIn: [https://linkedin.com/company    ] [Clear]
└── YouTube:  [https://youtube.com/@company    ] [Clear]

Contact Information
├── Phone:    [+966] [500000000                ]
└── WhatsApp: [+966] [501234567                ]

[Save Changes]
```

#### Validation Tips

1. **Real-time URL validation** - Check format as admin types
2. **Protocol detection** - Auto-add `https://` if missing
3. **Visual feedback** - Green checkmark for valid, red X for invalid
4. **Country code selector** - Dropdown for phone numbers
5. **Preview** - Show how settings will appear in app

---

## 2. Order Reports — Provider vs Client Filtering

### Overview

The order reports system now supports filtering to differentiate between reports filed by **providers** and reports filed by **clients**.

### Filter Parameters

| Filter | Parameter | Values | Description |
|--------|-----------|--------|-------------|
| Reporter Type | `reporter_type` | `client` OR `provider` | Who filed the report (single value) |
| Status | `status` | `pending`, `reviewed`, `dismissed` | Report review status |
| Complaint Type | `complaint_type` | See enum values | Type of complaint |
| Order Category | `order_category` | `service_order` OR `urgent_order` | Type of order reported (single value) |
| Date Range | `date_from`, `date_to` | `YYYY-MM-DD` | Filter by submission date |
| Order Number | `order_number` | `string` | Search by specific order |
| Reporter ID | `reporter_id` | `integer` | Filter by specific reporter user ID |

### API Endpoints

#### Get All Order Reports

```http
GET /api/dashboard/admin/order-reports
Authorization: Bearer {admin_token}
```

#### Filter by Reporter Type

**Get provider reports only:**
```http
GET /api/dashboard/admin/order-reports?reporter_type=provider
Authorization: Bearer {admin_token}
```

**Get client reports only:**
```http
GET /api/dashboard/admin/order-reports?reporter_type=client
Authorization: Bearer {admin_token}
```

#### Combined Filters

**Get pending provider reports for service orders:**
```http
GET /api/dashboard/admin/order-reports?reporter_type=provider&status=pending&order_category=service_order
Authorization: Bearer {admin_token}
```

**Get all reports from last 7 days:**
```http
GET /api/dashboard/admin/order-reports?date_from=2024-01-01&date_to=2024-01-07
Authorization: Bearer {admin_token}
```

### Response Structure

```json
{
    "status": "success",
    "message": "Data retrieved successfully",
    "data": {
        "data": [
            {
                "id": 1,
                "reporter_type": "provider",
                "reporter_data": {
                    "id": 123,
                    "full_name": "Ahmed Mohamed",
                    "email": "ahmed@example.com"
                },
                "reportable_type": "ServiceOrder",
                "reportable_id": 456,
                "order_data": {
                    "order_number": "SO-123456",
                    "status": "in_progress",
                    "service_name": "Legal Consultation"
                },
                "title": "Client Requested Illegal Service",
                "message": "The client asked me to perform services outside the agreed scope...",
                "complaint_type": "scope_violation",
                "status": "pending",
                "admin_note": null,
                "reviewed_by": null,
                "reviewed_at": null,
                "created_at": "2024-01-15T10:30:00.000000Z"
            },
            {
                "id": 2,
                "reporter_type": "client",
                "reporter_data": {
                    "id": 789,
                    "full_name": "Sara Ali",
                    "email": "sara@example.com"
                },
                "reportable_type": "ServiceOrder",
                "reportable_id": 789,
                "order_data": {
                    "order_number": "SO-789012",
                    "status": "completed",
                    "service_name": "Accounting Services"
                },
                "title": "Poor Service Quality",
                "message": "The provider did not complete the work as promised...",
                "complaint_type": "service_quality",
                "status": "reviewed",
                "admin_note": "Contacted both parties, issue resolved",
                "reviewed_by": {
                    "id": 1,
                    "full_name": "Admin User"
                },
                "reviewed_at": "2024-01-16T14:20:00.000000Z",
                "created_at": "2024-01-15T16:45:00.000000Z"
            }
        ],
        "current_page": 1,
        "per_page": 15,
        "total": 2
    }
}
```

### Report Statuses

| Status | Description |
|--------|-------------|
| `pending` | Report submitted, awaiting admin review |
| `reviewed` | Admin reviewed and took action |
| `dismissed` | Admin reviewed and dismissed (no action needed) |

### Complaint Types

| Value | Description |
|-------|-------------|
| `inappropriate_behavior` | Inappropriate or unprofessional behavior |
| `payment_issue` | Payment-related problems |
| `service_quality` | Quality of service concerns |
| `incorrect_information` | Misleading or false information |
| `scope_violation` | Work outside agreed scope |
| `safety_concern` | Safety or security issues |
| `other` | Other issues |

### Review Report

```http
PATCH /api/dashboard/admin/order-reports/{report}/review
Authorization: Bearer {admin_token}
Content-Type: application/json

{
    "status": "reviewed",
    "admin_note": "Contacted both parties and resolved the issue. Provider will be more careful about scope clarification."
}
```

**Response:**
```json
{
    "status": "success",
    "message": "Report reviewed successfully.",
    "data": {
        "id": 1,
        "status": "reviewed",
        "admin_note": "Contacted both parties and resolved the issue...",
        "reviewed_by": {
            "id": 1,
            "full_name": "Admin User"
        },
        "reviewed_at": "2024-01-16T15:30:00.000000Z"
    }
}
```

### Admin Dashboard Recommendations

#### Reports List Page

**Filter UI:**
```
Order Reports
┌─────────────────────────────────────────────────────────┐
│ Filters:                                                │
│ Reporter Type: [All ▼] [Provider] [Client]            │
│ Status:        [All ▼] [Pending] [Reviewed] [Dismissed]│
│ Order Type:    [All ▼] [Service Order] [Urgent Order]  │
│ Date Range:    [From: ____] [To: ____]                 │
│ Search:        [Order number or reporter name ______]   │
│                                        [Apply Filters]  │
└─────────────────────────────────────────────────────────┘

Results (25 reports)
┌─────────────────────────────────────────────────────────┐
│ #1 | Provider Report | SO-123456 | Pending | Jan 15     │
│ Ahmed Mohamed → Scope Violation                         │
│ "Client requested services outside agreed scope..."     │
│                              [View] [Review] [Dismiss]  │
├─────────────────────────────────────────────────────────┤
│ #2 | Client Report   | SO-789012 | Reviewed | Jan 15   │
│ Sara Ali → Service Quality                              │
│ "Provider did not complete the work as promised..."     │
│                              [View Details]             │
└─────────────────────────────────────────────────────────┘
```

#### Report Detail View

```
Report #1 Details
┌─────────────────────────────────────────────────────────┐
│ Status: [Pending ▼]                                     │
│                                                         │
│ Reporter Information:                                   │
│ - Type: Provider                                        │
│ - Name: Ahmed Mohamed                                   │
│ - Email: ahmed@example.com                              │
│ - Phone: +966500000000                                  │
│                                                         │
│ Order Information:                                      │
│ - Order #: SO-123456                                    │
│ - Type: Service Order                                   │
│ - Service: Legal Consultation                           │
│ - Current Status: In Progress                           │
│ - [View Full Order]                                     │
│                                                         │
│ Report Details:                                         │
│ - Title: Client Requested Illegal Service               │
│ - Complaint Type: Scope Violation                       │
│ - Message:                                              │
│   "The client asked me to perform services outside      │
│   the agreed scope and threatened negative reviews..."  │
│ - Submitted: Jan 15, 2024 10:30 AM                      │
│                                                         │
│ Admin Actions:                                          │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Admin Note: _________________________________       │ │
│ │            _________________________________       │ │
│ └─────────────────────────────────────────────────────┘ │
│                                                         │
│ [Mark as Reviewed] [Dismiss] [Contact Reporter]        │
└─────────────────────────────────────────────────────────┘
```

#### Statistics Dashboard

Show report metrics:
- Total reports this month
- Provider reports vs Client reports breakdown
- Pending reports count (requires attention)
- Most common complaint types
- Average response time

---

## Summary

### ✅ What's New for Admins

1. **Settings Management:**
   - Social media links (7 platforms) configurable
   - Contact information (phone, whatsapp) configurable
   - All settings are nullable
   - Settings automatically appear in all user profile responses

2. **Order Report Filtering:**
   - Filter reports by `reporter_type` (provider or client)
   - Additional filters: status, complaint type, order category, date range
   - Differentiate between provider and client complaints
   - Review and add admin notes to reports

### ⚠️ Important Notes

- All social media and contact settings are **nullable**
- Frontend applications must handle `null` values properly
- URLs must include protocol for validation
- Phone numbers must include country code
- Report filters help identify patterns and prioritize reviews

---

## Related Documentation

- [SETTINGS_SYSTEM.md](./SETTINGS_SYSTEM.md) - Complete settings system
- [ADMIN_REVIEW_AND_REPORT_FILTERS_DOCUMENTATION.md](./ADMIN_REVIEW_AND_REPORT_FILTERS_DOCUMENTATION.md) - Report system details
- [admin.md](./admin.md) - Admin dashboard overview