# Quick Start Guide - Profile Update Request System

## 🚀 Setup (5 minutes)

### 1. Run Migration
```bash
php artisan migrate
```

This creates the `profile_update_requests` table.

### 2. Import Postman Collection
Import `POSTMAN_COLLECTION.json` into Postman for easy testing.

### 3. Set Environment Variables in Postman
- `base_url`: Your API base URL (e.g., `http://localhost:8000`)
- `vendor_token`: Vendor's authentication token
- `admin_token`: Admin's authentication token

---

## 📝 Complete Workflow (Step by Step)

### **Vendor Side**

#### Step 1: Upload Logo
```bash
POST /api/media
Content-Type: multipart/form-data

file: [Select your logo.jpg]
model: Profile
media_type: image
width: 800
height: 800
quality: 85
```

**Save the returned `id`** (e.g., `abc123-logo-id`)

#### Step 2: Upload Commercial Register File
```bash
POST /api/media
Content-Type: multipart/form-data

file: [Select your document.pdf]
model: Profile
media_type: pdf
generate_thumbnail: true
```

**Save the returned `id`** (e.g., `def456-file-id`)

#### Step 3: Create Profile Update Request
```bash
POST /api/dashboard/vendor/profile-update-requests
Content-Type: application/json
Authorization: Bearer {vendor_token}

{
  "logo": "abc123-logo-id",
  "commercial_register_file": "def456-file-id",
  "commercial_register_number": "CR-2024-123456",
  "ar": {
    "name": "متجر الإلكترونيات الحديثة",
    "description": "نحن متجر متخصص في بيع الأجهزة الإلكترونية"
  },
  "en": {
    "name": "Modern Electronics Store",
    "description": "We are a store specialized in selling electronic devices"
  },
  "location": {
    "country_id": 1,
    "city_id": 5,
    "lat": 24.7136,
    "lng": 46.6753,
    "name": "Main Branch - Riyadh",
    "property_number": "1234",
    "details": "Building 15, Floor 2, Office 201",
    "url": "https://maps.google.com/?q=24.7136,46.6753"
  }
}
```

✅ **Result:** Request created with status `pending`, supervisors notified

#### Step 4: Check Request Status
```bash
GET /api/dashboard/vendor/profile-update-requests
Authorization: Bearer {vendor_token}
```

---

### **Admin Side**

#### Step 1: View Pending Requests
```bash
GET /api/dashboard/admin/profile-update-requests?status=pending
Authorization: Bearer {admin_token}
```

#### Step 2: View Request Details
```bash
GET /api/dashboard/admin/profile-update-requests/{id}
Authorization: Bearer {admin_token}
```

**Response includes:**
- Requested changes (`profile_data`, `location_data`)
- Current profile data for comparison
- Vendor information

#### Step 3: Approve or Reject

**Option A: Approve**
```bash
POST /api/dashboard/admin/profile-update-requests/{id}/approve
Authorization: Bearer {admin_token}
Content-Type: application/json

{}
```

✅ **Result:** 
- Profile updated automatically
- Location created/updated
- Vendor notified
- Status changed to `approved`

**Option B: Reject**
```bash
POST /api/dashboard/admin/profile-update-requests/{id}/reject
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "reason": "The commercial register file is not clear. Please upload a higher quality document."
}
```

✅ **Result:**
- Status changed to `rejected`
- Vendor notified with reason
- No changes applied to profile

---

## 🎯 Common Use Cases

### Use Case 1: Update Logo Only
```json
{
  "logo": "new-logo-media-id",
  "ar": {
    "name": "متجر الإلكترونيات",
    "description": "وصف المتجر"
  },
  "en": {
    "name": "Electronics Store",
    "description": "Store description"
  }
}
```

### Use Case 2: Update Location Only
```json
{
  "ar": {
    "name": "متجر الإلكترونيات",
    "description": "وصف المتجر"
  },
  "en": {
    "name": "Electronics Store",
    "description": "Store description"
  },
  "location": {
    "country_id": 1,
    "city_id": 5,
    "lat": 24.7136,
    "lng": 46.6753,
    "name": "New Branch Location"
  }
}
```

### Use Case 3: Update Everything
```json
{
  "logo": "logo-media-id",
  "commercial_register_file": "file-media-id",
  "commercial_register_number": "CR-2024-123456",
  "ar": {
    "name": "اسم جديد",
    "description": "وصف جديد"
  },
  "en": {
    "name": "New Name",
    "description": "New Description"
  },
  "location": {
    "country_id": 1,
    "city_id": 5,
    "lat": 24.7136,
    "lng": 46.6753,
    "name": "Updated Location",
    "property_number": "5678",
    "details": "New building details",
    "url": "https://maps.google.com/?q=24.7136,46.6753"
  }
}
```

---

## 🔍 Filter & Search Examples

### Admin Filters

**Get pending requests:**
```
GET /api/dashboard/admin/profile-update-requests?status=pending
```

**Get requests by specific vendor:**
```
GET /api/dashboard/admin/profile-update-requests?vendor_id=25
```

**Search by vendor name/email:**
```
GET /api/dashboard/admin/profile-update-requests?search=electronics
```

**Combine filters:**
```
GET /api/dashboard/admin/profile-update-requests?status=pending&search=store&per_page=20
```

### Vendor Filters

**Get own pending requests:**
```
GET /api/dashboard/vendor/profile-update-requests?status=pending
```

**Get own approved requests:**
```
GET /api/dashboard/vendor/profile-update-requests?status=approved
```

---

## ⚠️ Important Rules

1. **One Pending Request Per Vendor**
   - Vendor can only have ONE pending request at a time
   - Must wait for approval/rejection before creating new request

2. **Vendor Can Only Delete Pending Requests**
   - Approved/rejected requests cannot be deleted by vendor
   - Admin can delete any request

3. **Media Upload First**
   - Always upload media files FIRST to get media IDs
   - Then use those IDs in the profile update request

4. **Translations Required**
   - Both `ar` and `en` translations are required
   - Each must have `name` (2-100 chars) and `description` (2-1000 chars)

5. **Media Validation**
   - Media IDs must exist in the `media` table
   - Media IDs are UUIDs (strings), not integers

---

## 📊 Status Flow

```
┌─────────┐
│ PENDING │ ◄── Vendor creates request
└────┬────┘
     │
     ├──► Admin Approves ──► ┌──────────┐
     │                        │ APPROVED │ ──► Profile Updated
     │                        └──────────┘
     │
     └──► Admin Rejects ───► ┌──────────┐
                              │ REJECTED │ ──► No changes
                              └──────────┘
```

---

## 🔔 Notifications

### When Vendor Creates Request
- **To:** All supervisors
- **Message:** "New profile update request"

### When Admin Approves
- **To:** Vendor + Supervisors
- **Message:** "Profile update request approved"

### When Admin Rejects
- **To:** Vendor
- **Message:** Admin's rejection reason

---

## 🐛 Troubleshooting

### Error: "You already have a pending profile update request"
**Solution:** Wait for admin to approve/reject, or delete the pending request first

### Error: "The selected logo is invalid"
**Solution:** Upload the logo file first to get a valid media ID

### Error: "This request has already been processed"
**Solution:** Request is already approved/rejected, cannot be processed again

### Error: "Only pending requests can be deleted"
**Solution:** Vendor can only delete pending requests, not approved/rejected ones

---

## 📚 Additional Resources

- **Full Documentation:** `PROFILE_UPDATE_REQUEST_IMPLEMENTATION.md`
- **Media Upload Guide:** `MEDIA_UPLOAD_GUIDE.md`
- **Postman Collection:** `POSTMAN_COLLECTION.json`

---

## ✅ Testing Checklist

- [ ] Run migration successfully
- [ ] Upload logo via media endpoint
- [ ] Upload commercial register file
- [ ] Create profile update request with media IDs
- [ ] Verify supervisors receive notification
- [ ] Admin views pending requests
- [ ] Admin approves request
- [ ] Verify profile is updated
- [ ] Verify vendor receives approval notification
- [ ] Create another request
- [ ] Admin rejects with reason
- [ ] Verify vendor receives rejection notification
- [ ] Vendor deletes pending request
- [ ] Test filter by status
- [ ] Test search by vendor name

---

## 🎉 You're Ready!

The system is fully implemented and ready to use. Start with the Postman collection for easy testing, then integrate into your frontend application.

**Need help?** Check the detailed documentation files or review the code comments.