أتمتة تعبئة سجل القضايا ألياً من منصة بيسكامب لملف اكسل

١. نبذة المشروع

مكتب محاماة يدير قضاياه على منصة Basecamp، ويحتفظ بسجل متابعة في ملف Excel يحتوي 24 حقلاً لكل قضية. المطلوب برمجة أداة تُعبّئ هذا السجل آلياً من بيانات Basecamp عبر واجهتها البرمجية (API)، بشكل دوري ومن دون تدخل بشري، مع الحفاظ على معادلات Excel القائمة.

٢. أهداف المشروع

•إلغاء الإدخال اليدوي المتكرر لبيانات القضايا في ملف Excel.

•مزامنة يومية تلقائية من Basecamp إلى السجل، مع خيار تحديث لحظي عبر Webhooks.

•الحفاظ على معادلات Excel القائمة (أعمدة «الحالة» و«المؤخر») وعملها دون أخطاء.

٣. بنية البيانات في Basecamp (مهم جداً)

التسلسل الهرمي المعتمد — «مهام فقط»، بلا استخدام بطاقات Card Table إطلاقاً:

•مشروع (Project) = مساحة محامٍ ← اسم المشروع يمثّل «اسم المحامي».

•قائمة مهام (To-do list) داخل المشروع = قضية واحدة ← اسم القائمة = «اسم ملف القضية»، ووصف القائمة يحوي بقية بيانات القضية بصيغة موحّدة.

•مهمة (To-do) داخل القائمة = مرحلة من مراحل القضية ← تاريخ إتمام المهمة (completed_at) = تاريخ تلك المرحلة.

٤. نطاق العمل المطلوب

1.المصادقة مع Basecamp عبر OAuth 2.0 (يوفّر العميل Client ID و Secret و Refresh Token و Account ID).

2.سحب جميع المشاريع، ولكل مشروع قوائم المهام، ولكل قائمة مهامها — مع معالجة ترقيم الصفحات (pagination) واحترام حدّ الطلبات وإعادة المحاولة عند الحاجة.

3.محرّك مطابقة يحوّل البيانات إلى أعمدة السجل وفق «خريطة الحقول» في القسم 6، ويحلّل الوصف الموحّد لاستخراج الحقول التي لا يملك Basecamp حقلاً مخصّصاً لها.

4.الكتابة في ملف Excel (xlsx): مسح البيانات القديمة، كتابة الصفوف الجديدة، إعادة تطبيق المعادلات، تنسيق التواريخ والأرقام، وحفظ نسخة احتياطية مؤرّخة.

5.جدولة التشغيل اليومي تلقائياً (cron على لينكس/ماك أو Task Scheduler على ويندوز).

6.(إضافي/اختياري) ربط Webhook للتحديث اللحظي عند إتمام مهمة.

7.توثيق مختصر للتشغيل والإعداد، وتنفيذ تشغيل تجريبي ناجح على بيانات المكتب.

٥. صيغة إدخال بيانات القضية في Basecamp

تُكتب الحقول التي لا يملك Basecamp حقلاً مخصّصاً لها داخل «وصف قائمة المهام» بهذه الصيغة (سطر لكل حقل)، ويقوم البرنامج بتحليلها:

رقم القضية: 4772639321

المحكمة: محكمة الأحوال الشخصية بالرياض

قيمة التعاقد: 15000

المقدم: 5000

المحامي: أحمد عبدالله الدخيل(اختياري)

تاريخ التواصل: 2026-03-07(اختياري)

٦. خريطة الحقول (24 عموداً)

الأخضر = يُسحب مباشرة من Basecamp · الأصفر = يُستخرج من الوصف الموحّد · الأزرق = معادلة Excel تُعاد كتابتها. ملاحظة: أسماء المراحل يجب أن تُطابَق حرفياً، وسيوفّر العميل القائمة النهائية المعتمدة.

العمود

اسم الحقل

المصدر / كيفية التعبئة

A

تاريخ تواصل العميل

تاريخ إنشاء قائمة المهام (created_at) — أو سطر «تاريخ التواصل» في الوصف

B

رقم ملف القضية

تحليل وصف القائمة — سطر «رقم القضية»

C

اسم ملف القضية

اسم قائمة المهام (To-do list name)

D

اسم المحكمة

تحليل وصف القائمة — سطر «المحكمة»

E

استقبال الأعمال

تاريخ إتمام المهمة المسمّاة «استقبال الأعمال» (completed_at)

F

استيفاء المتطلبات

تاريخ إتمام المهمة «استيفاء المتطلبات»

G

تحرير عقد الأتعاب

تاريخ إتمام المهمة «تحرير عقد الأتعاب»

H

الإجراءات الشكلية

تاريخ إتمام المهمة «الإجراءات الشكلية»

I

غير منظور

تاريخ إتمام المهمة «غير منظور»

J

تقديم الدعوى

تاريخ إتمام المهمة «تقديم الدعوى»

K

منظور المحكمة الإبتدائية

تاريخ إتمام المهمة «منظور المحكمة الإبتدائية»

L

منظور محكمة الإستئناف

تاريخ إتمام المهمة «منظور محكمة الإستئناف»

M

منظور المحكمة العليا

تاريخ إتمام المهمة «منظور المحكمة العليا»

N

التنفيذ

تاريخ إتمام المهمة «التنفيذ»

O

قيمة التعاقد

تحليل وصف القائمة — سطر «قيمة التعاقد» (يُكتب رقماً)

P

مقدم

تحليل وصف القائمة — سطر «المقدم» (يُكتب رقماً)

Q

مؤخر

معادلة Excel = قيمة التعاقد − المقدم (تُعاد كتابتها)

R

اسم المحامى

اسم المشروع (مساحة المحامي) — أو سطر «المحامي» في الوصف

S

حالة تحرير عقد الأتعاب

معادلة Excel قائمة (تُعاد كتابتها لكل صف)

T

حالة إستفاء المتطلبات

معادلة Excel قائمة

U

حالة الإجراءات الشكلية

معادلة Excel قائمة

V

حالة غير منظور

معادلة Excel قائمة

W

حالة تقديم الدعوى

معادلة Excel قائمة

X

حالة استقبال الأعمال

معادلة Excel قائمة

٧. المتطلبات التقنية

•التكامل مع Basecamp 3/4 API عبر OAuth 2.0 ومعالجة استجابات JSON.

•لغة مفتوحة (يُفضّل Python) — يتوفّر سكربت انطلاق جاهز بلغة Python يمكن البناء عليه.

•التعامل مع Excel والحفاظ على المعادلات والتنسيق (مثل مكتبة openpyxl أو ما يماثلها).

•دعم كامل للنص العربي (RTL) والتواريخ، والتعامل مع الأرقام العربية واللاتينية.

•التعامل مع حدّ الطلبات (نحو 50 طلباً لكل 10 ثوانٍ) وترقيم الصفحات وإعادة المحاولة.

•حفظ المفاتيح الحسّاسة بأمان (متغيرات بيئة أو خزنة أسرار) لا داخل الكود.

٨. المخرجات المطلوبة

•كود مصدري موثّق وقابل للصيانة.

•ملف/آلية إعدادات لإدخال المفاتيح الأربعة بأمان.

•تعليمات تشغيل وجدولة واضحة (لينكس/ماك وويندوز).

•تشغيل تجريبي ناجح على بيانات المكتب مع مطابقة عيّنة قضايا.

•(عند الاتفاق) إعداد Webhook للتحديث اللحظي.

٩. معايير القبول

•تُعبّأ الحقول الآلية (A حتى N، وO، P، R) بشكل صحيح لكل قضية عند التشغيل.

•أعمدة الحالة (S–X) و«المؤخر» (Q) تُحسب صحيحةً دون أي خطأ #VALUE!.

•المزامنة قابلة للتكرار يومياً دون تكرار صفوف أو فقدان بيانات (مسح نظيف وإعادة كتابة).

•التعامل السليم مع القضايا غير المكتملة (مراحل بلا تاريخ تبقى فارغة لا نصّاً).

•الحفاظ على بنية السجل ومعادلاته الأصلية سليمة.

١٠. ما هو مُجهّز مسبقاً (يُرفق للمبرمج)

لتسريع التنفيذ، تتوفّر الملفات التالية وتُرفق للمبرمج المختار:

•سكربت Python كامل كنقطة انطلاق (مصادقة + سحب + محرّك مطابقة + كتابة في Excel — مُختبَر).

•سكربت مساعد للحصول على Refresh Token.

•ملف السجل بصيغة xlsx مع معادلاته.

•دليل تنفيذي ومخطط تدفّق للآلية.

المبرمج حرّ في استخدام هذه الملفات أو إعادة البناء بأسلوبه، بشرط تحقيق معايير القبول.

١١. المهارات المطلوبة

Python · REST APIs · OAuth 2.0 · تكامل Basecamp API · أتمتة Excel (openpyxl) · معالجة نصوص عربية · جدولة المهام (cron / Task Scheduler) · Webhooks (ميزة إضافية).

١٢. المدة المتوقعة

تقديرياً من 3 إلى 7 أيام عمل، وتُحدَّد نهائياً حسب خطة المبرمج.

١٣. ما يجب أن يتضمّنه عرض المتقدّم

•خبرة سابقة في تكاملات API (ويفضّل تجربة مع Basecamp) مع أمثلة إن وُجدت.

•خطة تنفيذ مختصرة والمدة الزمنية.

•كيفية ضمان أمان المفاتيح والبيانات.

•السعر، وضمان تعديلات ما بعد التسليم لفترة متّفق عليها.

١٤. ملاحظات وقيود

•المفاتيح حسّاسة — تُسلّم بأمان ولا تُخزّن في الكود أو تُشارك.

•أسماء المراحل تُطابَق حرفياً؛ سيوفّر العميل القائمة النهائية المعتمدة قبل البدء.

•تواريخ Basecamp ميلادية؛ يُتّفق على معالجة التاريخ الهجري إن رغب العميل في عرضه.

•ملف السجل الحالي بصيغة xlsb ويُحوَّل إلى xlsx (مُنجز).