التوثيق — كيف يعمل
آخر تحديث: 6 أغسطس 2026
تمت ترجمة هذه الصفحة آليًا لتسهيل قراءتها. في حال وجود أي تباين، فإن النسخة الفرنسية فقط هي التي تتمتع بالحجية القانونية.
1. نظرة عامة على التدفق
يُنشئ منظّم مسجّل الدخول موعدًا، ثم يُرسل إلى ضيف عبر رابط عام فريد. لا يحتاج الضيف إلى أي حساب: فهو يردّ من صفحة عامة، ويظهر الرد فورًا على لوحة تحكم المنظّم.
المنظّم (مسجّل الدخول)
└─ ينشئ موعدًا ──▶ appointments (status = pending، تم إنشاء invite_token)
├─ «الإرسال عبر البريد الإلكتروني» ──▶ دالة الخادم sendInviteEmail ──▶ Resend
└─ «نسخ الرابط» ──▶ /invite/<token>
الضيف (بدون حساب)
└─ يفتح /invite/<token> ──▶ RPC get_invite(_token) (قراءة عامة مُفلترة)
└─ قبول / رفض ──▶ RPC respond_to_invite(_token, _accept, _message)
└─ status = accepted | declined، responded_at = now()
المنظّم
└─ لوحة التحكم: شارة الحالة، تاريخ الرد، رسالة الضيف، الإحصاءات2. محتوى رسالة الدعوة
تُصاغ الرسالة على جانب الخادم في الدالة sendInviteEmail وتُرسل عبر Resend. المرسل: قيمة RESEND_FROM (الافتراضي «Cadence <onboarding@resend.dev>»). الموضوع: «موعد: {{title}}».
بنية النص، بالترتيب:
- عنوان «اقتراح موعد».
- تحية «مرحبًا {{guestName}}،».
- قسم رسالة مخصصة (لمنظّمي Business فقط).
- عنوان الموعد بخط عريض، ثم التاريخ والوقت منسّقين حسب اللغة.
- الموقع والوصف، يظهر كل منهما فقط عند تعبئته.
- زر إجراء أخضر «تأكيد أو رفض» يشير إلى رابط الدعوة.
- تذكير بالرابط بنص عادي، لعملاء البريد التي تحظر الأزرار.
- قسم «تقييمات Google» (Business): اسم النشاط التجاري، التقييم، رابط التقييمات، رابط Maps.
يتم تحويل جميع القيم الديناميكية إلى ترميز HTML آمن قبل إدراجها: لا يمكن لأي محتوى يُدخله المنظّم حقن أكواد في الرسالة.
المتغيرات المتاحة
| المتغير | المصدر | الاستخدام |
|---|---|---|
| {{guestName}} | contacts.name | سطر التحية «مرحبًا {{guestName}}،». فارغ إذا لم تكن هناك جهة اتصال مرتبطة. |
| {{title}} | appointments.title | موضوع الرسالة «موعد: {{title}}» والعنوان بخط عريض في النص. |
| {{dateRange}} | appointments.starts_at / ends_at | منسّق حسب اللغة: «الثلاثاء 12 أغسطس، 15:00 → 15:30» (Intl.DateTimeFormat). |
| {{location}} | appointments.location | سطر «الموقع: …». يُحذف القسم بالكامل إذا كان الحقل فارغًا. |
| {{description}} | appointments.description | فقرة نصية حرة تظهر أسفل التاريخ. تُحذف إذا كانت فارغة. |
| {{inviteLink}} | origin + /invite/ + appointments.invite_token | زر «تأكيد أو رفض» + تذكير بالرابط كنص عادي أسفل الرسالة (للنسخ واللصق). |
| {{inviteMessage}} | profiles.invite_message (Business) | قسم أخضر برسالة مخصصة، يظهر فقط لمنظّم Business. |
| {{businessName}} / {{googleRating}} / {{googleReviewUrl}} / {{googleMapsUrl}} | profiles.* (Business) | قسم «تقييمات Google» في تذييل الرسالة وعلى صفحة الدعوة، إذا كان الخيار مفعّلًا. |
الحالات التي لا يكتمل فيها الإرسال
- no_email : لا تملك جهة الاتصال عنوان بريد إلكتروني. يجب على المنظّم نسخ الرابط وإرساله عبر قناة أخرى.
- no_api_key : مفتاح الإرسال غير مُهيأ. يُعاد رابط الدعوة مع ذلك إلى الواجهة للنسخ اليدوي.
- provider_error : رفض من مزوّد البريد الإلكتروني (عنوان غير صالح، نطاق غير موثّق…). تبقى حالة الموعد دون تغيير.
- في حال النجاح، يُختم invite_sent_at بطابع زمني: يغذّي هذا الحقل تتبّع «الروابط المُرسلة» في الإحصاءات.
3. شاشات التأكيد (صفحة /invite/<token>)
صفحة عامة، دون مصادقة، تُعرض من الدالة الآمنة get_invite التي لا تُعيد سوى الحقول اللازمة للعرض.
- جارٍ التحميل : هيكل متحرك (تقويم) ريثما يصل الرد.
- رابط غير صالح أو منتهي الصلاحية : رسالة خطأ؛ لا يُكشف عن أي معلومة بخصوص المنظّم أو الموعد.
- حالة «قيد الانتظار» : الموضوع، التاريخ والوقت، المدة، الموقع، اسم المنظّم، رسالة مخصصة (Business)، حقل نصي حر اختياري (500 حرف كحد أقصى)، ثم زرّان «أقبل» و«أرفض».
- بعد القبول : شارة خضراء «مقبول»، تأكيد على الشاشة، تذكير بالمعلومات العملية وقسم تقييمات Google إذا كان المنظّم على خطة Business.
- بعد الرفض : شارة حمراء «مرفوض»، رسالة تفيد بأن المنظّم قد أُبلغ؛ يمكن للضيف إعادة فتح الرابط وتغيير رده طالما لم يُلغَ الموعد.
- موعد ملغى : لم يعد لأزرار الرد أي تأثير، وتبقى الحالة المعروضة «ملغى».
تُقتطع الرسالة الحرة التي يُدخلها الضيف إلى 500 حرف من جانب العميل و1000 حرف من جانب قاعدة البيانات، ثم تُعرض للمنظّم في سجل الموعد.
4. حالات المواعيد
| الحالة | التسمية | المُحفّز | الأثر |
|---|---|---|---|
| pending | قيد الانتظار | عند إنشاء الموعد (القيمة الافتراضية في قاعدة البيانات). | الرابط نشط، يمكن للضيف الرد. يُحتسب ضمن «الردود المتوقعة». |
| accepted | مقبول | ينقر الضيف على «أقبل» — استدعاء respond_to_invite(_accept = true). | تُملأ responded_at وresponse_message؛ شارة خضراء على لوحة التحكم. |
| declined | مرفوض | ينقر الضيف على «أرفض» — respond_to_invite(_accept = false). | نفس التسجيل الخاص بالقبول، شارة حمراء. تبقى الفترة الزمنية مرئية للمتابعة. |
| cancelled | ملغى | إجراء من المنظّم من لوحة تحكمه. | لم يعد الرابط يقبل أي رد (يقوم respond_to_invite بتحديث الحالات الأخرى فقط). |
5. التدفق على جانب الخادم
- الإنشاء / التعديل / الحذف : يقوم بها العميل المصادق عليه؛ يُضمن عزل البيانات بواسطة قواعد الوصول إلى قاعدة البيانات.
- sendInviteEmail: دالة خادم محمية. تعيد تحميل الموعد بتصفيته وفق معرّف مقدّم الطلب، وترفض إذا لم يكن الموعد ملكه، وتُنشئ الرسالة، وتستدعي Resend ثم تختم الإرسال بطابع زمني.
- get_invite(_token): دالة قاعدة بيانات بصلاحيات مرتفعة، وهي الطريق الوحيد للقراءة العامة. لا تُعيد سوى حقول العرض، وتُخفي معلومات العلامة التجارية عن المنظّم غير المشترك في Business.
- respond_to_invite(_token, _accept, _message): تُحدّث الحالة والرسالة والطابع الزمني للرد. تعمل فقط على السطر المطابق للرمز المميز وتتجاهل المواعيد الملغاة.
- get_plan_usage(): تُعيد الخطة، واستهلاك الشهر، ومؤشر المسؤول لعرض الحصص.
6. منطق التفويض
- المنظّم : وصول كامل بالقراءة والكتابة إلى جهات اتصاله ومواعيده الخاصة فقط.
- الضيف غير المسجّل الدخول : لا وصول مباشر إلى الجداول. لا يمكنه سوى قراءة موعد عبر رمزه المميز والرد عليه. الرمز عشوائي (36 حرفًا سداسي عشري) ولا يمنح الوصول إلى أي شيء آخر.
- الأدوار : مخزّنة في جدول مخصص (مستخدم، مشرف، مسؤول) ويتم التحقق منها على جانب الخادم؛ لا تُقرأ أبدًا من المتصفح لمنح صلاحية.
- المسؤول : الوصول إلى منطقة /admin (جميع الحسابات وجهات الاتصال والمواعيد) والإعفاء من حصص خطة Free-mium.
- الخطة : لا يمكن فرض تغيير المستوى من جانب العميل؛ فقط عملية الدفع عبر Stripe أو أحد المسؤولين يمكنهما تعديلها.
- الحصص : مُطبّقة في قاعدة البيانات قبل كل إنشاء — 10/15 (Free-mium)، 30/50 (Basic)، 50/100 (Standard)، 250/500 (Economic) جهة اتصال/موعد في الشهر التقويمي، غير محدود في Business وللمسؤولين.
7. قائمة تحقق لفريق التحرير
- تعديل نص رسالة: العمل على قالب HTML الخاص بدالة الإرسال، وليس على صفحة الدعوة.
- تعديل شاشة تأكيد: العمل على صفحة الدعوة العامة.
- يجب أن يأتي أي متغير جديد من حقل مكشوف مسبقًا بواسطة دالة القراءة العامة.
- عدم عرض بيانات موعد آخر أو جهة اتصال أخرى على الصفحة العامة أبدًا.
- اختبار الحالات الثلاث دائمًا: قيد الانتظار، مقبول، مرفوض.