# API Create Client + User

## 🎯 **Overview**

API ini memungkinkan pembuatan Client dan Admin User dalam satu panggilan API. **Endpoint ini bersifat PUBLIC** dan tidak memerlukan authentication. Sangat berguna untuk setup awal sistem multi-tenant atau ketika perlu membuat client baru dengan admin user secara bersamaan.

## 🚀 **Endpoint**

```
POST /api/clients/with-user
```

## 📋 **Request Structure**

### **Headers**
```
Content-Type: application/json
```

### **Request Body**
```json
{
  "clientName": "string (required)",
  "clientDescription": "string (optional)",
  "clientType": "string (required) - oneof: parent_client, sub_client, standalone",
  "parentClientId": "string (optional) - UUID format",
  "maxUsers": "integer (optional)",
  "maxStorage": "integer (optional) - in bytes",
  "adminUser": {
    "username": "string (required)",
    "email": "string (required) - email format",
    "fullname": "string (required)",
    "password": "string (required) - min 8 characters",
    "address": "string (optional)",
    "phoneNumber": "string (optional)",
    "workType": "string (optional)",
    "genderType": "string (optional)",
    "identityType": "string (optional)",
    "identityGroup": "string (optional)",
    "identityGroupNumber": "string (optional)",
    "identityNumber": "string (optional)",
    "dateOfBirth": "string (optional)",
    "lastEducation": "string (optional)",
    "userRoleId": "integer (required)",
    "userLevelId": "integer (required)"
  }
}
```

## 📊 **Response Structure**

### **Success Response (200)**
```json
{
  "success": true,
  "messages": ["Client and admin user created successfully"],
  "data": {
    "client": {
      "id": "uuid",
      "name": "string",
      "description": "string",
      "clientType": "string",
      "parentClientId": "string",
      "maxUsers": "integer",
      "maxStorage": "integer",
      "isActive": "boolean",
      "createdAt": "datetime"
    },
    "adminUser": {
      "id": "integer",
      "username": "string",
      "email": "string",
      "fullname": "string",
      "address": "string",
      "phoneNumber": "string",
      "workType": "string",
      "genderType": "string",
      "identityType": "string",
      "identityGroup": "string",
      "identityGroupNumber": "string",
      "identityNumber": "string",
      "dateOfBirth": "string",
      "lastEducation": "string",
      "userRoleId": "integer",
      "userLevelId": "integer",
      "clientId": "string",
      "statusId": "integer",
      "isActive": "boolean",
      "createdAt": "datetime"
    },
    "message": "Client and admin user created successfully"
  }
}
```

### **Error Response (400/500)**
```json
{
  "success": false,
  "messages": ["Error message"],
  "code": 400
}
```

## 🔧 **Usage Examples**

### **1. Create Standalone Client with Admin User**

```bash
curl -X POST "http://localhost:8080/api/clients/with-user" \
  -H "Content-Type: application/json" \
  -d '{
    "clientName": "Acme Corporation",
    "clientDescription": "A leading technology company",
    "clientType": "standalone",
    "maxUsers": 100,
    "maxStorage": 1073741824,
    "adminUser": {
      "username": "admin_acme",
      "email": "admin@acme.com",
      "fullname": "John Doe",
      "password": "SecurePass123",
      "address": "123 Tech Street, Silicon Valley",
      "phoneNumber": "+1-555-0123",
      "workType": "Full-time",
      "genderType": "Male",
      "identityType": "Passport",
      "identityNumber": "P123456789",
      "dateOfBirth": "1985-06-15",
      "lastEducation": "Master Degree",
      "userRoleId": 1,
      "userLevelId": 1
    }
  }'
```

### **2. Create Sub Client with Admin User**

```bash
curl -X POST "http://localhost:8080/api/clients/with-user" \
  -H "Content-Type: application/json" \
  -d '{
    "clientName": "Acme Branch Office",
    "clientDescription": "Branch office in New York",
    "clientType": "sub_client",
    "parentClientId": "550e8400-e29b-41d4-a716-446655440000",
    "maxUsers": 50,
    "maxStorage": 536870912,
    "adminUser": {
      "username": "admin_branch",
      "email": "admin@branch.acme.com",
      "fullname": "Jane Smith",
      "password": "BranchPass123",
      "address": "456 Business Ave, New York",
      "phoneNumber": "+1-555-0456",
      "workType": "Full-time",
      "genderType": "Female",
      "identityType": "Driver License",
      "identityNumber": "DL987654321",
      "dateOfBirth": "1990-03-22",
      "lastEducation": "Bachelor Degree",
      "userRoleId": 2,
      "userLevelId": 2
    }
  }'
```

### **3. Create Parent Client with Admin User**

```bash
curl -X POST "http://localhost:8080/api/clients/with-user" \
  -H "Content-Type: application/json" \
  -d '{
    "clientName": "Global Enterprise",
    "clientDescription": "Global enterprise with multiple branches",
    "clientType": "parent_client",
    "maxUsers": 1000,
    "maxStorage": 10737418240,
    "adminUser": {
      "username": "super_admin",
      "email": "superadmin@global.com",
      "fullname": "Robert Johnson",
      "password": "SuperSecure123",
      "address": "789 Corporate Blvd, Global City",
      "phoneNumber": "+1-555-0789",
      "workType": "Full-time",
      "genderType": "Male",
      "identityType": "Passport",
      "identityNumber": "P987654321",
      "dateOfBirth": "1980-12-10",
      "lastEducation": "PhD",
      "userRoleId": 1,
      "userLevelId": 1
    }
  }'
```

## 📝 **Field Descriptions**

### **Client Fields**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `clientName` | string | ✅ | Nama client |
| `clientDescription` | string | ❌ | Deskripsi client |
| `clientType` | string | ✅ | Tipe client: `parent_client`, `sub_client`, `standalone` |
| `parentClientId` | string | ❌ | UUID parent client (untuk sub_client) |
| `maxUsers` | integer | ❌ | Maksimal jumlah user |
| `maxStorage` | integer | ❌ | Maksimal storage dalam bytes |

### **Admin User Fields**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `username` | string | ✅ | Username untuk login |
| `email` | string | ✅ | Email address (format email) |
| `fullname` | string | ✅ | Nama lengkap |
| `password` | string | ✅ | Password (min 8 karakter) |
| `address` | string | ❌ | Alamat |
| `phoneNumber` | string | ❌ | Nomor telepon |
| `workType` | string | ❌ | Tipe pekerjaan |
| `genderType` | string | ❌ | Jenis kelamin |
| `identityType` | string | ❌ | Tipe identitas |
| `identityGroup` | string | ❌ | Grup identitas |
| `identityGroupNumber` | string | ❌ | Nomor grup identitas |
| `identityNumber` | string | ❌ | Nomor identitas |
| `dateOfBirth` | string | ❌ | Tanggal lahir |
| `lastEducation` | string | ❌ | Pendidikan terakhir |
| `userRoleId` | integer | ✅ | ID role user |
| `userLevelId` | integer | ✅ | ID level user |

## 🔒 **Authentication & Authorization**

- **Required**: None (Public endpoint)
- **Permission**: No authentication required
- **Access**: Anyone can create a client and admin user

## ⚠️ **Error Handling**

### **Common Error Scenarios**

1. **Invalid Request Body (400)**
   ```json
   {
     "success": false,
     "messages": ["Invalid request body"],
     "code": 400
   }
   ```

2. **Validation Failed (400)**
   ```json
   {
     "success": false,
     "messages": ["Key: 'ClientWithUserCreateRequest.AdminUser.Email' Error:Field validation for 'Email' failed on the 'email' tag"],
     "code": 400
   }
   ```

3. **User Creation Failed (500)**
   ```json
   {
     "success": false,
     "messages": ["failed to create admin user: username already exists"],
     "code": 500
   }
   ```

4. **Invalid Parent Client ID (500)**
   ```json
   {
     "success": false,
     "messages": ["invalid parent client ID: invalid UUID length: 5"],
     "code": 500
   }
   ```

## 🎯 **Business Logic**

### **Process Flow**
1. **Validate Request** menggunakan struct validation
2. **Generate Client ID** menggunakan UUID
3. **Parse Parent Client ID** jika ada
4. **Create Client Entity** dengan data yang diberikan
5. **Create Admin User Entity** dengan client ID yang baru
6. **Save User** menggunakan existing repository
7. **Update Client** dengan created user ID
8. **Return Response** dengan data client dan user

### **Data Relationships**
- **Client** → **Admin User**: One-to-One relationship
- **Parent Client** → **Sub Client**: One-to-Many relationship

## 🔧 **Implementation Notes**

### **Current Limitations**
- **TODO**: Client repository belum diimplementasi (simulasi saja)
- **TODO**: Keycloak integration untuk user creation
- **TODO**: Transaction rollback jika user creation gagal
- **Public Endpoint**: Tidak ada authentication, semua orang bisa akses

### **Future Enhancements**
- Implementasi client repository yang sesungguhnya
- Integration dengan Keycloak untuk user management
- Transaction management untuk data consistency
- Email notification untuk admin user
- Bulk client creation
- Rate limiting untuk public endpoint
- CAPTCHA untuk mencegah abuse

## 📚 **Related APIs**

- `POST /api/users` - Create individual user
- `POST /api/clients` - Create individual client
- `GET /api/clients` - List all clients
- `GET /api/users` - List all users

## 🎉 **Summary**

API ini memberikan kemudahan untuk:
- ✅ **Single API Call**: Membuat client dan admin user sekaligus
- ✅ **Public Access**: Tidak memerlukan authentication
- ✅ **Data Consistency**: Memastikan relasi client-user terhubung dengan benar
- ✅ **Flexible Configuration**: Mendukung berbagai tipe client
- ✅ **Comprehensive Validation**: Validasi lengkap untuk semua field
- ✅ **Detailed Response**: Response yang informatif dengan data lengkap

Perfect untuk setup awal sistem multi-tenant dengan akses public! 🚀