# Implementation Plan - Intaleq Customer Service & Driver Registration Flow

This plan details the implementation of the Intaleq customer service prompt template, the multi-stage WhatsApp driver registration flow using Gemini OCR, and the authenticated REST API endpoints for Nabeh's backend.

## User Review Required

> [!IMPORTANT]
> - **API Key Configuration**: We will authenticate the REST endpoints using a shared `ENTALEQ_API_KEY` defined in the `.env` file. Please ensure this environment variable is populated on your environment before calling these endpoints.
> - **Direct Upload Path**: Decoded WhatsApp images will be saved under the public directory `backend/public/uploads/documents/` to ensure they are accessible via public URL paths.
> - **Prompt Dialect**: The custom service prompt is written in a professional, warm Syrian dialect (اللهجة السورية) adhering to all business rules.

---

## Proposed Changes

### Database Schema Component

#### [NEW] [DriverOcrData.php](file:///Users/hamzaaleghwairyeen/development/App/nabeh/backend/app/Models/DriverOcrData.php)
- Class extending `BaseModel` that manages the `driver_ocr_data` table.
- Dynamically creates the table via `ensureTableExists()`.
- Implements `saveSecure` to encrypt sensitive fields (`phone`, `name`, `password`, and all JSON OCR strings) using AES-256-GCM (`Security::encrypt()`) and generate search hashes (`Security::blindIndex()`).
- Implements `findByPhone` to retrieve and decrypt records.

---

### Gemini Service Component

#### [MODIFY] [GeminiService.php](file:///Users/hamzaaleghwairyeen/development/App/nabeh/backend/app/Services/GeminiService.php)
- Add the `generateOcrFromImage` static method to support custom structured document analysis. It forwards custom prompts (e.g. green card OCR instructions) and base64 inline images to the `gemini-2.0-flash-lite` model.

---

### Dashboard Component

#### [MODIFY] [index.html](file:///Users/hamzaaleghwairyeen/development/App/nabeh/backend/public/index.html)
- Add the new prompt template button: `<button type="button" class="btn btn-secondary" @click="loadPromptTemplate('intaleq')">قالب خدمة عملاء انطلق (سوري)</button>`.
- Add `intaleq` template case inside `loadPromptTemplate(type)` to load the full customer service system instruction prompt.

---

### Conversation Flow Component

#### [NEW] [DriverRegistrationFlow.php](file:///Users/hamzaaleghwairyeen/development/App/nabeh/backend/app/Core/Flows/DriverRegistrationFlow.php)
- Implement a step-by-step driver registration state machine.
- Steps:
  1. `start`: Welcome message, request full name.
  2. `ask_name`: Save name, request password.
  3. `ask_password`: Validate password, request ID Front image.
  4. `id_front`: Run `id_front_sy` Gemini OCR prompt. Request ID Back.
  5. `id_back`: Run `id_back_sy` Gemini OCR prompt. Request Driving License Front.
  6. `driving_license_front`: Run `driving_license_sy_front` Gemini OCR prompt. Request Driving License Back.
  7. `driving_license_back`: Run `driving_license_sy_back` Gemini OCR prompt. Request Vehicle License Front.
  8. `vehicle_license_front`: Run `vehicle_license_sy_front` Gemini OCR prompt. Request Vehicle License Back.
  9. `vehicle_license_back`: Run `vehicle_license_sy_back` Gemini OCR prompt. Request Criminal Record (لا حكم عليه).
  10. `criminal_record`: Save document, update status to `ocr_completed`, save to `driver_ocr_data` table, and conclude.

#### [MODIFY] [ConversationFlowEngine.php](file:///Users/hamzaaleghwairyeen/development/App/nabeh/backend/app/Core/Flows/ConversationFlowEngine.php)
- Add trigger mappings: `'تسجيل' => 'driver_registration_flow'`, `'سجل' => 'driver_registration_flow'`, and `'register' => 'driver_registration_flow'`.
- Register the flow class: `'driver_registration_flow' => DriverRegistrationFlow::class`.

---

### REST API Component

#### [MODIFY] [index.php](file:///Users/hamzaaleghwairyeen/development/App/nabeh/backend/public/index.php)
- Define 2 REST API endpoints:
  - `GET /api/external/driver-ocr`: Accepts a query parameter `phone`. Authenticates against `ENTALEQ_API_KEY`. Retrieves and decrypts driver documents, OCR logs, and password details.
  - `POST /api/external/register-driver`: Accepts a `phone` body parameter. Authenticates against `ENTALEQ_API_KEY`. Marks the local record status as `registered` (confirming transfer to primary DB).

---

## Verification Plan

### Manual Verification
1. Open the dashboard, click **قالب خدمة عملاء انطلق (سوري)**, and verify the prompt loads.
2. Send a WhatsApp message to the bot saying `"تسجيل"` and follow the registration wizard. Send test images for each stage, verifying database storage and Gemini OCR parsing logs.
3. Query the `GET /api/external/driver-ocr` endpoint using `curl` with the header `X-API-Key: your_key` and confirm decrypted data is returned.
4. Execute `POST /api/external/register-driver` with the API key header and confirm the record status updates to `registered`.