# Admin Bulk Upload User - Usage Instructions

## 📌 Brief Overview
This branch (`feat/admin-sub/user-managment-sub/bulk-upload-user`) introduces a robust **Bulk User Import** functionality to the Admin User Management module. This feature enables administrators to import multiple users simultaneously using a CSV file. It handles real-time progress reporting, data validation, and generates a detailed report of any failed records for easy correction. 

## 🎯 Goals & What You Get After Merging
By merging this branch with the `feat/admin` and `base` branches, you will get:
1. **Bulk Upload Modal**: A new UI component in the User Management page to upload CSV files.
2. **Sample CSV Download**: Users can download a pre-formatted sample CSV file (`example-user-upload.csv`) to understand the required data structure.
3. **Real-time Import Progress**: The import process streams progress back to the UI (using `application/x-ndjson`), giving the user live feedback on the number of processed, imported, and failed rows.
4. **Data Validation**: Validates user details such as required headers (`first_name`, `last_name`, `email`), unique emails, and valid phone formats.
5. **Failure Reporting**: Any rows that fail validation are captured and can be downloaded as a separate CSV (`failed-user-upload-[timestamp].csv`) containing an extra `failure_reason` column to help the admin easily identify and correct mistakes.

## 🚀 How It Works & How to Use It

1. **Navigate to User Management**: Log in to the admin panel and go to the User Management section.
2. **Open Bulk Upload Modal**: Click on the "Bulk Upload" (or Import) button which opens the bulk upload modal.
3. **Download Sample**: If you don't have the format, click on the download sample button inside the modal.
4. **Prepare CSV**:
    - **Required Columns**: `first_name`, `last_name`, `email`.
    - **Optional Columns**: `phone`, `status`, `send_invitation`.
    - **Note**: Maximum 500 records are allowed per upload.
5. **Upload & Process**: Select your CSV file and start the upload. The UI will show a real-time progress bar.
6. **Review Results**: Once completed, the system will show the total imported and failed records. If there are failed records, a button will appear allowing you to download the failed CSV file for review.

## 📂 Key Files & Paths Modifed/Added

- **Services**:
  - `app/Services/Admin/UserBulkImportService.php`: The core service handling the CSV parsing, data normalization, row-by-row validation, DB insertion, and progress emission.
- **Controllers**:
  - `app/Http/Controllers/Admin/User/UserManagementController.php`: Updated with endpoints for `bulkUpload`, `downloadBulkUploadSample`, and `downloadBulkUploadFailed`.
- **Requests Validation**:
  - `app/Http/Requests/Admin/User/BulkUserImportRequest.php`: Validates the uploaded CSV file itself (e.g., mime types, file size).
- **Exports/Imports (Excel)**:
  - `App\Exports\FailedUsersBulkExport`: Generates the failed records CSV.
  - `App\Exports\UserBulkSampleExport`: Generates the sample CSV.
  - `App\Imports\UsersBulkCsvImport`: Reads the CSV into collections.
- **Views & UI**:
  - `resources/views/pages/admin/users/partials/bulk-upload-modal.blade.php`: The Blade partial for the bulk upload interface.
  - `resources/views/components/tables/bulk-actions.blade.php`: Updated with the import trigger buttons.
- **Javascript**:
  - `resources/js/admin/user-management.js`: Handles the AJAX chunking/streaming (`application/x-ndjson`) and modal interactions.
- **Routes**:
  - `routes/admin.php`: New routes added for `/users/bulk-upload`, `/users/bulk-upload/sample`, and `/users/bulk-upload/failed/{token}`.
- **Language**:
  - `lang/en/pages/admin/users.php`: Localization strings for bulk upload feedback and validation messages.

## 🛠️ Important Technical Features
- **Streamed Responses (NDJSON)**: We used streamed responses to keep the frontend updated during large file processes without timing out.
- **Cache-based Failed Exports**: Failed rows are cached using a unique UUID token for 1 hour so they can be downloaded efficiently without clogging up the storage.