تنبيهات الإنفاق

تراقب قواعد الإنفاق إنفاق مساحة العمل وترسل تنبيهًا عندما يتجاوز حدًا معيّنًا. ويمكن للقاعدة أيضًا حظر الطلبات بعد أن يتخطى الإنفاق هامش سماح. يمكن في كل خطة إنشاء ما يصل إلى 50 قاعدة لكل مساحة عمل.

يجري طرح تنبيهات الإنفاق والحظر وتقارير الإنفاق تدريجيًا. وإلى أن يتم تفعيلها، تُحفظ القواعد والإعدادات لكن لا يُقيَّم أي شيء ولا يُحظر ولا يُرسل.

كيف تعمل القاعدة

تجمع القاعدة بين:

مقياس: ما الذي يُقاس (راجع أنواع التنبيهات)؛
نطاق: إنفاق من يُحتسب، مثل مساحة العمل أو مفتاح API واحد أو قسم واحد؛
فترة: يوم أو أسبوع أو شهر تقويمي، أو نافذة متجددة من الساعات؛
حدود: المبلغ بالدولار أو النسب المئوية التي تُرسل تنبيهًا؛
إجراء: notify، أو block لرفض الطلبات التي تتجاوز حدًا معيّنًا أيضًا.

تقيّم Phaseo القواعد استنادًا إلى الاستخدام المسجَّل، بعد انتهاء الطلبات ببضع دقائق. وتُفحص مساحات العمل التي لديها قواعد كل ساعة أيضًا، وقواعد الرصيد كل 15 دقيقة. ويشمل الإنفاق مهام الفيديو والدفعات والموسيقى والوقت الفعلي. لإنشاء قاعدة، افتح Gateway → الإعدادات → الإشعارات → تنبيهات الإنفاق واختر إضافة تنبيه. يعرض المحرر القيمة الحالية للقاعدة المحفوظة ويمكنه إرسال تنبيه تجريبي. وتحتوي صفحة مفتاح API وصفحة الميزانيات على اختصارات تفتح المحرر مع حد المفتاح أو الميزانية كأساس. يمكن للأعضاء رؤية القواعد، أما المالكون والمشرفون فينشئونها ويغيّرونها ويختبرونها ويحذفونها.

أنواع التنبيهات والأسس

المقياس	يرسل تنبيهًا عندما	الفترات
`spend`	يبلغ إنفاق الفترة `threshold_amount`	أي فترة
`budget_percent`	يبلغ الإنفاق نسبة مئوية من أساس، بما يصل إلى خمسة حدود مثل 50 و80 و100	أي فترة
`forecast`	يبلغ الإنفاق المتوقع حتى نهاية الفترة مبلغًا أو نسبة مئوية من أساس	يوم، أسبوع، شهر
`spike`	يكون إنفاق الساعات القليلة الماضية أضعاف الإنفاق المعتاد	متجددة
`balance`	ينخفض الرصيد المتاح إلى مبلغ معيّن، أو يكفي لأقل من عدد معيّن من الأيام	متجددة، نطاق مساحة العمل فقط

تُقاس النسب المئوية مقارنةً بأساس (base_kind):

amount: مبلغ بالدولار يُحدَّد في القاعدة ويُستخدم للتنبيهات فقط.
workspace_budget: ميزانية مساحة العمل ذات الفاصل الزمني المطابق (base_ref: daily لفترة اليوم، وweekly للأسبوع، وmonthly للشهر). لا يمكن أن تكون الميزانية الدائمة أساسًا.
key_limit: حد إنفاق مفتاح API الخاص بالقاعدة للنافذة المطابقة. يتطلب نطاق المفتاح.
previous_period: الإنفاق عند النقطة نفسها من الفترة السابقة، مثل “أمس حتى هذا الوقت”. وفي القواعد المتجددة هي النافذة السابقة، وفي التوقعات الفترة السابقة كاملة.

لا ترسل القاعدة التي ينقصها أساسها، مثل ميزانية محذوفة أو مفتاح بلا حد إنفاق، أي شيء إلى أن يعود الأساس. ليست لضوابط الحماية حدود إنفاق، ولا يمكن أن تكون أساسًا.

النطاقات

النطاق	`scope_id`	ما يُحتسب
`workspace`	لا شيء	كل إنفاق مساحة العمل
`key`	معرّف مفتاح API	الطلبات المُرسلة بهذا المفتاح
`member`	معرّف المستخدم للعضو	الطلبات المُرسلة بمفاتيح أنشأها العضو، إضافةً إلى طلبات OAuth الخاصة بالعضو
`department`	معرّف القسم	كل ما يفعله الأشخاص في القسم (انظر أدناه)
`model`	معرّف النموذج، مثل `openai/gpt-5`	الطلبات التي يخدمها النموذج
`provider`	معرّف المزوّد	الطلبات التي يخدمها المزوّد

يُنسب إنفاق القسم لكل طلب على حدة:

المفتاح المخصّص لقسم يُحتسب لهذا القسم فقط.
وإلا فمنشئ المفتاح هو من يحدد: أقسامه، أو في طلبات OAuth أقسام المستخدم الذي سجّل الدخول.
الشخص الذي ينتمي إلى عدة أقسام يُحتسب افتراضيًا لها كلها. اختر القسم الأساسي فقط بدلًا من كل أقسامه في إعدادات إنفاق مساحة العمل (API: spend.department_attribution: "primary") لاحتسابه لقسمه الأساسي فقط. وإذا لم يكن أي قسم محددًا كقسم أساسي، فيأتي أولًا قسم أُضيف إليه يدويًا، ثم الأقدم.

تُقرأ عضوية الأقسام في كل مرة تُقيَّم فيها القاعدة، لذا فإن نقل شخص إلى قسم آخر ينقل معه إنفاقه في الفترة الحالية. ولأن الشخص قد يُحتسب لعدة أقسام، قد يزيد مجموع الأقسام على إجمالي مساحة العمل. لا يُنسب الاستخدام السابق لسبتمبر 2026 إلى الأعضاء أو الأقسام.

الفترات والمناطق الزمنية

اليوم والأسبوع والشهر فترات تقويمية. يمتد الأسبوع من الاثنين إلى الأحد. يمكن لكل قاعدة تحديد time_zone خاص بها من IANA، مثل Europe/London أو America/New_York؛ وإلا فتستخدم المنطقة الزمنية للفوترة في مساحة العمل، وهي UTC افتراضيًا. غيّر المنطقة الزمنية للفوترة في إعدادات إنفاق مساحة العمل أو باستخدام spend.billing_time_zone في API إعدادات الإشعارات. تُراعى تغييرات التوقيت الصيفي، وأسماء المناطق حساسة لحالة الأحرف. تغطي فترة rolling آخر window_hours (من 1 إلى 720) وتتقدم باستمرار. تستخدمها قواعد الارتفاع المفاجئ كنافذة للارتفاع، وقواعد الرصيد كمدة لحساب متوسط الإنفاق.

تُعاد حدود المفاتيح وميزانيات مساحة العمل دائمًا عند حدود UTC. القاعدة التي تعتمد أساس workspace_budget أو key_limit في منطقة زمنية أخرى تقارن يومها أو أسبوعها أو شهرها المحلي بهذا الحد، لذا قد يختلف إنفاقها عمّا يحتسبه الحد.

الحدود والتنبيهات المتكررة

بحسب المقياس، تحتوي القاعدة على حد إلى خمسة حدود بالنسبة المئوية (من 1 إلى 1000) أو حد واحد بالدولار.

في الفترات التقويمية، يرسل كل حد تنبيهًا واحدًا على الأكثر في كل فترة. وعندما يتجاوز الإنفاق عدة حدود دفعة واحدة، يذكر تنبيه واحد الحد الأعلى ويسرد الحدود الأخرى.
تستخدم القواعد المتجددة وقواعد الارتفاع المفاجئ والرصيد بدلًا من ذلك cooldown_minutes (من 5 إلى 43,200، والافتراضي 360). خلال فترة التهدئة لا يرسل تنبيهًا إلا حدٌّ أعلى، وبعدها تنبّه القاعدة مجددًا إذا ظل الإنفاق فوق الحد.
لا تُرسل الحدود التي أُرسلت بالفعل في هذه الفترة مرة أخرى عند تعديل القاعدة.

يرسل إرسال اختبار التنبيه الذي سترسله القاعدة الآن، مع علامة [TEST]، إلى وجهات القاعدة. لا يُسجَّل أي شيء، ويمكن لمساحة العمل إرسال خمسة اختبارات في الدقيقة. يعرض السجل لكل قاعدة التنبيهات وحالات الحظر التي أرسلتها.

حظر الطلبات

تنبّه قاعدة spend أو budget_percent ذات action: "block" عند حدودها، وتحظر عندما يبلغ الإنفاق نقطة الحظر: block_at_percent من الأساس (الافتراضي 110، وعلى الأقل الحد الأعلى)، أو block_at_amount لقاعدة spend. لا يمكن للقواعد ذات أساس previous_period الحظر. المسافة بين آخر تنبيه ونقطة الحظر هي هامش السماح: يتلقى فريقك تحذيرًا قبل توقف الطلبات.

يتم الحظر بأفضل جهد. فهو يعتمد على الاستخدام المسجَّل، لذا يبدأ الحظر بعد بضع دقائق من تجاوز الإنفاق نقطة الحظر، وقد يتخطاها الإنفاق خلال ذلك الوقت. للحصول على حد صارم يُفحص مع كل طلب، استخدم حدود المفاتيح أو ميزانيات مساحة العمل.

	حظر قاعدة الإنفاق	حد المفتاح	ميزانية مساحة العمل
الفحص	كل بضع دقائق، من الاستخدام المسجَّل	مع كل طلب	مع كل طلب
النطاق	مساحة العمل أو المفتاح أو العضو أو القسم أو النموذج أو المزوّد	مفتاح واحد	مساحة العمل
الفترات	يوم أو أسبوع أو شهر أو متجددة، في أي منطقة زمنية	يوم أو أسبوع أو شهر UTC	يوم أو أسبوع أو شهر UTC، أو دائمة
النماذج المجانية	لا تُحظر ما لم تكن `block_free_models` بقيمة true	تُحتسب	تُحتسب
تحذير مسبق	نعم، عند حدود القاعدة	لا	لا
الرفع	بواسطة مالك أو مشرف، لبقية الفترة	رفع الحد	رفع الميزانية

طوال فترة نشاط الحظر، تتلقى الطلبات ضمن نطاقه 429 مع رمز الخطأ spend_rule_blocked. يتضمن النص reason: "spend_rule_block" وrule_id وrule_name وblock_id وlimit_scope وlimit_value (بالدولار الأمريكي) وreset_at. يحدد Retry-After عدد الثواني حتى تُعاد الفترة. ليس للقاعدة المتجددة وقت إعادة: يستمر حظرها حتى ينخفض الإنفاق في النافذة إلى ما دون نقطة الحظر، ولا تتضمن الاستجابة Retry-After. يزيل حظر المزوّد مسارات ذلك المزوّد، ولا يُرفض الطلب إلا إذا لم يبقَ مسار آخر. لا تُحظر جلسات الوقت الفعلي بعد. ما دام الإنفاق فوق آخر حد للقاعدة لكنه دون نقطة الحظر، تحمل استجابات الطلبات ضمن النطاق ترويسة x-phaseo-spend-warning تسرد ما يصل إلى ثلاث قواعد، مثل rule_id=…; scope=workspace; resets_at=2026-11-01T00:00:00.000Z. يمكن للعملاء تسجيلها أو الإبطاء قبل أن يبدأ الحظر. يُرفع الحظر تلقائيًا عند إعادة الفترة، أو عندما ينخفض إنفاق قاعدة متجددة إلى ما دون نقطة الحظر، أو عند تعطيل القاعدة أو حذفها أو تغييرها. يمكن للمالكين والمشرفين رفعه من تنبيهات الإنفاق → الحظر النشط أو باستخدام POST /v1/spend-blocks/{id}/lift. لا يبدأ الحظر المرفوع مجددًا في الفترة نفسها (وفي القواعد المتجددة لمدة نافذة واحدة). تُرسل إشعارات حظر الإنفاق عند بدء الحظر وعند رفعه.

الرصيد والمدة المتبقية

تراقب قاعدة balance الرصيد المتاح لمساحة العمل: رصيد الأرصدة مطروحًا منه المبالغ المحجوزة للطلبات الجارية. وتستخدم نطاق مساحة العمل وفترة متجددة، وتنبّه عند تحقق أي من الشرطين:

threshold_amount: الرصيد المتاح يساوي هذا المبلغ أو أقل منه؛
runway_days: بمتوسط الإنفاق اليومي خلال آخر window_hours، سيكفي الرصيد أقل من هذا العدد من الأيام. وإذا لم يكن هناك إنفاق حديث، فلا يوجد تنبيه للمدة المتبقية.

تنبّه قاعدة الرصيد مرة واحدة لكل انخفاض. ولا تنبّه مجددًا إلا بعد أن يتعافى الرصيد ثم ينخفض مرة أخرى، وليس أكثر من فترة التهدئة الخاصة بها. لا يُرسل أي تنبيه ما دامت إعادة الشحن التلقائية مفعّلة وتعمل. يبقى البريد الإلكتروني لانخفاض الرصيد في الإعدادات → الأرصدة الخيار الافتراضي البسيط. يُرسل مرة واحدة في كل مرة ينخفض فيها الرصيد عن حده، وعلى الأكثر كل ست ساعات، ولا يُرسل ما دامت إعادة الشحن التلقائية تعمل. استخدم قاعدة رصيد لتنبيهات المدة المتبقية أو لوجهات أخرى أو لحد مختلف.

التوقع

تتوقع قاعدة forecast الإنفاق بخط مستقيم حتى نهاية اليوم أو الأسبوع أو الشهر الحالي: الإنفاق حتى الآن مقسومًا على الجزء المنقضي من الفترة. وتنتظر حتى تمر 3 ساعات من اليوم أو 24 ساعة من الأسبوع أو 72 ساعة من الشهر، وحتى يُنفق 0.01 دولار على الأقل، كي لا تؤدي بداية هادئة إلى تنبيه. يذكر التنبيه متى سيُبلغ الحد بالوتيرة الحالية. حدد threshold_amount بالدولار، أو أساسًا مع نسب مئوية. مع أساس previous_period، يُقارن التوقع بالفترة السابقة كاملة. ينبّه كل حد مرة واحدة في كل فترة.

الارتفاع المفاجئ

تقارن قاعدة spike إنفاق آخر window_hours (من 1 إلى 56) بالإنفاق المعتاد لذلك الوقت:

في النوافذ الأقصر من 24 ساعة، الإنفاق المعتاد هو وسيط الساعات نفسها في كل يوم من الأيام السبعة السابقة. وفي النوافذ الأطول، هو وسيط النوافذ السابقة ذات الطول نفسه خلال الأيام السبعة السابقة.
تنبّه عندما يبلغ الإنفاق على الأقل spike_multiplier ضعف المعتاد (الافتراضي 3) وعلى الأقل spike_floor (الافتراضي 5 دولارات).
تحتاج إلى إنفاق لمساحة العمل في ثلاث من تلك النوافذ السابقة على الأقل. وحتى ذلك الحين يُظهر المحرر أنها لا تزال تتعلّم. وعندما يكون الإنفاق المعتاد صفرًا، لا يُطبَّق إلا الحد الأدنى.
تستخدم فترة تهدئة (الافتراضي 6 ساعات) ولا تحظر أبدًا.

تستخدم المقارنة خطوات دقيقة مدتها 24 ساعة، لذا بعد تغيير التوقيت الصيفي تقارن بساعة أبكر أو أبعد على الساعة المحلية. تُفحص قواعد الارتفاع المفاجئ عند وصول استخدام جديد.

تقارير الإنفاق

يتلقى المالكون تقرير إنفاق أسبوعيًا افتراضيًا، ويمكن للمشرفين الاشتراك فيه. تتوفر أيضًا تقارير يومية وشهرية. يشرح دليل إشعارات مساحة العمل الإعدادات والمحتوى. إضافةً إلى ذلك:

يُرسل التقرير بين 09:00 و21:00 في المنطقة الزمنية للفوترة في اليوم الأول بعد فترته. وإذا تعذّر إرساله في ذلك اليوم، فيُتخطى بدلًا من إرساله متأخرًا.
التوقع في التقرير خاص بشهر الفوترة الحالي.
تشمل إجماليات الأعضاء والأقسام المهام غير المتزامنة وتتبع قاعدة الأقسام أعلاه، لذا قد تختلف قليلًا عن الإجمالي.
يلغي كل شخص اشتراكه في نسخته فقط من تقرير مساحة العمل. ولا يتلقاه أبدًا الأعضاء الذين ليسوا مالكين أو مشرفين.

التوجيه والوجهات

ترسل قواعد الإنفاق ثلاثة أنواع من الإشعارات. اختر وجهة كل نوع في الإعدادات → الإشعارات:

المسار	النوع	يُرسل عندما
تنبيهات الإنفاق	`spend_alert`	يُتجاوز حد إحدى القواعد
حظر الإنفاق	`spend_blocked`	يبدأ حظر أو يُرفع (`payload.state` هو `started` أو `lifted`)
تقارير الإنفاق	`spend_report`	يحين موعد تقرير إنفاق

يمكن أن تكون للقاعدة وجهاتها الخاصة. وهي تحل محل مساري تنبيهات الإنفاق وحظر الإنفاق لتلك القاعدة؛ وإذا كانت كلها متوقفة مؤقتًا، فلا تُرسل تنبيهات القاعدة إلى المسارات بدلًا منها. تصل التنبيهات وحالات الحظر أيضًا إلى تطبيق الجوال لدى المالكين والمشرفين، ولدى منشئ المفتاح أو العضو الذي تخصه القاعدة. تتلقى خطافات الويب المخصصة التنبيه بصيغة JSON، مع title وmessage وrule_id وrule_name وmetric وscope وperiod وvalue_nanos، وبحسب المقياس base_nanos أو forecast أو spike أو حقول الرصيد. تحقّق من كل عملية تسليم بتوقيعها؛ راجع القسم الخاص بالتحقق من توقيعات خطافات الويب في إشعارات مساحة العمل.

إدارة القواعد باستخدام API

تستخدم API قواعد الإنفاق مفتاح إدارة يملك spend_rules:read أو spend_rules:write أو spend_rules:delete. يمكن إرسال المبالغ بالدولار (threshold_amount_usd) أو بدقة بالنانودولار (threshold_amount_nanos)، وتتضمن الاستجابات الاثنين.

curl https://api.phaseo.app/v1/spend-rules \
  -H "Authorization: Bearer $PHASEO_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly budget",
    "metric": "budget_percent",
    "period": "month",
    "base_kind": "workspace_budget",
    "base_ref": "monthly",
    "threshold_percents": [50, 80, 100],
    "action": "block",
    "block_at_percent": 110
  }'

استخدم GET /v1/spend-rules/{id}/preview لعرض القيمة الحالية والحد التالي، وPOST /v1/spend-rules/{id}/test لإرسال اختبار. يعرض GET /v1/spend-blocks حالات الحظر النشطة. توجد المنطقة الزمنية للفوترة ونسبة الإنفاق إلى الأقسام وإعدادات التقارير في الكائن spend ضمن إعدادات الإشعارات.

إدارة القواعد باستخدام Terraform

يوفّر مزوّد Terraform من Phaseo (phaseoteam/phaseo) المورديْن phaseo_spend_rule وphaseo_workspace_budget، ومصادر البيانات phaseo_spend_rules وphaseo_spend_blocks وphaseo_workspace_budgets.

resource "phaseo_workspace_budget" "monthly" {
  interval = "monthly"
  limit    = 500
}

resource "phaseo_spend_rule" "monthly_budget" {
  name               = "Monthly budget"
  metric             = "budget_percent"
  period             = "month"
  base_kind          = "workspace_budget"
  base_ref           = "monthly"
  threshold_percents = [50, 80, 100]
  action             = "block"
  block_at_percent   = 110

  depends_on = [phaseo_workspace_budget.monthly]
}

resource "phaseo_spend_rule" "spike" {
  name             = "Spend spike"
  metric           = "spike"
  period           = "rolling"
  window_hours     = 3
  spike_multiplier = 4
}

استورد قاعدة أو ميزانية موجودة باستخدام معرّفها:

terraform import phaseo_spend_rule.monthly_budget 11111111-1111-4111-8111-111111111111

نظرة عامة

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

الميزات

التكاملات

مساحات العمل والوصول

الموثوقية والعمليات

المنصة والأبحاث

أدلة الترحيل

المجتمع

تنبيهات الإنفاق

كيف تعمل القاعدة

أنواع التنبيهات والأسس

النطاقات

الفترات والمناطق الزمنية

الحدود والتنبيهات المتكررة

حظر الطلبات

الرصيد والمدة المتبقية

التوقع

الارتفاع المفاجئ

تقارير الإنفاق

التوجيه والوجهات

إدارة القواعد باستخدام API

إدارة القواعد باستخدام Terraform

​كيف تعمل القاعدة

​أنواع التنبيهات والأسس

​النطاقات

​الفترات والمناطق الزمنية

​الحدود والتنبيهات المتكررة

​حظر الطلبات

​الرصيد والمدة المتبقية

​التوقع

​الارتفاع المفاجئ

​تقارير الإنفاق

​التوجيه والوجهات

​إدارة القواعد باستخدام API

​إدارة القواعد باستخدام Terraform

كيف تعمل القاعدة

أنواع التنبيهات والأسس

النطاقات

الفترات والمناطق الزمنية

الحدود والتنبيهات المتكررة

حظر الطلبات

الرصيد والمدة المتبقية

التوقع

الارتفاع المفاجئ

تقارير الإنفاق

التوجيه والوجهات

إدارة القواعد باستخدام API

إدارة القواعد باستخدام Terraform