# Admin API Documentation

## Statistics Endpoints

### Admin Statistics Overview
**GET** `/api/v1/admin/statistics/overview`

Complete dashboard statistics including service orders, urgent orders, financial data, user metrics, and team performance.

**Response Structure:**
```json
{
  "status": "success",
  "message": "Data retrieved successfully",
  "data": {
    "service_orders": {
      "totals": {
        "all": 1250,
        "pending": 45,
        "pending_negotiation": 12,
        "active": 78,
        "provider_finished": 23,
        "pending_admin_review": 8,
        "completed": 980,
        "cancelled": 85,
        "rejected": 19
      },
      "rates": {
        "completion_rate": 78.4,
        "cancellation_rate": 8.3
      },
      "golden_guarantee": {
        "total_filed": 25,
        "pending_review": 3,
        "approved": 15,
        "rejected": 7
      },
      "revisions": {
        "orders_with_revision": 156,
        "avg_revisions": 1.8
      },
      "negotiations": {
        "orders_with_negotiation": 89,
        "avg_negotiation_difference": 75.50
      },
      "volume_chart": [
        {
          "period": "2026-08",
          "in_progress": 45,
          "completed": 89,
          "cancelled": 12
        },
        {
          "period": "2026-09",
          "in_progress": 52,
          "completed": 94,
          "cancelled": 8
        }
      ]
    },
    "urgent_orders": {
      "totals": {
        "all": 345,
        "searching_for_provider": 12,
        "accepted": 25,
        "completed": 287,
        "cancelled": 21
      },
      "rates": {
        "completion_rate": 83.2,
        "cancellation_rate": 6.1
      },
      "revenue": {
        "total_gross": 125000.00,
        "total_vat": 18750.00,
        "this_month": 15000.00
      }
    },
    "financial_overview": {
      "total_revenue": 2450000.00,
      "total_vat": 367500.00,
      "app_fees": 245000.00,
      "provider_earnings": 1837500.00
    },
    "users": {
      "total_clients": 5680,
      "total_providers": 1250,
      "active_this_month": {
        "clients": 890,
        "providers": 345
      },
      "growth_chart": [
        {
          "period": "2026-08",
          "clients": 78,
          "providers": 23
        },
        {
          "period": "2026-09",
          "clients": 95,
          "providers": 28
        }
      ]
    },
    "team_performance": {
      "total_teams": 45,
      "active_teams": 38,
      "team_leaders": [
        {
          "id": 123,
          "name": "Ahmed Al-Rashid",
          "teams_led": "Legal Experts, Contract Specialists",
          "teams_count": 2,
          "completed_orders": 156,
          "revenue": 78000.00
        }
      ]
    }
  }
}
```

**Response includes:**
- Service order statistics with all statuses (pending, pending_negotiation, active, provider_finished, pending_admin_review, completed, cancelled, rejected)
- Golden Guarantee statistics (total filed, pending review, approved, rejected)
- Negotiation statistics (orders with negotiations, average price difference)
- Urgent order statistics
- Financial overview with earnings breakdown
- User growth and provider performance metrics
- Team performance and leadership statistics

### Service Order Statistics
**GET** `/api/v1/admin/statistics/service-orders`

Detailed service order analytics with volume charts and completion rates.

**Response Structure:**
```json
{
  "status": "success",
  "message": "Data retrieved successfully",
  "data": {
    "totals": {
      "all": 1250,
      "pending": 45,
      "pending_negotiation": 12,
      "active": 78,
      "provider_finished": 23,
      "pending_admin_review": 8,
      "completed": 980,
      "cancelled": 85,
      "rejected": 19
    },
    "rates": {
      "completion_rate": 78.4,
      "cancellation_rate": 8.3
    },
    "golden_guarantee": {
      "total_filed": 25,
      "pending_review": 3,
      "approved": 15,
      "rejected": 7
    },
    "revisions": {
      "orders_with_revision": 156,
      "avg_revisions": 1.8
    },
    "negotiations": {
      "orders_with_negotiation": 89,
      "avg_negotiation_difference": 75.50
    },
    "volume_chart": [
      {
        "period": "2026-01",
        "in_progress": 45,
        "completed": 89,
        "cancelled": 12
      },
      {
        "period": "2026-02",
        "in_progress": 52,
        "completed": 94,
        "cancelled": 8
      }
    ]
  }
}
```

**Key Features:**
- Tracks all order statuses excluding pending_payment (removed as requested)
- Golden Guarantee tracking with admin review status
- Revision statistics and average revision counts
- 12-month volume charts showing order trends

## Order Management

### Order Types
Orders now include an `order_type` field that indicates whether the order is handled by:
- `individual` - Single provider handling the order
- `team` - Team-based order with multiple members

### Team-Based Orders
When `order_type` is "team":
- The team leader manages the entire order process
- Team data is included in order responses
- All team members can collaborate but the leader has full control
- Order assignment and communication flows through the team leader

### Package Discounts
Orders now include package discount information:
- `package_discount_amount` - Discount applied from active package subscription
- `package_discount_percentage` - Percentage discount from package

### Broker Discounts
Orders also include broker discount information when applicable:
- `broker_discount_amount` - Discount applied through broker referral
- `broker_discount_percentage` - Percentage discount from broker program
- `broker_id` - ID of the referring broker (if applicable)

## Package Management

### Package CRUD Operations
**Endpoints:**
- GET `/api/v1/admin/packages`
- POST `/api/v1/admin/packages`
- GET `/api/v1/admin/packages/{id}`
- PUT `/api/v1/admin/packages/{id}`
- DELETE `/api/v1/admin/packages/{id}`

### Package Discount Fields (Updated Naming)
**English Fields:**
- `admin_commission_rate` (Previously: admin_discount)
- `provider_commission_rate` (Previously: provider_discount)

**Arabic Translation:**
- نسبة الخصم التي تتحملها الإدارة (Admin commission rate)
- نسبة الخصم التي يتحملها المحامي (Provider commission rate)

These fields represent the commission structure where:
- Admin commission rate: Percentage retained by the platform
- Provider commission rate: Percentage earned by the provider

## Order Data Structure

### Individual Orders
```json
{
  "id": 123,
  "order_number": "ORD-2026-001234",
  "reference_id": "REF-ABC123",
  "order_type": "individual",
  "provider_data": {
    "id": 456,
    "full_name": "Provider Name",
    "avatar": "https://...",
    "type": "individual"
  },
  "team_data": null,
  "package_discount_amount": 50.00,
  "package_discount_percentage": 10.0,
  "broker_discount_amount": 25.00,
  "broker_discount_percentage": 5.0,
  "broker_id": 789
}
```

### Team Orders
```json
{
  "id": 124,
  "order_number": "ORD-2026-001235",
  "reference_id": "REF-XYZ456",
  "order_type": "team",
  "provider_data": {
    "id": 789,
    "full_name": "Team Leader Name",
    "avatar": "https://...",
    "type": "team_leader"
  },
  "team_data": {
    "id": 12,
    "name": "Legal Team Alpha",
    "members_count": 5,
    "leader_id": 789
  },
  "package_discount_amount": 0.00,
  "package_discount_percentage": 0.0,
  "broker_discount_amount": 0.00,
  "broker_discount_percentage": 0.0,
  "broker_id": null
}
```

## Team Management

### Team Statistics
Admin can view comprehensive team performance including:
- Team completion rates
- Individual vs team order distribution
- Team leader performance metrics
- Member collaboration statistics

### Team Order Processing
- Team orders are assigned to the team leader
- Leader coordinates with team members
- All communication flows through the leader
- Payment and completion handled by the leader
- Team performance affects overall statistics

## Provider Review Management

### Review Endpoints
**GET** `/api/v1/admin/provider-reviews` - List all provider and team reviews
**GET** `/api/v1/admin/provider-reviews/{id}` - Show detailed review
**DELETE** `/api/v1/admin/provider-reviews/{id}` - Delete review (admin moderation)

### Available Filters
The review listing endpoint supports focused filters for efficient review management:

**Filter Parameters:**
- `review_type` - Filter by review type:
  - `team` - Reviews for team-based orders
  - `individual` - Reviews for individual provider orders
- `order_category` - Filter by order category:
  - `service_order` - Reviews from regular service orders
  - `urgent_order` - Reviews from urgent/emergency orders
- `rating` - Filter by star rating (1-5)
- `order_number` - Search reviews by order number (partial match)

**Example Requests:**
```
GET /api/v1/admin/provider-reviews?review_type=team
GET /api/v1/admin/provider-reviews?order_category=urgent_order
GET /api/v1/admin/provider-reviews?rating=5
GET /api/v1/admin/provider-reviews?order_number=NK-S0123
GET /api/v1/admin/provider-reviews?review_type=individual&order_category=service_order
GET /api/v1/admin/provider-reviews?order_category=urgent_order&rating=1
```

### Review Data Structure
Reviews now include comprehensive order information for better tracking:

```json
{
  "id": 123,
  "rating": 5,
  "comment": "Excellent service provided",
  "order_data": {
    "id": 456,
    "order_number": "NK-S0123#",
    "order_category": "service_order", // or "urgent_order"
    "order_type": "team", // or "individual"
    "reference_id": "REF-ABC123",
    "type": "App\\Models\\ServiceOrder",
    "total_price": 500.00,
    "status": "completed"
  },
  "provider_data": {
    "id": 789,
    "full_name": "Provider Name",
    "avatar": "https://..."
  },
  "team_data": null, // or team info for team orders
  "client_data": {
    "id": 321,
    "full_name": "Client Name",
    "avatar": "https://..."
  },
  "created_at": "2026-09-15 10:30"
}
```

### Review Types
- **Individual Reviews**: Reviews for orders handled by individual providers
- **Team Reviews**: Reviews for orders handled by teams (provider_data will be null, team_data populated)

### Review Moderation
Admins can delete inappropriate reviews or reviews that violate platform policies through the delete endpoint.

## Financial Tracking

### Enhanced Financial Reports
- Package discount impact on revenue
- Team vs individual provider earnings
- Commission structure tracking (admin vs provider rates)
- Golden Guarantee financial impact
- Negotiation price difference analytics

## Data Integrity

### Order Classification
All orders are properly classified as either individual or team-based, ensuring:
- Accurate performance tracking
- Proper commission calculations
- Clear responsibility assignment
- Comprehensive team analytics

### Package Integration
Package discounts are automatically applied and tracked:
- Real-time discount calculations
- Historical discount impact analysis
- Provider subscription status integration
- Commission rate adjustments based on package tiers