تسجيل الدخولإنشاء حساب مجانًا

المعمارية

نظرة عامة على النظام، ونموذج البيانات، وآلية دعم العملات المتعددة، ونموذج المصادقة.

نظرة عامة على النظام

واجهة الويب في المتصفح --> تطبيق الويب Next.js ----------------> Postgres (RLS)
العملاء الآليون        --> API Gateway (REST) --> SQL Lambda -------^
عملاء MCP              --> API Gateway (HTTP) --> MCP Lambda -------^
خدمة المصادقة (OTP + OAuth) ---------------------------------------^
العامل (جلب أسعار الصرف) ------------------------------------------^

ستة مكونات، وقاعدة بيانات واحدة:

  1. web — تطبيق Next.js يوفّر واجهة المستخدم ولوحات المعلومات ومسارات API
  2. auth — تسجيل الدخول عبر OTP بالبريد الإلكتروني وتهيئة الوكلاء على نطاق المصادقة
  3. sql-api — دالة AWS Lambda تعمل خلف API Gateway لخدمة العملاء الآليين
  4. mcp — دالة AWS Lambda وHTTP API مخصّصتان في API Gateway لنقطة MCP المستضافة
  5. worker — عامل يجلب أسعار الصرف اليومية من ECB وCBR وNBS
  6. Postgres — المصدر الوحيد للحقيقة مع أمان على مستوى الصفوف

نموذج البيانات

  • ledger_entries — صف واحد لكل حركة على الحساب، مثل الدخل أو الإنفاق أو التحويل
  • budget_lines — خلايا الميزانية تُسجَّل بنمط الإضافة فقط، مع اعتماد آخر كتابة عند القراءة
  • budget_comments — ملاحظات مرتبطة بخلايا الميزانية وتُحفَظ بنمط الإضافة فقط
  • workspace_settings — عملة التقارير وإعدادات مساحة العمل
  • account_metadata — بيانات وصفية لكل حساب مثل تصنيف السيولة
  • exchange_rates — أسعار صرف يومية تُستخدم للتحويل وقت الاستعلام
  • workspaces / workspace_members — عزل متعدد المستأجرين
  • accounts — عرض مشتق من ledger_entries

العملات المتعددة

تُخزَّن جميع المبالغ بعملتها الأصلية. ويجري التحويل إلى عملة التقارير وقت القراءة عبر عمليات ربط SQL مع exchange_rates. ولا توجد أي عملية تحويل مسبقة قد تؤدي إلى فقدان الدقة.

المصادقة

يوجد وضعان عبر متغير البيئة AUTH_MODE:

  • none — من دون مصادقة، مع مساحة عمل محلية واحدة
  • cognito — تسجيل دخول بلا كلمة مرور عبر OTP يُرسل إلى البريد الإلكتروني باستخدام AWS Cognito، مع تسجيل مفتوح

بالنسبة إلى العملاء الآليين، تكون نقطة الاكتشاف العامة هي GET /v1/. وتبدأ تهيئة الوكيل عبر OTP بالبريد الإلكتروني على نطاق المصادقة، ثم تعيد مفتاح ApiKey طويل العمر، وبعد ذلك تُنفَّذ استعلامات SQL عبر واجهة العملاء الآليين خلف API Gateway.

يتصل عملاء MCP بشكل منفصل بـ https://mcp.expense-budget-tracker.com/mcp. وتتولى HTTP API مخصّصة في API Gateway ودالة MCP Lambda هذا المسار، بينما يتم التصريح التفاعلي عبر OAuth في المتصفح على نطاق المصادقة.

يحصل كل مستخدم على مساحة عمل معزولة. وتتحقق سياسات RLS من العضوية في كل استعلام، بما في ذلك طلبات SQL الواردة من العملاء الآليين.