# Shop Management

**Author**: Josh S. Sakweli, Backend Lead Team  
**Last Updated**: 2025-09-23  
**Version**: v1.0

**Base URL**: `https://api.nextgate.com/api/v1`

**Short Description**: The Shop Management API provides comprehensive endpoints for creating, managing, and retrieving shop information within the NextGate platform. This API handles shop registration, updates, approvals, categorization, and includes integrated rating and review data for enhanced shop profiles.

**Hints**: 
- All shop operations require proper authentication via Bearer token
- Shop creation requires valid category ID and owner authentication
- Pagination uses 1-based page numbering (page=1 for first page)
- Shop approval operations require SUPER_ADMIN or STAFF_ADMIN roles
- Featured shops are randomized on each request for better discovery
- Rating and review data is automatically included in shop responses

---

## Standard Response Format

All API responses follow a consistent structure using our Globe Response Builder pattern:

### Success Response Structure
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    // Actual response data goes here
  }
}
```

### Error Response Structure
```json
{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-09-23T10:30:45",
  "data": "Error description" // or detailed error object
}
```

### Standard Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `success` | boolean | Always `true` for successful operations, `false` for errors |
| `httpStatus` | string | HTTP status name (OK, BAD_REQUEST, NOT_FOUND, etc.) |
| `message` | string | Human-readable message describing the operation result |
| `action_time` | string | ISO 8601 timestamp of when the response was generated |
| `data` | object/string | Response payload for success, error details for failures |

---

## Endpoints

## 1. Create Shop
**Purpose**: Creates a new shop with all required information including owner details, category assignment, and location data

**Endpoint**: <span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `{base_url}/shops`

**Access Level**: 🔒 Protected (Requires Bearer Token Authentication)

**Authentication**: Bearer Token

**Request Headers**:
| Header | Type | Required | Description |
|--------|------|----------|-------------|
| Authorization | string | Yes | Bearer token for authenticated user |
| Content-Type | string | Yes | application/json |

**Request JSON Sample**:
```json
{
  "shopName": "Mama Lucy's Restaurant",
  "shopDescription": "Authentic Tanzanian cuisine served with love in the heart of Dar es Salaam",
  "tagline": "Taste of home",
  "logoUrl": "https://example.com/logo.jpg",
  "bannerUrl": "https://example.com/banner.jpg",
  "shopImages": [
    "https://example.com/shop1.jpg",
    "https://example.com/shop2.jpg"
  ],
  "categoryId": "550e8400-e29b-41d4-a716-446655440000",
  "shopType": "HYBRID",
  "phoneNumber": "+255123456789",
  "email": "info@mamalucy.co.tz",
  "websiteUrl": "https://mamalucy.co.tz",
  "socialMediaLinks": [
    "https://facebook.com/mamalucy",
    "https://instagram.com/mamalucy"
  ],
  "address": "Msimbazi Street, Block 45",
  "city": "Dar es Salaam",
  "region": "Dar es Salaam",
  "postalCode": "12345",
  "countryCode": "TZ",
  "latitude": -6.7924,
  "longitude": 39.2083,
  "locationNotes": "Near the main bus stop",
  "businessRegistrationNumber": "REG123456",
  "taxNumber": "TAX789012",
  "licenseNumber": "LIC345678",
  "promotionText": "Grand opening - 20% off all meals!"
}
```

**Request Body Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| shopName | string | Yes | Name of the shop | Min: 2, Max: 100 characters |
| shopDescription | string | Yes | Detailed description of the shop | Max: 1000 characters |
| categoryId | UUID | Yes | Shop category identifier | Must be valid category ID |
| phoneNumber | string | Yes | Contact phone number | Pattern: ^\\+?[0-9]{10,15}$ |
| city | string | Yes | City location | Min: 2, Max: 50 characters |
| region | string | Yes | Region/state location | Min: 2, Max: 50 characters |
| tagline | string | No | Short promotional tagline | Max: 50 characters |
| logoUrl | string | No | URL to shop logo image | Must be valid URL, Max: 1000 chars |
| bannerUrl | string | No | URL to shop banner image | Must be valid URL, Max: 1000 chars |
| shopImages | array | No | Array of shop image URLs | Each URL max 1000 chars |
| shopType | string | No | Type of shop | enum: PHYSICAL, ONLINE, HYBRID (default: HYBRID) |
| email | string | No | Shop contact email | Must be valid email, Max: 100 chars |
| websiteUrl | string | No | Shop website URL | Must be valid URL, Max: 200 chars |
| socialMediaLinks | array | No | Array of social media URLs | Each URL max 500 chars |
| address | string | No | Street address | Max: 200 characters |
| postalCode | string | No | Postal/ZIP code | Max: 10 characters |
| countryCode | string | No | Country code | Max: 3 chars (default: "TZ") |
| latitude | decimal | No | Latitude coordinate | Range: -90.0 to 90.0 |
| longitude | decimal | No | Longitude coordinate | Range: -180.0 to 180.0 |
| locationNotes | string | No | Additional location details | Max: 300 characters |
| businessRegistrationNumber | string | No | Business registration number | Max: 50 characters |
| taxNumber | string | No | Tax identification number | Max: 50 characters |
| licenseNumber | string | No | Business license number | Max: 50 characters |
| promotionText | string | No | Current promotion message | Max: 200 characters |

**Success Response JSON Sample**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Shop created successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "shopId": "123e4567-e89b-12d3-a456-426614174000",
    "shopName": "Mama Lucy's Restaurant",
    "shopSlug": "mama-lucys-restaurant",
    "shopDescription": "Authentic Tanzanian cuisine served with love in the heart of Dar es Salaam",
    "tagline": "Taste of home",
    "logoUrl": "https://example.com/logo.jpg",
    "bannerUrl": "https://example.com/banner.jpg",
    "shopImages": [
      "https://example.com/shop1.jpg",
      "https://example.com/shop2.jpg"
    ],
    "ownerId": "456e7890-e89b-12d3-a456-426614174001",
    "ownerName": "Lucy Mwalimu",
    "categoryId": "550e8400-e29b-41d4-a716-446655440000",
    "categoryName": "Restaurant & Food",
    "shopType": "HYBRID",
    "status": "PENDING",
    "phoneNumber": "+255123456789",
    "email": "info@mamalucy.co.tz",
    "websiteUrl": "https://mamalucy.co.tz",
    "socialMediaLinks": [
      "https://facebook.com/mamalucy",
      "https://instagram.com/mamalucy"
    ],
    "address": "Msimbazi Street, Block 45",
    "city": "Dar es Salaam",
    "region": "Dar es Salaam",
    "postalCode": "12345",
    "countryCode": "TZ",
    "latitude": -6.7924,
    "longitude": 39.2083,
    "locationNotes": "Near the main bus stop",
    "businessRegistrationNumber": "REG123456",
    "taxNumber": "TAX789012",
    "licenseNumber": "LIC345678",
    "establishedYear": null,
    "isVerified": false,
    "verificationBadge": null,
    "trustScore": 0.00,
    "lastSeenTime": null,
    "isFeatured": false,
    "featuredUntil": null,
    "promotionText": "Grand opening - 20% off all meals!",
    "isApproved": true,
    "createdAt": "2025-09-23T10:30:45",
    "updatedAt": "2025-09-23T10:30:45",
    "approvedAt": null,
    "averageRating": null,
    "totalRatings": 0,
    "totalActiveReviews": 0,
    "reviews": []
  }
}
```

**Success Response Fields**:
| Field | Description |
|-------|-------------|
| shopId | Unique identifier for the shop |
| shopSlug | URL-friendly version of shop name |
| status | Shop status (PENDING, ACTIVE, SUSPENDED, CLOSED, UNDER_REVIEW) |
| isApproved | Whether shop has been approved by admin |
| averageRating | Average rating score (null if no ratings) |
| totalRatings | Total number of ratings received |
| totalActiveReviews | Number of active reviews |
| reviews | Array of review objects |
## 2. Get All Shops (List)
**Purpose**: Retrieves all shops in the system without pagination

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/shops/all`

**Access Level**: 🌐 Public (No authentication required)

**Authentication**: None

**Success Response JSON Sample**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "All shops retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": [
    {
      "shopId": "123e4567-e89b-12d3-a456-426614174000",
      "shopName": "Mama Lucy's Restaurant",
      "shopSlug": "mama-lucys-restaurant",
      "averageRating": 4.5,
      "totalRatings": 25,
      "totalActiveReviews": 12,
      "topReviews": [
        {
          "reviewId": "rev-123",
          "userName": "John Doe",
          "reviewText": "Amazing food and great service!",
          "createdAt": "2025-09-22T14:30:00"
        }
      ]
    }
  ]
}
```

---

## 3. Get All Shops (Paginated)
**Purpose**: Retrieves all shops with pagination support for better performance

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/shops/all-paged`

**Access Level**: 🌐 Public (No authentication required)

**Authentication**: None

**Query Parameters**:
| Parameter | Type | Required | Description | Validation | Default |
|-----------|------|----------|-------------|------------|---------|
| page | integer | No | Page number (1-based) | Min: 1 | 1 |
| size | integer | No | Number of items per page | Min: 1, Max: 100 | 10 |

**Success Response JSON Sample**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Shops retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "shops": [
      {
        "shopId": "123e4567-e89b-12d3-a456-426614174000",
        "shopName": "Mama Lucy's Restaurant",
        "averageRating": 4.5,
        "totalRatings": 25,
        "city": "Dar es Salaam",
        "region": "Dar es Salaam"
      }
    ],
    "currentPage": 1,
    "pageSize": 10,
    "totalElements": 150,
    "totalPages": 15,
    "hasNext": true,
    "hasPrevious": false,
    "isFirst": true,
    "isLast": false
  }
}
```

---

## 4. Update Shop
**Purpose**: Updates shop information (only shop owners can update their shops)

**Endpoint**: <span style="background-color: #ffc107; color: black; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">PUT</span> `{base_url}/shops/{shopId}`

**Access Level**: 🔒 Protected (Shop Owner Only)

**Authentication**: Bearer Token

**Path Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| shopId | UUID | Yes | Unique identifier of the shop | Must be valid UUID |

**Request Headers**:
| Header | Type | Required | Description |
|--------|------|----------|-------------|
| Authorization | string | Yes | Bearer token for authenticated user |
| Content-Type | string | Yes | application/json |

**Request JSON Sample**:
```json
{
	"shopName": "Mama Juma's Kitchen - Tabora",
	"shopDescription": "Authentic Tanzanian cuisine with fresh ingredients and traditional recipes passed down through generations. We specialize in local dishes like ugali, nyama choma, and pilau.",
	"logoUrl": "https://example.com/images/mama-juma-logo.jpg",
	"categoryId": "fec6a097-612c-470c-af4f-4807e24bef9a",
	"phoneNumber": "+255712345678",
	"city": "Dar es Salaam",
	"region": "Dar es Salaam",
	"tagline": "Taste of Home",
	"shopImages": [
		"https://example.com/images/shop-front.jpg",
		"https://example.com/images/kitchen.jpg"
	],
	"bannerUrl": "https://example.com/images/banner.jpg",
	"shopType": "ONLINE",
	"email": "info@mamajuma.co.tz",
	"websiteUrl": "https://mamajuma.co.tz",
	"socialMediaLinks": [
		"https://facebook.com/mamajuma",
		"https://instagram.com/mamajuma"
	],
	"address": "123 Msimbazi Street, Kariakoo",
	"postalCode": "11101",
	"businessRegistrationNumber": "VRI19939",
	"taxNumber": "TAX9482",
	"countryCode": "TZ",
	"latitude": -6.8160,
	"longitude": 39.2803,
	"locationNotes": "Near Kariakoo Market, opposite the blue building",
	"promotionText": "Free delivery within 5km for orders above 20,000 TSH"
}
```

**Request Body Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| shopName | string | No | Updated shop name | Min: 2, Max: 100 characters |
| shopDescription | string | No | Updated description | Max: 1000 characters |
| tagline | string | No | Updated tagline | Max: 50 characters |
| logoUrl | string | No | Updated logo URL | Must be valid URL |
| bannerUrl | string | No | Updated banner URL | Must be valid URL |
| shopImages | array | No | Updated shop images | Array of valid URLs |
| categoryId | UUID | No | Updated category | Must be valid category ID |
| shopType | string | No | Updated shop type | enum: PHYSICAL, ONLINE, HYBRID |
| phoneNumber | string | No | Updated phone number | Pattern: ^\\+?[0-9]{10,15}$ |
| email | string | No | Updated email | Must be valid email |
| websiteUrl | string | No | Updated website URL | Must be valid URL |
| socialMediaLinks | array | No | Updated social media links | Array of valid URLs |
| address | string | No | Updated address | Max: 200 characters |
| city | string | No | Updated city | Min: 2, Max: 50 characters |
| region | string | No | Updated region | Min: 2, Max: 50 characters |
| postalCode | string | No | Updated postal code | Max: 10 characters |
| countryCode | string | No | Updated country code | Max: 3 characters |
| latitude | decimal | No | Updated latitude | Range: -90.0 to 90.0 |
| longitude | decimal | No | Updated longitude | Range: -180.0 to 180.0 |
| locationNotes | string | No | Updated location notes | Max: 300 characters |
| promotionText | string | No | Updated promotion text | Max: 200 characters |

**Success Response JSON Sample**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Shop updated successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "shopId": "123e4567-e89b-12d3-a456-426614174000",
    "shopName": "Mama Lucy's Premium Restaurant",
    "shopSlug": "mama-lucys-premium-restaurant",
    "updatedAt": "2025-09-23T10:30:45"
  }
}
```

---

## 5. Get Shop by ID (Summary)
**Purpose**: Retrieves basic shop information by shop ID

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/shops/{shopId}`

**Access Level**: 🌐 Public (No authentication required)

**Authentication**: None

**Path Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| shopId | UUID | Yes | Unique identifier of the shop | Must be valid UUID |

**Success Response JSON Sample**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Shop retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "shopId": "123e4567-e89b-12d3-a456-426614174000",
    "shopName": "Mama Lucy's Restaurant",
    "shopSlug": "mama-lucys-restaurant",
    "shopDescription": "Authentic Tanzanian cuisine",
    "logoUrl": "https://example.com/logo.jpg",
    "averageRating": 4.5,
    "totalRatings": 25,
    "totalActiveReviews": 12,
    "city": "Dar es Salaam",
    "region": "Dar es Salaam",
    "isVerified": false,
    "trustScore": 8.5
  }
}
```

---

## 6. Get Shop by ID (Detailed)
**Purpose**: Retrieves complete shop information including sensitive business details (owner/admin access only)

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/shops/{shopId}/detailed`

**Access Level**: 🔒 Protected (Shop Owner or Admin Only)

**Authentication**: Bearer Token

**Path Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| shopId | UUID | Yes | Unique identifier of the shop | Must be valid UUID |

**Request Headers**:
| Header | Type | Required | Description |
|--------|------|----------|-------------|
| Authorization | string | Yes | Bearer token for authenticated user |

**Success Response JSON Sample**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Shop retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "shopId": "123e4567-e89b-12d3-a456-426614174000",
    "shopName": "Mama Lucy's Restaurant",
    "businessRegistrationNumber": "REG123456",
    "taxNumber": "TAX789012",
    "licenseNumber": "LIC345678",
    "averageRating": 4.5,
    "totalRatings": 25,
    "reviews": [
      {
        "reviewId": "rev-123",
        "userName": "John Doe",
        "reviewText": "Amazing food!",
        "status": "ACTIVE",
        "createdAt": "2025-09-22T14:30:00"
      }
    ]
  }
}
```
## 7. Get My Shops
**Purpose**: Retrieves all shops owned by the authenticated user

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/shops/my-shops`

**Access Level**: 🔒 Protected (Authenticated User Only)

**Authentication**: Bearer Token

**Request Headers**:
| Header | Type | Required | Description |
|--------|------|----------|-------------|
| Authorization | string | Yes | Bearer token for authenticated user |

**Success Response JSON Sample**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "My shops retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": [
    {
      "shopId": "123e4567-e89b-12d3-a456-426614174000",
      "shopName": "Mama Lucy's Restaurant",
      "status": "ACTIVE",
      "isApproved": true,
      "averageRating": 4.5,
      "totalRatings": 25,
      "createdAt": "2025-09-20T10:30:45"
    }
  ]
}
```

---

## 8. Get My Shops (Paginated)
**Purpose**: Retrieves user's shops with pagination support

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/shops/my-shops-paged`

**Access Level**: 🔒 Protected (Authenticated User Only)

**Authentication**: Bearer Token

**Query Parameters**:
| Parameter | Type | Required | Description | Validation | Default |
|-----------|------|----------|-------------|------------|---------|
| page | integer | No | Page number (1-based) | Min: 1 | 1 |
| size | integer | No | Number of items per page | Min: 1, Max: 100 | 10 |

**Request Headers**:
| Header | Type | Required | Description |
|--------|------|----------|-------------|
| Authorization | string | Yes | Bearer token for authenticated user |

---

## 9. Approve Shop
**Purpose**: Approve or reject a shop (admin operation)

**Endpoint**: <span style="background-color: #fd7e14; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">PATCH</span> `{base_url}/shops/{shopId}/approve-shop`

**Access Level**: 🔒 Protected (Super Admin or Staff Admin Only)

**Authentication**: Bearer Token

**Path Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| shopId | UUID | Yes | Unique identifier of the shop | Must be valid UUID |

**Query Parameters**:
| Parameter | Type | Required | Description | Validation | Default |
|-----------|------|----------|-------------|------------|---------|
| approve | boolean | Yes | Whether to approve (true) or reject (false) | Must be boolean | - |

**Request Headers**:
| Header | Type | Required | Description |
|--------|------|----------|-------------|
| Authorization | string | Yes | Bearer token for admin user |

**Success Response JSON Sample**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Shop approval status changed successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "shopId": "123e4567-e89b-12d3-a456-426614174000",
    "shopName": "Mama Lucy's Restaurant",
    "isApproved": true,
    "approvedAt": "2025-09-23T10:30:45"
  }
}
```

---

## 10. Get Shops by Category
**Purpose**: Retrieves all shops in a specific category

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/shops/category/{categoryId}`

**Access Level**: 🌐 Public (No authentication required)

**Authentication**: None

**Path Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| categoryId | UUID | Yes | Unique identifier of the shop category | Must be valid UUID |

**Success Response JSON Sample**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Shops by category retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": [
    {
      "shopId": "123e4567-e89b-12d3-a456-426614174000",
      "shopName": "Mama Lucy's Restaurant",
      "categoryName": "Restaurant & Food",
      "averageRating": 4.5,
      "city": "Dar es Salaam"
    }
  ]
}
```

---

## 11. Get Shops by Category (Paginated)
**Purpose**: Retrieves shops in a category with pagination

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/shops/category/{categoryId}/paged`

**Access Level**: 🌐 Public (No authentication required)

**Authentication**: None

**Path Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| categoryId | UUID | Yes | Unique identifier of the shop category | Must be valid UUID |

**Query Parameters**:
| Parameter | Type | Required | Description | Validation | Default |
|-----------|------|----------|-------------|------------|---------|
| page | integer | No | Page number (1-based) | Min: 1 | 1 |
| size | integer | No | Number of items per page | Min: 1, Max: 100 | 10 |

---

## 12. Get Featured Shops
**Purpose**: Retrieves randomly selected featured shops (up to 20 shops)

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/shops/featured`

**Access Level**: 🌐 Public (No authentication required)

**Authentication**: None

**Success Response JSON Sample**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Featured shops retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": [
    {
      "shopId": "123e4567-e89b-12d3-a456-426614174000",
      "shopName": "Mama Lucy's Restaurant",
      "averageRating": 4.5,
      "totalRatings": 25,
      "city": "Dar es Salaam",
      "isVerified": true
    }
  ]
}
```

---

## 13. Get Featured Shops (Paginated)
**Purpose**: Retrieves featured shops with pagination (randomized on each request)

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/shops/featured-paged`

**Access Level**: 🌐 Public (No authentication required)

**Authentication**: None

**Query Parameters**:
| Parameter | Type | Required | Description | Validation | Default |
|-----------|------|----------|-------------|------------|---------|
| page | integer | No | Page number (1-based) | Min: 1 | 1 |
| size | integer | No | Number of items per page | Min: 1, Max: 100 | 10 |

---

## 14. Get Shop Summary Statistics
**Purpose**: Retrieves comprehensive statistics including ratings, reviews, and user activities for a shop

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/shops/{shopId}/summary-stats`

**Access Level**: 🌐 Public (No authentication required)

**Authentication**: None

**Path Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| shopId | UUID | Yes | Unique identifier of the shop | Must be valid UUID |

**Success Response JSON Sample**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Shop summary stats retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "shopId": "123e4567-e89b-12d3-a456-426614174000",
    "shopName": "Mama Lucy's Restaurant",
    "averageRating": 4.5,
    "totalRatings": 25,
    "ratingDistribution": {
      "1": 1,
      "2": 2,
      "3": 5,
      "4": 7,
      "5": 10
    },
    "totalReviews": 15,
    "activeReviews": 12,
    "hiddenReviews": 2,
    "flaggedReviews": 1,
    "userActivities": [
      {
        "userId": "user-123",
        "userName": "John Doe",
        "reviewId": "rev-123",
        "reviewText": "Amazing food and service!",
        "reviewStatus": "ACTIVE",
        "reviewDate": "2025-09-22T14:30:00",
        "ratingId": "rat-123",
        "ratingValue": 5,
        "ratingDate": "2025-09-22T14:35:00",
        "hasReview": true,
        "hasRating": true
      }
    ]
  }
}
```

**Success Response Fields**:
| Field | Description |
|-------|-------------|
| shopId | Unique identifier of the shop |
| shopName | Name of the shop |
| averageRating | Average rating score (1-5) |
| totalRatings | Total number of ratings received |
| ratingDistribution | Count of ratings by star value (1-5) |
| totalReviews | Total number of reviews (all statuses) |
| activeReviews | Number of active/visible reviews |
| hiddenReviews | Number of hidden reviews |
| flaggedReviews | Number of flagged reviews |
| userActivities | Array of combined user review and rating activities |
| userActivities.hasReview | Whether user has written a review |
| userActivities.hasRating | Whether user has given a rating |

## Standard Error Types and Responses

### Application-Level Exceptions (400-499)
- `400 BAD_REQUEST`: General invalid request data, random exceptions, or item already exists
- `401 UNAUTHORIZED`: Authentication issues (empty, invalid, expired, or malformed tokens)
- `403 FORBIDDEN`: Access denied, permission issues, verification failures, expired invitations
- `404 NOT_FOUND`: Requested resource does not exist
- `422 UNPROCESSABLE_ENTITY`: Validation errors with detailed field information
- `429 TOO_MANY_REQUESTS`: Rate limit exceeded

### Server-Level Exceptions (500+)
- `500 INTERNAL_SERVER_ERROR`: Unexpected server errors

**Error Response Examples**:

*Shop Already Exists (400):*
```json
{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Shop with this name already exists",
  "action_time": "2025-09-23T10:30:45",
  "data": "Shop with this name already exists"
}
```

*Unauthorized - Token Issues (401):*
```json
{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Token has expired",
  "action_time": "2025-09-23T10:30:45",
  "data": "Token has expired"
}
```

*Access Denied - Insufficient Permissions (403):*
```json
{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Access denied: Insufficient permissions",
  "action_time": "2025-09-23T10:30:45",
  "data": "Access denied: Insufficient permissions"
}
```

*Shop Not Found (404):*
```json
{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Shop not found",
  "action_time": "2025-09-23T10:30:45",
  "data": "Shop not found"
}
```

*Category Not Found (404):*
```json
{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Shop category not found",
  "action_time": "2025-09-23T10:30:45",
  "data": "Shop category not found"
}
```

*User Not Authenticated (404):*
```json
{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "User not authenticated",
  "action_time": "2025-09-23T10:30:45",
  "data": "User not authenticated"
}
```

*Validation Error (422):*
```json
{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "shopName": "Shop name must be between 2 and 100 characters",
    "phoneNumber": "Phone number must be between 10-15 digits and may start with +",
    "email": "Email must be valid"
  }
}
```

*Random Business Logic Error (400):*
```json
{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Only shop owners can update their shops",
  "action_time": "2025-09-23T10:30:45",
  "data": "Only shop owners can update their shops"
}
```

*Cannot Update Deleted Shop (400):*
```json
{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot update a deleted shop",
  "action_time": "2025-09-23T10:30:45",
  "data": "Cannot update a deleted shop"
}
```

---

## Data Models and Enums

### Shop Status Enum
| Value | Description |
|-------|-------------|
| `PENDING` | Awaiting admin approval |
| `ACTIVE` | Active and operational |
| `SUSPENDED` | Temporarily suspended by admin |
| `CLOSED` | Permanently closed/inactive |
| `UNDER_REVIEW` | Under admin review for policy violations |

### Shop Type Enum
| Value | Description |
|-------|-------------|
| `PHYSICAL` | Physical store only (brick-and-mortar) |
| `ONLINE` | Online store only (e-commerce) |
| `HYBRID` | Both physical and online presence |

### Verification Badge Enum
| Value | Description |
|-------|-------------|
| `BRONZE` | Basic verification (documents verified) |
| `SILVER` | Enhanced verification (business registration + documents) |
| `GOLD` | Premium verification (full compliance + good track record) |
| `PREMIUM` | Highest level (partner status + excellent performance) |

### Review Status Enum (from related services)
| Value | Description |
|-------|-------------|
| `ACTIVE` | Review is visible and active |
| `HIDDEN` | Review is hidden from public view |
| `FLAGGED` | Review has been flagged for review |
| `DELETED` | Review has been deleted |

---

## Business Rules and Logic

### Shop Creation Rules
- Shop name must be unique across all active shops
- Shop slug is automatically generated from shop name and must be unique
- New shops are automatically set to `PENDING` status
- Shop owner is automatically set to the authenticated user
- Shop approval is automatically set to `true` in current implementation
- Default country code is "TZ" (Tanzania)
- Default shop type is "HYBRID"

### Shop Update Rules
- Only shop owners can update their own shops
- Shop name changes trigger automatic slug regeneration
- Deleted shops cannot be updated
- Category ID must exist and be valid
- Phone number and email validation applies on updates

### Shop Approval Rules
- Only users with `ROLE_SUPER_ADMIN` or `ROLE_STAFF_ADMIN` can approve shops
- Approval status change is tracked with timestamp and admin user
- Approved shops can be featured in search results

### Access Control Rules
- **Public endpoints**: Shop listings, shop details (summary), categories, featured shops
- **Authenticated user**: Create shop, update own shop, view own shops
- **Admin only**: Approve/reject shops, view detailed shop information for all shops
- **Owner/Admin only**: View detailed shop information with business details

### Rating and Review Integration
- Shop responses automatically include rating summaries (average, total count)
- Shop responses include review summaries (total active reviews, top reviews)
- Summary statistics combine ratings and reviews from related services
- User activities show combined review and rating history per user

### Pagination Rules
- Page numbers are 1-based (first page is page=1)
- Default page size is 10 items
- Maximum page size is 100 items
- Invalid page numbers default to page 1
- Invalid page sizes default to 10

### Featured Shops Logic
- Featured shops are randomly selected from all approved, active shops
- Non-paginated featured endpoint returns up to 20 shops
- Paginated featured endpoint maintains randomization across requests
- Featured status can be time-limited (featuredUntil field)

---

## Authentication and Authorization

### Bearer Token Authentication
Include the Bearer token in the Authorization header for protected endpoints:
```
Authorization: Bearer your_jwt_token_here
```

### Required Roles for Admin Operations
- **Shop Approval**: Requires `ROLE_SUPER_ADMIN` or `ROLE_STAFF_ADMIN`
- **Detailed Shop Access**: Shop owner or admin roles
- **Shop Updates**: Shop owner only

### Token Validation
- Tokens are validated on each request to protected endpoints
- Expired tokens return 401 Unauthorized
- Invalid or malformed tokens return 401 Unauthorized
- Missing tokens on protected endpoints return 401 Unauthorized

---