79 lines
4.9 KiB
Markdown
79 lines
4.9 KiB
Markdown
# 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`.
|