دليل المطوّر

كيف يعمل الـ API وكيف تبنون عليه تطبيق Flutter. التفاصيل الكاملة لكل رابط في التوثيق التفاعلي.

1. فكرة التطبيق

تطبيق لعائلة واحدة (عائلة الخضري): شجرتها كاملة، وملف لكل فرد حيّاً أو متوفى، وأخبار العائلة.

• النسب عن طريق الأب فقط. لكل شخص father_id واحد (أو لا شيء للجذر). لا يوجد أمهات ولا زوجات. الأبناء والبنات يُرتّبون معاً من الأكبر.
• التصفح كله بدون حساب: الشجرة والأفراد والأخبار.
• أنواع المستخدمين:

2. الأساسيات

Base URL:  https://api-production-34bd.up.railway.app/api/v1

شكل الرد الناجح

{ "message": "تم الحفظ",        // في عمليات الكتابة فقط
  "data": { ... } أو [ ... ],
  "meta": { ... } }              // أحياناً: عدادات أو معلومات إضافية

القوائم (pagination)

GET /persons و/posts وأمثالها ترجع صفحات. أرسلوا page وper_page، واقرؤوا:

"links": { "next": "https://…/persons?page=2", "prev": null, … },
"meta":  { "current_page": 1, "last_page": 48, "per_page": 25, "total": 1188 }

للتحميل اللانهائي: اطلبوا الصفحة التالية ما دام links.next ليس null.

شكل الخطأ (دائماً)

{ "message": "البيانات المدخلة غير صحيحة.",   // مترجمة: اعرضوها للمستخدم
  "code": "VALIDATION_FAILED",                 // ثابتة: اعتمدوا عليها في الكود
  "errors": { "email": ["…"] } }               // في 422 فقط: خطأ لكل حقل

أشياء يجب معرفتها

• المعرّفات نصوص ULID (مثل 01m45sp9akn922fwjqjtbgxycg) وليست أرقاماً. ref_no هو رقم الشخص في سجل العائلة (للعرض والبحث).
• القيم الثابتة (الجنس، حالة الحياة…) تأتي كـ {"value": "male", "label": "ذكر"}: استخدموا value في المنطق وlabel للعرض. القائمة الكاملة: GET /meta/enums.
• التواريخ بصيغة ISO. تاريخ الميلاد والوفاة معه دقة birth_date_precision: exact / month / year / approx — اعرضوا السنة فقط إذا كانت year.
• الحقول المترجمة (الاسم، النبذة، عنوان الخبر…) ترجع بلغة Accept-Language. عند الإرسال: {"ar": "أحمد", "en": "Ahmad"}، أو نص عادي فيُحفظ بلغة Content-Language.
• الصور روابط كاملة جاهزة: thumb (صغيرة للقوائم) وpreview (للملف) وoriginal.
• حدود الطلبات: 120 طلب/دقيقة، الدخول 10/دقيقة، التعليقات والرفع 10–20/دقيقة. عند تجاوزها: 429 TOO_MANY_REQUESTS.
• اللغات المفعّلة واتجاهها: GET /meta/languages. إعدادات عامة (التسجيل مفتوح؟ حجم الرفع): GET /meta/settings.

3. الدخول والحساب

الدخول والتسجيل يرجعان:

{ "data": { "token": "12|AbC…", "token_type": "Bearer",
            "user": { "id", "name", "email", "roles": ["staff"],
                      "permissions": ["persons.create", "persons.update", …] } } }

• احفظوا token في flutter_secure_storage. التوكن لا ينتهي حتى الخروج، وكل جهاز له توكن (أرسلوا device_name مثل اسم الجهاز).
• أي رد 401 UNAUTHENTICATED = احذفوا التوكن وارجعوا لوضع الزائر.
• استخدموا permissions لإظهار الأزرار (مثلاً زر "إضافة" إذا فيها persons.create). وكل فرد وخبر يرجع معه can جاهزة (انظر تحت).

4. الشجرة (الرسم)

GET /graph يرجع جزءاً من الشجرة حول شخص، جاهزاً للرسم:

{ "data": {
    "root_id": "01m45…",
    "nodes": [ { "id", "ref_no", "label": "سالم الخضري", "gender": "male",
                 "life_status": "deceased", "birth_year", "death_year", "thumb_url",
                 "generation": 1, "father_id": "01m45…", "children_count": 3,
                 "has_more_up": false, "has_more_down": true } ],
    "families": [ { "father_id": "01m45…", "children": ["id1", "id2"] } ]   // مرتبة من الأكبر
  },
  "meta": { "graph_version": 2424, "nodes_count": 3, "truncated": false } }

• الرسم: كل عنصر في families = خط من الأب إلى أبنائه بالترتيب. (مكتبة مثل graphview تكفي).
• التوسيع عند الضغط: إذا has_more_down = true اعرضوا زر "+" واطلبوا GET /graph/expand/{id}?direction=down&depth=2 وادمجوا النتيجة.
• التخزين: الرد يحمل ETag. أرسلوه في If-None-Match في المرة القادمة: إذا لم يتغير شيء يرجع 304 بدون جسم، فاعرضوا النسخة المخزّنة (يعمل بدون إنترنت أيضاً).

5. الأفراد

كائن can في البطاقة يقول ماذا يستطيع المستخدم الحالي:

"can": { "update": true, "delete": false, "add_relative": true, "add_child": true,
         "needs_review": true }   // true = تعديلاته ستذهب للمدير: اعرضوا تنبيهاً بذلك

6. الأخبار

• كل خبر فيه allow_comments وallow_likes: إذا كانت false أخفوا الزر (العدّاد يرجع null). المحاولة رغم ذلك ترجع COMMENTS_DISABLED / LIKES_DISABLED.
• liked_by_me يكون صحيحاً فقط إذا أرسلتم التوكن.
• cover = أول صورة (للقائمة)، وimages = كل الصور.

7. الإضافة والتعديل والموافقة

العمليات الأساسية

قواعد تتحقق منها الشجرة تلقائياً (ترجع 422 برمز واضح): الأب ذكر وأكبر بـ 12 سنة على الأقل، لا يكون الشخص جداً لنفسه، الميلاد قبل الوفاة… انظر رموز الأخطاء.

تحذيرات بدون رفض: إذا كانت التواريخ تقريبية، أو وُلد الشخص بعد وفاة أبيه، يُحفظ الطلب ويرجع معه "meta": {"warnings": ["INVALID_PARENT_AGE"]} أو BIRTH_AFTER_PARENT_DEATH — اعرضوا تنبيهاً للمستخدم ليتأكد.

الموافقة: انتبهوا لـ 201 مقابل 202

نفس الطلب قد يرجع ردين مختلفين حسب صلاحية المستخدم:

// 202
{ "message": "أُرسل طلبك للمدير للموافقة",
  "data": { "change_request": { "id", "status": {"value": "pending"}, "action": {"label": "إضافة شخص"},
                                "subject": "أحمد الخضري", "preview": { … } } } }

الطلبات: GET /change-requests (الموظف يرى طلباته، المدير يرى الكل)، والمدير يوافق POST /change-requests/{id}/approve أو يرفض …/reject مع {"note": "…"}. الموظف يلغي طلبه بـ DELETE.

8. الإشعارات

لا يوجد Push حالياً (FCM مخطط لاحقاً): اطلبوا unread-count عند فتح التطبيق وكل دقيقة أو دقيقتين أثناء استخدامه.

9. شاشات المدير

كلها تحت /admin وتحتاج صلاحيات المدير:

• GET /admin/stats — أرقام لوحة الإحصائيات.
• /admin/users — القائمة، الإضافة، التعديل، الإيقاف (/suspend، /activate)، الأدوار PUT /admin/users/{id}/roles، والصلاحيات المباشرة للموظف PUT /admin/users/{id}/permissions (مثل منح persons.direct).
• GET /admin/permissions و/admin/roles — لبناء شاشة الصلاحيات.
• /admin/languages و/admin/settings — اللغات والإعدادات.
• PATCH /family — اسم العائلة، الجذر، إعدادات عرض النسب.

10. رموز الأخطاء

القاعدة البسيطة: اعرضوا message للمستخدم كما هي (مترجمة)، واستخدموا code فقط عندما تحتاجون تصرفاً خاصاً (مثل 401 → شاشة الدخول).

11. Flutter: البداية

عميل dio واحد للتطبيق

final dio = Dio(BaseOptions(
  baseUrl: 'https://api-production-34bd.up.railway.app/api/v1',
  headers: {'Accept': 'application/json'},
  connectTimeout: const Duration(seconds: 60),   // السيرفر قد يأخذ وقتاً في أول طلب
));

dio.interceptors.add(InterceptorsWrapper(
  onRequest: (options, handler) async {
    options.headers['Accept-Language'] = currentLocale;          // 'ar' أو 'en'
    final token = await storage.read(key: 'token');
    if (token != null) options.headers['Authorization'] = 'Bearer $token';
    handler.next(options);
  },
  onError: (e, handler) async {
    final body = e.response?.data;
    if (e.response?.statusCode == 401) await auth.logoutLocally();
    handler.reject(e.copyWith(error: ApiError(
      code: body is Map ? body['code'] : 'NETWORK',
      message: body is Map ? body['message'] : 'تحقق من الاتصال',
      fields: body is Map ? body['errors'] : null,
    )));
  },
));

الحفظ مع الموافقة

final res = await dio.post('/persons/$id/relatives', data: {
  'relation': 'son',
  'person': {'first_name': {'ar': name}, 'birth_date': date},
});
if (res.statusCode == 202) {
  showSnack('أُرسل للمدير للموافقة');
} else {
  showSnack(res.data['message']);
  refreshTree();
}

رفع صورة

await dio.post('/persons/$id/photo', data: FormData.fromMap({
  'photo': await MultipartFile.fromFile(file.path),
}));

الشجرة مع التخزين

final res = await dio.get('/graph',
  queryParameters: {'depth_down': 12, 'max_nodes': 2000},
  options: Options(
    headers: {if (savedEtag != null) 'If-None-Match': savedEtag},
    validateStatus: (s) => s == 200 || s == 304,
  ));
if (res.statusCode == 304) return cachedGraph;
save(res.data, res.headers.value('etag'));

12. كل شاشة وروابطها

⚠️ هذا هو السيرفر الحقيقي ببيانات العائلة. للتجربة استخدموا حساب موظف بدون صلاحية مباشرة: كل إضافاتكم تذهب للمدير بدل أن تُكتب في الشجرة.

أي سؤال أو رابط ناقص؟ تواصلوا مع مسؤول المشروع.