perling/docs/user-management.md

# User Management System

Sistem manajemen pengguna untuk aplikasi Perling dengan fitur CRUD lengkap dan integrasi role-based access control.

## 🚀 Fitur

### ✅ Manajemen Pengguna

-   **View (Index)**: Daftar semua pengguna dengan pagination
-   **Create**: Tambah pengguna baru dengan role assignment
-   **Show**: Detail lengkap pengguna termasuk role dan permissions
-   **Edit**: Update informasi pengguna dan role
-   **Delete**: Hapus pengguna (dengan proteksi untuk user yang sedang login)

### 🔐 Keamanan

-   Password validation dengan requirements yang kuat
-   Role-based access control menggunakan Spatie Laravel Permission
-   Proteksi CSRF untuk semua form
-   Validasi unique untuk email dan username
-   Proteksi penghapusan akun sendiri

## 📋 Endpoints

| Method | Route                      | Action               | Permission Required |
| ------ | -------------------------- | -------------------- | ------------------- |
| GET    | `/admin/users`             | Daftar pengguna      | `settings.manage`   |
| GET    | `/admin/users/create`      | Form tambah pengguna | `settings.manage`   |
| POST   | `/admin/users`             | Simpan pengguna baru | `settings.manage`   |
| GET    | `/admin/users/{user}`      | Detail pengguna      | `settings.manage`   |
| GET    | `/admin/users/{user}/edit` | Form edit pengguna   | `settings.manage`   |
| PUT    | `/admin/users/{user}`      | Update pengguna      | `settings.manage`   |
| DELETE | `/admin/users/{user}`      | Hapus pengguna       | `settings.manage`   |

## 🎯 Validasi

### Create User

```php
'name' => 'required|string|max:255',
'email' => 'required|email|unique:users',
'username' => 'required|string|unique:users',
'password' => 'required|min:8|confirmed|regex:/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[^A-Za-z0-9]).{8,}$/',
'roles' => 'array|exists:roles,name'
```

### Update User

```php
'name' => 'required|string|max:255',
'email' => 'required|email|unique:users,email,{user_id}',
'username' => 'required|string|unique:users,username,{user_id}',
'password' => 'nullable|min:8|confirmed|regex:/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[^A-Za-z0-9]).{8,}$/',
'roles' => 'array|exists:roles,name'
```

## 🗂️ File Structure

```
app/Http/Controllers/Admin/
└── UserController.php              # Controller utama

resources/views/admin/users/
├── index.blade.php                 # Daftar pengguna
├── create.blade.php                # Form tambah pengguna
├── edit.blade.php                  # Form edit pengguna
└── show.blade.php                  # Detail pengguna

resources/views/layouts/
└── app.blade.php                   # Layout utama

database/seeders/
└── UserManagementSeeder.php        # Seeder untuk data awal
```

## 🎨 UI Components

### Index Page

-   Tabel responsif dengan pagination
-   Badge untuk menampilkan role
-   Action buttons (View, Edit, Delete)
-   Modal konfirmasi untuk delete
-   Alert untuk feedback

### Create/Edit Forms

-   Form validation dengan error display
-   Password strength requirements
-   Role selection dengan checkbox
-   Responsive layout (2 kolom)

### Show Page

-   Informasi lengkap pengguna
-   Role dan permissions display
-   Activity summary cards
-   Action buttons

## 🔧 Setup & Installation

### 1. Run Migrations

```bash
php artisan migrate
```

### 2. Run Seeders

```bash
php artisan db:seed
```

### 3. Default Users

Sistem sudah memiliki user default dari UserSeeder:

-   **ammar@dinaslhdki.id** (role: DLH) - Super admin dengan akses penuh
-   **kadis@dinaslhdki.id** (role: Kadis) - Management level access
-   **ppkl@dinaslhkdki.id** (role: PPKL) - Operational level access

Password sesuai dengan yang sudah dikonfigurasi di UserSeeder.

## 🚀 Usage Examples

### Akses User Management

1. Login sebagai user dengan role DLH (ammar@dinaslhdki.id)
2. Klik menu "Pengaturan" → "Manajemen Pengguna"
3. Atau akses langsung: `/admin/users`

### Tambah User Baru

1. Klik tombol "Tambah Pengguna"
2. Isi form dengan data lengkap
3. Pilih role yang sesuai
4. Klik "Simpan"

### Edit User

1. Dari daftar user, klik tombol "Edit" (ikon pensil)
2. Update informasi yang diperlukan
3. Password bisa dikosongkan jika tidak ingin diubah
4. Klik "Perbarui"

### Hapus User

1. Klik tombol "Hapus" (ikon trash)
2. Konfirmasi di modal yang muncul
3. User akan dihapus permanent

## 🔒 Security Features

### Password Requirements

-   Minimal 8 karakter
-   Harus mengandung huruf besar
-   Harus mengandung huruf kecil
-   Harus mengandung angka
-   Harus mengandung simbol khusus

### Access Control

-   Hanya user dengan permission `settings.manage` yang bisa akses
-   User tidak bisa menghapus akun sendiri
-   CSRF protection pada semua form
-   Input validation dan sanitization

### Role Management

-   Role assignment saat create/edit user
-   Multiple role support
-   Permission inheritance dari role
-   Real-time role sync

## 🐛 Troubleshooting

### Common Issues

**Permission Denied**

-   Pastikan user memiliki permission `settings.manage`
-   Check role assignment di database

**Validation Errors**

-   Email/username sudah digunakan
-   Password tidak memenuhi requirements
-   Role tidak valid

**Layout Issues**

-   Pastikan Bootstrap CSS/JS ter-load
-   Check Lucide icons script
-   Verify Vite assets compiled

### Debug Commands

```bash
# Check user permissions
php artisan tinker
>>> $user = User::find(1);
>>> $user->getAllPermissions();

# Reset permissions
php artisan permission:cache-reset

# Re-run seeders
php artisan db:seed --class=UserManagementSeeder
```

## 📈 Future Enhancements

-   [ ] Bulk user operations
-   [ ] User import/export
-   [ ] Advanced filtering dan search
-   [ ] User activity logging
-   [ ] Email verification workflow
-   [ ] Password reset functionality
-   [ ] User profile pictures
-   [ ] Two-factor authentication