# دليل الوكلاء — درب

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

## من نحن
منصّة تعليمية سعودية للطلاب المقبلين على اختبارات القبول الجامعي. الواجهة عربية
(RTL) والجمهور طلابُ الثانوية والخريجون في السعودية.

## ماذا يمكنك أن تفعل بالنيابة عن الطالب
- **خريطة المذاكرة** — لكل اختبارٍ مساحةُ عمل: جاهزيةٌ محسوبة، وما تبقّى من دروسٍ وتدريب، والخطوة التالية. (`/roadmap`)
- **جلسات التركيز** — مؤقّت مذاكرةٍ يسجّل ساعاتك ويربطها بمهمّة اليوم وبسلسلة أيامك. (`/orbit`)
- **خزنة الأخطاء** — تحفظ كل سؤالٍ أخطأت فيه ويشرحه المساعد، ثم تُراجَع بالتكرار المتباعد. (`/vault`)
- **خطة اليوم** — جدولٌ يوميّ/أسبوعيّ/شهريّ يُبنى حول مشاغلك ويحسب وقتك المتاح فعلاً. (`/plan`)
- **دليل الجامعات** — جامعات السعودية بكلياتها وتخصّصاتها الدقيقة ومعادلات النسبة الموزونة وترتيب QS. (`/universities`)
- **التقويم الدراسي** — العام الدراسي الرسمي وإجازاته ومواعيد قياس المعلنة — تُبنى الخطة عليه. (`/plan`)
- **أسئلة القبول الشائعة** — إجاباتٌ عن منصّة قبول وشروط التقديم والنسب الموزونة. (`/faq`)

## واجهات القراءة العامّة
لا تحتاج مصادقة، وتُعيد JSON، وحدُّها ٦٠ طلباً في الدقيقة لكل عنوان.

### `GET /api/agent/universities`
قائمة الجامعات السعودية ومعلوماتها؛ ومع `id` تُعاد كلياتها وتخصّصاتها الدقيقة.
المعاملات: `id` · `region`

### `GET /api/agent/exams`
الاختبارات الوطنية ونوافذ تسجيلها الرسمية وحالتها (مفتوح/قادم/بانتظار الإعلان).

### `GET /api/agent/calendar`
التقويم الدراسي السعودي المعتمد: الفصول والإجازات ونهاية العام.

### `GET /api/agent/faq`
الأسئلة الشائعة عن القبول الجامعي ومنصّة قبول، مع بحثٍ نصّي عبر `q`.
المعاملات: `q`

## الاكتشاف الآليّ
| ماذا | أين |
|---|---|
| وصف OpenAPI 3.1 | `https://usedarb.com/openapi.json` |
| بطاقة الوكيل (A2A) | `https://usedarb.com/.well-known/agent-card.json` |
| بيان الإضافة | `https://usedarb.com/.well-known/ai-plugin.json` |
| خادم MCP | `https://usedarb.com/mcp` |
| المهارات | `https://usedarb.com/api/agent/skills` |

## المصادقة
واجهاتُ القراءة أعلاه **عامّة بلا مصادقة**. أمّا ما يخصّ حساب طالبٍ بعينه فمحميٌّ
بتسجيل دخول Google (OAuth 2.0 عبر Firebase)، ويُرسَل رمزُ الهوية في ترويسة
`Authorization: Bearer <ID token>`. لا يوجد — ولن يوجد — طريقٌ يُخرِج بيانات
طالبٍ إلى وكيلٍ بلا إذنه.

## قواعد نتوقّع منك احترامها
1. **لا تخترع موعداً ولا رقماً.** إن لم تُعلنه الجهة الرسمية فالحقل فارغٌ عمداً؛
   انقل «لم يُعلن بعد» ولا تملأ الفراغ من عندك.
2. **انسب المصدر** حين تنقل تقويماً أو نافذة تسجيل — الجهة هي المرجع، ودرب ناقل.
3. **احترم robots.txt**: الصفحات خلف تسجيل الدخول ممنوعة من الزحف.