# Provider Dashboard — Service Order Guide

---

## Pricing — What the Provider Sees

### Fields Returned in Service Order Resource

| Field | Description | Show to Provider As |
|---|---|---|
| `service_price` | The price you set for this service | "Service Price" |
| `app_fee_percentage` | Service fee % captured at order creation | "Service Fee %" |
| `app_fee_amount` | Service fee SAR amount deducted from your price | "Service Fee" |
| `net_provider_earnings` | **Your actual earnings** = service_price − app_fee_amount | "You Will Receive" — show prominently |
| `total_price` | Total paid by client (includes VAT) | ❌ Hide from provider |
| `vat_amount` | VAT paid by client | ❌ Hide from provider |

> Always refer to `app_fee_percentage` / `app_fee_amount` as **"Service Fee"** in the provider-facing UI — never "app fee" or "platform fee".

### Recommended UI Display on Order

```
Service Price:          500 SAR
Service Fee (10%):   −   50 SAR
────────────────────────────────
You Will Receive:       450 SAR
```

---

## Service Fee — Within the Price You Set

The service fee is **deducted from the price you set** — it is not added on top by the client.

```
net_provider_earnings = service_price − app_fee_amount
```

### Pricing Hint (show when provider sets/edits their service price)

When the provider enters a price for their service, show this hint **inline** next to the price input:

> **"The price you enter already includes the service fee of X%. Your actual earnings will be your price minus X%."**
>
> Example: If you set **500 SAR** and the service fee is **10%**, you will receive **450 SAR**.

Use `app_fee_percentage` from `services_data` in the provider profile to populate `X%` dynamically.

> Both `app_fee_percentage` and `app_fee_amount` on an order are **captured at order creation time** — they never change after the order is placed, even if the platform rate changes later.

> For **negotiated orders**: these fields are `null` until the client accepts and pays. At payment time, the final agreed price is used to calculate and store them.

---

## Client & Parties Sensitive Data

By default, **sensitive contact and identity data is hidden** from the provider. Admin must explicitly reveal it.

### Always Visible
- `client_data.full_name`
- `parties_data[*].full_name`
- `parties_data[*].has_confirmed`
- `parties_data[*].confirmed_at`

### Hidden Until Admin Reveals (`show_client_contact = true`)
- `client_data.phone_code` → `null`
- `client_data.phone` → `null`
- `parties_data[*].national_id` → `null`
- `parties_data[*].national_id_type` → `null`
- `parties_data[*].phone_code` → `null`
- `parties_data[*].phone` → `null`

---

## Parties Data (Integrated Contract Orders)

```json
"parties_data": [
    {
        "id": 12,
        "full_name": "Ahmed Ali",
        "national_id": null,
        "national_id_type": null,
        "phone_code": null,
        "phone": null,
        "has_confirmed": false,
        "confirmed_at": null
    }
]
```

---

## Integrated Contract Order Flow (Provider Side)

```
1. Order arrives (status: pending)
   → Pricing shown: service_price, app_fee_amount, net_provider_earnings
   → Accept or reject

2. Order accepted (status: accepted → active)
   → Upload work files: POST /provider/orders/service/{id}/upload-work
   → At least ONE work file required before finishing

3. Mark as finished: POST /provider/orders/service/{id}/finish
   → status: provider_finished
   → All parties notified to confirm or request revision

4a. All parties confirm → status: completed → net_provider_earnings paid to you
4b. Any party requests revision → status: active (back to you)
    → re-upload and finish again

5. Max revisions reached → client can file Golden Guarantee → admin reviews
```

---

## Profile — Services Pricing

Provider profile `services_data` per-service fields:

```json
"services_data": [
    {
        "id": 1,
        "name": "Legal Consultation",
        "price": 500.00,
        "price_from": 200.00,
        "price_to": 1000.00,
        "app_fee_percentage": 10.00
    }
]
```

Use `app_fee_percentage` to drive the live hint shown to the provider when they set or update their service price.

---

## Profile Update — Editable Fields

Endpoint: `PUT /provider/profile` (all fields optional)

**Personal:** `full_name`, `national_id_type`, `national_id`, `gender`, `nationality`

**Professional:** `provider_type_id`, `category_id`, `subcategory_id`, `services[]`, `professional_license_number`, `license_expiration_date`, `licensing_authority`, `degree_specialty`, `degree_grade`, `gpa_or_percentage`, `years_of_experience`, `specialty_experience_years`, `has_criminal_record`, `brief`

**Location:** `city_id`, `district_id`, `lat`, `lng`, `address`

**Documents (media IDs):** `national_id_doc`, `professional_license_doc`, `university_degree_doc`, `wages_certificate[]`, `criminal_record_certificate`, `other_licenses[]`

**Account / Media:** `locale`, `allow_notifications`, `is_available`, `can_perform_urgent_order`, `avatar`, `cv`, `intro_video`