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

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

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

web — تطبيق Next.js يوفّر واجهة المستخدم ولوحات المعلومات ومسارات API
auth — تسجيل الدخول عبر OTP بالبريد الإلكتروني وتهيئة الوكلاء على نطاق المصادقة
sql-api — دالة AWS Lambda تعمل خلف API Gateway لخدمة العملاء الآليين
worker — عامل يجلب أسعار الصرف اليومية من ECB وCBR وNBS
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.

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