nabeh/implementation_plan.md

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

• 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

• 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

• 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

• 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

• 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

• 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.