kontenhumas-be/docs/CLIENTS_QUERY_CONTEXT_GUIDE.md

# 📋 ClientsQueryRequestContext - Usage Guide (camelCase)

## 🎯 **Overview**

`ClientsQueryRequestContext` adalah struct yang memudahkan parsing query parameters dari HTTP request untuk filtering clients dengan hierarchy support. **Semua JSON fields menggunakan camelCase format.**

## 🔧 **Available Query Parameters (camelCase)**

### **Basic Filters**
```bash
# Filter by name (case-insensitive, partial match)
GET /api/clients?name=company

# Filter by client type
GET /api/clients?clientType=parent_client
GET /api/clients?clientType=sub_client  
GET /api/clients?clientType=standalone

# Filter by parent client ID
GET /api/clients?parentClientId=123e4567-e89b-12d3-a456-426614174000

# Filter by active status
GET /api/clients?isActive=true
GET /api/clients?isActive=false
```

### **Hierarchy Filters**
```bash
# Only show clients that have children (parent clients)
GET /api/clients?onlyParentClients=true

# Only show standalone clients (no parent, no children)
GET /api/clients?onlyStandalone=true

# Only show root level clients (no parent)
GET /api/clients?onlyRootClients=true

# Include all descendants when filtering by parent
GET /api/clients?parentClientId=uuid&includeSubClients=true
```

### **Pagination**
```bash
# Pagination
GET /api/clients?page=1&limit=10
GET /api/clients?page=2&limit=20

# Sorting
GET /api/clients?sort=name&sort_by=asc
GET /api/clients?sort=created_at&sort_by=desc
```

## 🚀 **Usage Examples (camelCase)**

### **1. Get All Parent Clients**
```bash
GET /api/clients?clientType=parent_client&isActive=true
```

### **2. Get Sub-Clients of Specific Parent**
```bash
GET /api/clients?parentClientId=123e4567-e89b-12d3-a456-426614174000
```

### **3. Get All Root Level Clients**
```bash
GET /api/clients?onlyRootClients=true
```

### **4. Search Clients by Name**
```bash
GET /api/clients?name=company&isActive=true
```

### **5. Get All Standalone Clients**
```bash
GET /api/clients?onlyStandalone=true
```

### **6. Complex Filtering**
```bash
GET /api/clients?clientType=sub_client&isActive=true&page=1&limit=20&sort=name&sort_by=asc
```

## 📊 **Response Structure (camelCase)**

```json
{
  "success": true,
  "messages": ["Clients list successfully retrieved"],
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Parent Company",
      "description": "Main company",
      "clientType": "parent_client",
      "parentClientId": null,
      "parentClient": null,
      "subClients": [
        {
          "id": "456e7890-e89b-12d3-a456-426614174001",
          "name": "Sub Company 1",
          "clientType": "sub_client",
          "currentUsers": 25,
          "isActive": true
        }
      ],
      "subClientCount": 1,
      "maxUsers": 100,
      "maxStorage": 1073741824,
      "currentUsers": 50,
      "currentStorage": 536870912,
      "settings": "{\"theme\": \"dark\"}",
      "createdById": 1,
      "createdBy": {
        "id": 1,
        "username": "admin",
        "fullname": "Admin User"
      },
      "isActive": true,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "total_pages": 1
  }
}
```

## 🔍 **Filter Combinations**

### **Common Use Cases**

1. **Dashboard - Show Parent Clients Only**
   ```bash
   GET /api/clients?onlyParentClients=true&isActive=true&page=1&limit=10
   ```

2. **Client Management - Show All Active Clients**
   ```bash
   GET /api/clients?isActive=true&sort=name&sort_by=asc
   ```

3. **Hierarchy View - Show Root Clients**
   ```bash
   GET /api/clients?onlyRootClients=true&includeSubClients=true
   ```

4. **Search - Find Clients by Name**
   ```bash
   GET /api/clients?name=company&isActive=true
   ```

5. **Sub-Client Management - Show Children of Parent**
   ```bash
   GET /api/clients?parentClientId=uuid&isActive=true
   ```

## 📝 **Request Body Examples (camelCase)**

### **Create Client**
```json
{
  "name": "New Company",
  "description": "Company description",
  "clientType": "parent_client",
  "parentClientId": null,
  "maxUsers": 100,
  "maxStorage": 1073741824,
  "settings": "{\"theme\": \"dark\"}"
}
```

### **Update Client**
```json
{
  "name": "Updated Company",
  "clientType": "standalone",
  "parentClientId": null,
  "isActive": true
}
```

### **Move Client**
```json
{
  "targetParentId": "123e4567-e89b-12d3-a456-426614174000"
}
```

### **Bulk Create Sub-Clients**
```json
{
  "parentClientId": "123e4567-e89b-12d3-a456-426614174000",
  "subClients": [
    {
      "name": "Sub Client 1",
      "description": "First sub client",
      "maxUsers": 50,
      "maxStorage": 536870912
    },
    {
      "name": "Sub Client 2",
      "description": "Second sub client",
      "maxUsers": 25,
      "maxStorage": 268435456
    }
  ]
}
```

## ⚡ **Performance Tips**

1. **Use specific filters** - Always include `isActive=true` for better performance
2. **Limit results** - Use pagination (`page` & `limit`) for large datasets
3. **Use hierarchy filters** - `onlyParentClients`, `onlyStandalone`, `onlyRootClients` are optimized
4. **Combine filters** - Multiple filters work together efficiently

## 🛠 **Implementation Details**

### **Controller Usage**
```go
func (_i *clientsController) All(c *fiber.Ctx) error {
    paginate, err := paginator.Paginate(c)
    if err != nil {
        return err
    }

    reqContext := request.ClientsQueryRequestContext{
        Name:              c.Query("name"),
        ClientType:        c.Query("clientType"),
        ParentClientId:    c.Query("parentClientId"),
        IncludeSubClients: c.Query("includeSubClients"),
        OnlyParentClients: c.Query("onlyParentClients"),
        OnlyStandalone:    c.Query("onlyStandalone"),
        OnlyRootClients:   c.Query("onlyRootClients"),
        IsActive:          c.Query("isActive"),
        CreatedById:       c.Query("createdById"),
    }
    req := reqContext.ToParamRequest()
    req.Pagination = paginate

    clientsData, paging, err := _i.clientsService.All(req)
    // ... rest of implementation
}
```

## ✅ **Testing (camelCase)**

### **Test Cases**
```bash
# Test basic filtering
curl "http://localhost:8080/api/clients?name=test&isActive=true"

# Test hierarchy filtering  
curl "http://localhost:8080/api/clients?onlyParentClients=true"

# Test pagination
curl "http://localhost:8080/api/clients?page=1&limit=5"

# Test sorting
curl "http://localhost:8080/api/clients?sort=name&sort_by=asc"

# Test complex filtering
curl "http://localhost:8080/api/clients?clientType=sub_client&isActive=true&page=1&limit=10"
```

## 🔄 **Migration from snake_case**

### **Before (snake_case)**
```bash
GET /api/clients?client_type=parent_client&parent_client_id=uuid&is_active=true
```

### **After (camelCase)**
```bash
GET /api/clients?clientType=parent_client&parentClientId=uuid&isActive=true
```

### **Request Body Migration**
```json
// Before
{
  "client_type": "parent_client",
  "parent_client_id": "uuid",
  "max_users": 100,
  "max_storage": 1073741824
}

// After
{
  "clientType": "parent_client",
  "parentClientId": "uuid", 
  "maxUsers": 100,
  "maxStorage": 1073741824
}
```

---

## 🎉 **Ready to Use!**

`ClientsQueryRequestContext` sekarang sudah terintegrasi dengan:
- ✅ Controller parsing (camelCase)
- ✅ Repository filtering  
- ✅ Swagger documentation (camelCase)
- ✅ Type safety dengan UUID parsing
- ✅ Boolean conversion
- ✅ Pagination support
- ✅ **Full camelCase JSON support**

Semua query parameters dan response fields menggunakan camelCase format! 🚀