التقويم
يتضمن Libre WebUI تقويمًا شخصيًا. يحصل كل مستخدم مسجل الدخول على عرضيه الشهري والأسبوعي مع أحداث منفردة ومتكررة، كما تعرض الأتمتة المجدولة تكراراتها المقبلة وسجل تشغيلها على الشبكة نفسها.
الأحداث
للحدث عنوان وملاحظات اختيارية ووقت بدء ووقت انتهاء اختياري وعلامة لليوم كله وقاعدة تكرار اختيارية. وتُشفّر العناوين والملاحظات وهي مخزنة بالغلاف نفسه المستخدم للمحادثات والملاحظات.
يستخدم التكرار نموذج المشغّل المشترك:
| النوع | الحقول | المعنى |
|---|---|---|
once | at | تكرار واحد |
hourly | minute, startHour?, endHour? | كل ساعة ضمن نافذة |
daily | hour, minute | كل يوم في وقت محلي معين |
weekly | dayOfWeek, hour, minute | كل أسبوع في يوم مختار |
monthly | dayOfMonth, hour, minute | كل شهر في يوم مختار |
yearly | month, dayOfMonth, hour, minute | كل سنة في تاريخ مختار |
يُخزن الحدث المتكرر مرة واحدة. وتوسعه استعلامات النطاق على الخادم؛ إذ يحمل كل تكرار معروض baseEventId يشير إلى حدثه المصدر، ولذلك يحدث تعديل المصدر كل التكرارات المستقبلية. وإذا تجاوز dayOfMonth نهاية الشهر، يُضبط على آخر يوم فيه. وتستخدم جميع حسابات التكرار المنطقة الزمنية المحلية للخادم.
التقاويم المسماة والمشاركة
إضافة إلى النطاق الشخصي الافتراضي، يستطيع المستخدم إنشاء ما يصل إلى 20 تقويمًا مسمى، ولكل منها لون عرض اختياري. وتحمل الأحداث calendarId اختياريًا؛ أما الأحداث من دونه فتوجد في النطاق الافتراضي الذي يظل خاصًا.
تستخدم التقاويم المسماة نموذج المنح المشترك: تتيح منحة read للمستلم رؤية التقويم وأحداثه إلى جانب أحداثه، وتتيح منحة write أيضًا إنشاء الأحداث وتعديلها فيه. وتُخزن الأحداث التي ينشئها متعاون تحت حساب مالك التقويم، فتظل الحصص والحذف والأرشيف المحمول مرتبطة بالمالك. ويُعاد التصريح بالوصول مع كل طلب؛ لذلك يخفي إلغاء المنحة التقويم عند القراءة التالية. ويؤدي حذف تقويم إلى فصل أحداثه إلى النطاق الافتراضي للمالك وإزالة منحه.
التذكيرات
يمكن للحدث حمل إزاحة تذكير (reminderMinutes، حتى 14 يومًا). تمسح دورة المؤجر في مجدول الأتمتة التذكيرات المستحقة وتنشر إشعار calendar-reminder في صندوق وارد مالك الحدث. وتضمن عملية مقارنة وضبط لكل تكرار ألا يُطلق مرة أخرى، بما في ذلك الأحداث المتكررة.
استيراد ICS وتصديره
ينزّل GET /api/calendar/export?calendarId= تقويمًا (أو النطاق الافتراضي) كملف .ics وفق RFC 5545: طوابع زمنية UTC، ونص مهروب، وقواعد RRULE أساسية من أنواع التكرار الأصلية، وكتل VALARM للتذكيرات. ويقبل POST /api/calendar/import حمولة ICS (حتى 2 MB / 1,000 حدث) في نطاق تقويم قابل للكتابة. يتعامل المستورد مع أوقات UTC والأوقات العائمة وقيم DATE لليوم كله وقواعد FREQ البسيطة. أما القواعد التي لا يمكن تمثيلها بدقة (INTERVAL وCOUNT وUNTIL وEXDATE) فيستورد الحدث بلا تكرار ويعدها في الاستجابة قواعد متروكة بدلًا من انحرافها بصمت.
وصول النموذج
تمنح ثلاثة أدوات محادثة مدمجة النماذج وصولًا إلى التقويم بهوية المستخدم المستدعي: list_calendar_events (للقراءة فقط)، وcreate_calendar_event وdelete_calendar_event (لهما آثار جانبية، ولذلك يخضعان لمسار اعتماد الأدوات المعتاد).
API
تتطلب جميع نقاط النهاية المصادقة. وتشمل قراءة الأحداث أحداث المستدعي والتقاويم المشتركة معه؛ وتتطلب الكتابة الملكية أو منحة كتابة على التقويم الهدف.
| الطريقة | المسار | الغرض |
|---|---|---|
GET | /api/calendar/events?from=&to= | أحداث نطاق مع توسيع التكرار |
POST | /api/calendar/events | إنشاء حدث |
PUT | /api/calendar/events/:eventId | تحديث حدث |
DELETE | /api/calendar/events/:eventId | حذف حدث |
GET | /api/calendar/calendars | التقاويم المسماة المملوكة والمشتركة |
POST | /api/calendar/calendars | إنشاء تقويم مسمى |
PUT | /api/calendar/calendars/:id | إعادة تسمية تقويم أو تغيير لونه |
DELETE | /api/calendar/calendars/:id | حذف تقويم (مع فصل الأحداث) |
GET | /api/calendar/export | تصدير ICS |
POST | /api/calendar/import | استيراد ICS |
تستخدم استعلامات النطاق حدي from/to بالمللي ثانية منذ الحقبة وتمتد حتى 13 شهرًا لكل طلب. ويستطيع المستخدم تخزين حتى 2000 حدث؛ تقتصر العناوين على 200 حرف والملاحظات على 10,000.