SERVICE_PROFESSIONALS_API_QUICK_REF.md

# Service Professionals API - Quick Reference

## Overview
API for service professionals to view and update their own profile. Authentication via JWT token with staff_id. Admin operations (create/delete/list) are handled separately.

## Base URL
```
/service-professionals
```

## Authentication
All endpoints require JWT authentication with `partner_id` in the token payload (which contains the staff_id for service professionals).

**Header:**
```
Authorization: Bearer <jwt_token>
```

## Available Endpoints

### 1. Get My Profile
**GET** `/service-professionals/me`

Retrieves the authenticated service professional's profile based on staff_id from JWT token.

**Authentication:** Required (JWT with staff_id)

**Response:** `200 OK`
```json
{
  "staff_id": "550e8400-e29b-41d4-a716-446655440001",
  "staff_code": "SP001",
  "name": "Priya Sharma",
  "designation": "Senior Beautician",
  "role": "beautician",
  "phone": "+919876543210",
  "email": "priya.sharma@example.com",
  "status": "active",
  "category": "beauty",
  "skills": ["facial", "makeup", "hair_styling"],
  "working_hours": [...],
  "photo_url": "https://example.com/photo.jpg",
  "address": {
    "street": "123 Main St",
    "city": "Mumbai",
    "state": "Maharashtra",
    "postal_code": "400001",
    "country": "India"
  },
  "notes": "Specialist in bridal makeup",
  "is_deleted": false,
  "meta": {...}
}
```

---

### 2. Update My Profile
**PUT** `/service-professionals/me`

Updates the authenticated service professional's profile. Staff ID is extracted from JWT token.

**Authentication:** Required (JWT with staff_id)

**Supports updating:**
- Basic info (name, designation, role, phone, email)
- Status and category
- Skills and working hours
- Address (add new or change existing)
- Photo URL and notes

**Request Body (all fields optional):**
```json
{
  "email": "priya.new@example.com",
  "status": "on_leave",
  "address": {
    "street": "456 New Street",
    "city": "Delhi"
  },
  "notes": "Updated notes"
}
```

**Response:** `200 OK`
```json
{
  "staff_id": "550e8400-e29b-41d4-a716-446655440001",
  "staff_code": "SP001",
  "name": "Priya Sharma",
  "email": "priya.new@example.com",
  "status": "on_leave",
  "address": {
    "street": "456 New Street",
    "city": "Delhi",
    "state": "Maharashtra",
    "postal_code": "400001",
    "country": "India"
  },
  ...
}
```

---

## Admin-Only Operations

The following operations are restricted to admin users and are not available through this API:

- **Create Service Professional** - Handled by admin interface
- **Delete Service Professional** - Handled by admin interface
- **List Service Professionals** - Handled by admin interface

---

## Field Definitions

### Updatable Fields (PUT endpoint)
- `staff_code`: Unique staff code (1-20 chars)
- `name`: Full name (1-100 chars)
- `designation`: Job designation (1-100 chars)
- `role`: Role category (1-50 chars)
- `phone`: Contact phone (10-20 chars, unique)
- `email`: Email address (valid email format)
- `status`: Status
- `category`: Service category
- `skills`: Array of skill strings
- `working_hours`: Array of schedule objects
- `photo_url`: Profile photo URL
- `address`: Address object with street, city, state, postal_code, country
- `notes`: Additional notes (max 500 chars)

### Valid Status Values
- `active`
- `inactive`
- `on_leave`
- `suspended`
- `terminated`

### Valid Category Values
- `beauty`
- `spa`
- `salon`
- `fitness`
- `wellness`

---

## Projection List Support

The `/list` endpoint supports projection to reduce payload size:

**Without projection** (returns full objects):
```json
{
  "filters": {"status": "active"},
  "skip": 0,
  "limit": 10
}
```

**With projection** (returns only specified fields):
```json
{
  "filters": {"status": "active"},
  "skip": 0,
  "limit": 10,
  "projection_list": ["staff_id", "name", "phone"]
}
```

Benefits:
- 50-90% payload reduction
- Better performance
- Less network bandwidth

---

## Error Responses

### 400 Bad Request
```json
{
  "detail": "Staff code SP001 already exists"
}
```

### 404 Not Found
```json
{
  "detail": "Service professional 550e8400-e29b-41d4-a716-446655440001 not found"
}
```

### 500 Internal Server Error
```json
{
  "detail": "Failed to create service professional"
}
```

---

## MongoDB Collection
- Collection: `spa_service_professionals`
- Indexes: `staff_code`, `phone`, `is_deleted`

---

## Example Use Cases

### 1. Add New Address
```json
PUT /service-professionals/{staff_id}
{
  "address": {
    "street": "789 Park Avenue",
    "city": "Bangalore",
    "state": "Karnataka",
    "postal_code": "560001",
    "country": "India"
  }
}
```

### 2. Change Email
```json
PUT /service-professionals/{staff_id}
{
  "email": "new.email@example.com"
}
```

### 3. Update Status to On Leave
```json
PUT /service-professionals/{staff_id}
{
  "status": "on_leave"
}
```

### 4. Add New Skills
```json
PUT /service-professionals/{staff_id}
{
  "skills": ["facial", "makeup", "hair_styling", "nail_art"]
}
```

### 5. List Active Beauty Professionals
```json
POST /service-professionals/list
{
  "filters": {
    "status": "active",
    "category": "beauty"
  },
  "projection_list": ["staff_id", "name", "phone", "skills"]
}
```

---

## Testing

Use the provided endpoints to test the API. All endpoints follow standard REST conventions and return appropriate HTTP status codes.

**Collection:** `spa_service_professionals`
**Module Path:** `app/service_professionals/`