README_ar.md

واجهة برمجة التطبيقات لقراءات عدادات المياه والكهرباء

🌐

هذه واجهة برمجة تطبيقات لإدارة قراءات خدمات مختلفة لعملاء مختلفين. تم بناء التطبيق باستخدام تقنيات Node.js و TypeScript و Prisma و Express.js، لتقديم واجهة خلفية موثوقة وقابلة للتوسع.

📏 الواجهة الأمامية

• 📏 تطبيق Precision (React) - واجهة لقراءات عدادات المياه والكهرباء

🛠️ التقنيات المستخدمة

• Node.js: بيئة تشغيل JavaScript للجانب الخادم.
• TypeScript: مجموعة فوق JavaScript تضيف أنواع ثابتة للكود.
• Express.js: إطار عمل ويب بسيط لـ Node.js.
• Prisma: ORM تجعل الوصول إلى قاعدة البيانات أسهل.
• MySQL: قاعدة البيانات المستخدمة خلال عملية التطوير.
• ESLint: أداة لفحص الكود تساعد في الحفاظ على نظافة المعايير.
• Jest: إطار عمل للاختبار يضمن جودة الكود.
• Mocha: للاختبارات الإضافية.
• Google Generative AI: تم تكاملها لتحليل صور العدادات واستخراج القيم.
• Swagger: تم تكاملها لتوليد وثائق مسارات واجهة برمجة التطبيقات.

📁 هيكل المشروع

يتبع المشروع هيكلًا معياريًا لتسهيل الصيانة والتوسع. الملفات والمجلدات الرئيسية هي كما يلي:

• src/: يحتوي على الكود المصدري للتطبيق.
  • controllers/: منطق التحكم الذي يعالج الطلبات.
  • db/: يولد مثيل Prisma للاتصال بقاعدة البيانات للاستخدام في جميع أنحاء التطبيق.
  • exceptions/: إنشاء استثناءات مخصصة للتعامل مع الأخطاء أثناء تشغيل التطبيق.
  • interfaces/: إنشاء الواجهات والأنواع لإدارة معلمات الدوال وقيم الإرجاع.
  • middlewares/: دوال الوسطاء للتحقق والمعالجة.
  • models/: منطق الاتصال بقاعدة البيانات.
  • services/: طبقة الخدمة التي تتفاعل مع Prisma وتنفذ العمليات التجارية.
  • routes/: تعريف مسارات واجهة برمجة التطبيقات.
  • utils/: وظائف مساعدة مثل معالجة الصور والتفاعل مع Google Generative AI.
  • tests/: اختبارات تلقائية للتحقق من الوظائف.

⚙️ الميزات

• قائمة القراءات: يسمح بعرض جميع القراءات لعميل معين وتصفية النتائج حسب نوع القراءة.
• إدارة الصور: يتم حفظ صور القراءات واسترجاعها باستخدام URL مؤقت، باستخدام تشفير Base64.
• التحقق من المعلمات: يتم استخدام الوسطاء للتحقق من المعلمات المدخلة لضمان تكامل الطلبات.
• تحليل الصور باستخدام Google Generative AI: تقوم واجهة برمجة التطبيقات بتحليل الصور واستخراج القيم الاستهلاكية.

🚀 كيفية تشغيل المشروع

المتطلبات

• Node.js
• Docker (اختياري، لبيئة التطوير)

خطوات التثبيت

1. استنساخ المستودع:

   git clone /~https://github.com/SamuelRocha91/apiShopper.git
   cd apiMeasureWaterAndGas

2. تثبيت التبعيات:

   npm install

3. تكوين متغيرات البيئة:

   • أنشئ ملف .env يحتوي على التكوينات الضرورية.
   • مثال:

     DATABASE_URL="file:./dev.db"
     GEMINI_API_KEY="مفتاح_واجهة_برمجة_التطبيقات_الخاص_بك"
     HOST="http://localhost:3000"

4. تنفيذ ترحيل قاعدة البيانات:

   npx prisma migrate dev

5. بدء تشغيل الخادم:

   npm run dev

Docker

يمكنك تشغيل المشروع باستخدام Docker. يرجى تنفيذ:

docker-compose up --build

🧪 الاختبارات

يتم تنفيذ الاختبارات باستخدام Jest و Mocha. لتشغيل جميع الاختبارات، يرجى تنفيذ:

npm run test

📜 النصوص المتاحة

• start: بدء تشغيل التطبيق.
• dev: بدء تشغيل التطبيق في وضع التطوير.
• build: تحويل كود TypeScript إلى JavaScript.
• lint: تشغيل فحص ESLint للكود.
• lint:fix: تشغيل ESLint وإصلاح المشكلات تلقائيًا.
• prisma:generate: توليد أنواع Prisma.
• prisma:migrate: تنفيذ ترحيل قاعدة البيانات.
• prisma:seed: ملء قاعدة البيانات بالبيانات الأولية.
• docker: تثبيت التبعيات، وتوليد أنواع Prisma، وتنفيذ الترحيل، وبدء تشغيل الخادم.
• test: تشغيل جميع الاختبارات باستخدام Mocha و Jest.

🖼️ إعداد الصور

وظائف مساعدة لحفظ وتوليد عناوين URL للصور:

• saveBase64Image: لحفظ صورة Base64 على الخادم.
• getImageUrl: لتوليد عنوان URL مؤقت للوصول إلى الصورة.
• extractMimeType: لاستخراج نوع MIME من صورة Base64.
• extractSize: لحساب حجم صورة Base64.

🔍 استخدام Google Generative AI لتحليل الصور

تستخدم الدالة checkMeasureValue Google Generative AI لتحليل صورة القراءة واستخراج القيمة الاستهلاكية.

async function checkMeasureValue(mime: string, base64: string): Promise<number> {
  const result = await model.generateContent([
    {
      inlineData: {
        mimeType: mime,
        data: base64
      }
    },
  ]);
  return result.content?.[0]?.text ?? 0;
}

📦 واجهات برمجة التطبيقات الأخرى

• 🏦 [واجهة برمجة تطبيقات إدارة المستخدمين](/~https://github.com/SamuelRocha91/paymentAPI/blob

/main/README.md): إدارة معلومات العملاء.

• 💳 واجهة برمجة تطبيقات الدفع: لإجراء المدفوعات.
• 🛒 واجهة برمجة تطبيقات إدارة المنتجات: إدارة بيانات المنتجات.

⚖️ الترخيص

هذا المشروع مرخص بموجب MIT License.

📞 الاتصال

يمكنك الاتصال بي عبر البريد الإلكتروني: samuelrocha.91@gmail.com.