TaskNode Bot 🤖

نظام إدارة مهام احترافي عبر Telegram للشركات والمؤسسات.

---

📋 نظرة عامة

TaskNode Bot هو بوت تليجرام متكامل لإدارة المهام يدعم:

• ✅ نظام أقسام ومستخدمين
• ✅ 3 مستويات صلاحيات (Super Admin, Department Admin, User)
• ✅ إنشاء وتتبع المهام
• ✅ نظام تعليقات على المهام
• ✅ مرفقات (صور، ملفات) مع تخزين Cloudflare R2
• ✅ تقارير PDF و Excel
• ✅ تذكيرات تلقائية
• ✅ إشعارات فورية

---

🔧 المتطلبات

المتطلب	الإصدار
Python	3.11+
PostgreSQL	14+
Cloudflare R2	حساب مفعّل

---

🚀 خطوات التثبيت

1. إنشاء بيئة افتراضية

# Windows
python -m venv .venv
.venv\Scripts\activate

# Linux/Mac
python3 -m venv .venv
source .venv/bin/activate

2. تثبيت المكتبات

pip install -r requirements.txt

3. إنشاء قاعدة البيانات

-- في PostgreSQL
CREATE DATABASE tasknodebot;

4. إعداد ملف البيئة

# انسخ ملف المثال
cp .env.example .env

# ثم عدّل الإعدادات (انظر القسم التالي)

5. تشغيل Migrations

alembic upgrade head

6. تشغيل البوت

python main.py

---

⚙️ إعداد ملف .env

قم بإنشاء ملف .env في المجلد الرئيسي وأضف الإعدادات التالية:

# ==========================================
# إعدادات البوت (مطلوبة)
# ==========================================

# توكن البوت من @BotFather
BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

# معرفات السوبر أدمن (Telegram IDs) - مفصولة بفاصلة
# للحصول على ID: أرسل رسالة لـ @userinfobot
SUPER_ADMIN_IDS=123456789,987654321

# ==========================================
# قاعدة البيانات (مطلوبة)
# ==========================================

# رابط PostgreSQL
# الصيغة: postgresql+asyncpg://المستخدم:كلمة_السر@الخادم:المنفذ/اسم_القاعدة
DATABASE_URL=postgresql+asyncpg://postgres:mypassword@localhost:5432/tasknodebot

# ==========================================
# Cloudflare R2 للمرفقات (مطلوبة)
# ==========================================

# رابط R2 Endpoint
# الصيغة: https://<ACCOUNT_ID>.r2.cloudflarestorage.com
R2_ENDPOINT_URL=https://abc123def456.r2.cloudflarestorage.com

# مفاتيح API (من Cloudflare Dashboard > R2 > Manage R2 API Tokens)
R2_ACCESS_KEY_ID=your_access_key_id
R2_SECRET_ACCESS_KEY=your_secret_access_key

# اسم الـ Bucket
R2_BUCKET_NAME=tasknodebot-attachments

# ==========================================
# إعدادات إضافية (اختيارية)
# ==========================================

# المنطقة الزمنية (افتراضي: Asia/Riyadh)
TIMEZONE=Asia/Riyadh

# وضع التصحيح (True/False)
DEBUG_MODE=False

# مستوى السجلات (DEBUG, INFO, WARNING, ERROR)
LOG_LEVEL=INFO

---

📱 كيفية الحصول على الإعدادات

1. BOT_TOKEN

1. افتح @BotFather في تليجرام
2. أرسل /newbot
3. اتبع التعليمات واختر اسم للبوت
4. ستحصل على التوكن

2. SUPER_ADMIN_IDS

1. أرسل رسالة لـ @userinfobot في تليجرام
2. سيرد عليك بـ Telegram ID الخاص بك
3. أضف الـ IDs مفصولة بفاصلة

3. DATABASE_URL

مثال للـ PostgreSQL المحلي:

postgresql+asyncpg://postgres:password123@localhost:5432/tasknodebot

مثال لـ Supabase:

postgresql+asyncpg://postgres:password@db.xxxx.supabase.co:5432/postgres

4. Cloudflare R2

1. سجل دخول في Cloudflare Dashboard
2. اذهب إلى R2 Object Storage
3. أنشئ Bucket جديد باسم tasknodebot-attachments
4. اذهب إلى Manage R2 API Tokens
5. أنشئ Token جديد مع صلاحيات Read/Write
6. انسخ Access Key ID و Secret Access Key

---

📁 هيكل المشروع

TaskNodeBot/
├── main.py              # نقطة البداية
├── requirements.txt     # المكتبات المطلوبة
├── alembic.ini          # إعدادات Alembic
├── .env.example         # مثال ملف البيئة
│
├── bot/
│   ├── handlers/        # معالجات الأوامر والأزرار
│   ├── models/          # نماذج قاعدة البيانات
│   ├── services/        # خدمات الأعمال
│   ├── jobs/            # المهام المجدولة
│   └── utils/           # أدوات مساعدة
│
├── config/
│   └── settings.py      # إعدادات التطبيق
│
├── alembic/
│   └── versions/        # ملفات Migration
│
├── scripts/
│   ├── reset_database.py         # إعادة تعيين القاعدة
│   └── check_empty_database.py   # فحص القاعدة
│
└── docs/
    └── individual_tasks_system.md  # توثيق نظام المهام

---

👥 مستويات الصلاحيات

1. Super Admin (المدير العام)

• إدارة جميع الأقسام والمستخدمين
• الموافقة على تسجيلات المستخدمين الجدد
• إنشاء مهام لأي قسم
• عرض جميع التقارير
• إعدادات النظام

2. Department Admin (مدير القسم)

• إدارة مستخدمي القسم الخاص به
• إنشاء مهام للقسم
• مراجعة وقبول/رفض تسليمات المهام
• عرض تقارير القسم

3. User (المستخدم)

• استلام المهام
• تسليم المهام مع المرفقات
• إضافة تعليقات
• عرض مهامه الشخصية

---

🔄 حالات المهمة

PENDING → IN_PROGRESS → PENDING_REVIEW → COMPLETED
                    ↘               ↙
                      NEEDS_REVISION

الحالة	الوصف
PENDING	بانتظار القبول
IN_PROGRESS	قيد التنفيذ
PENDING_REVIEW	بانتظار المراجعة
NEEDS_REVISION	تحتاج تعديلات
COMPLETED	مكتملة
CANCELLED	ملغية

---

⏰ المهام المجدولة

المهمة	الوقت	الوصف
التذكيرات	12:00 PM	إرسال تذكيرات المهام القريبة
فحص البلوك	8:00 AM	اكتشاف المستخدمين الذين حظروا البوت

---

🛠️ سكريبتات مفيدة

# إعادة تعيين قاعدة البيانات (حذف كل البيانات)
python scripts/reset_database.py

# فحص إذا كانت القاعدة فارغة
python scripts/check_empty_database.py

---

🐛 حل المشاكل الشائعة

1. خطأ في الاتصال بقاعدة البيانات

تأكد من:
- PostgreSQL شغال
- DATABASE_URL صحيح
- قاعدة البيانات موجودة

2. خطأ في Cloudflare R2

تأكد من:
- R2_ENDPOINT_URL يحتوي على Account ID الصحيح
- المفاتيح صحيحة ولها صلاحيات كافية
- الـ Bucket موجود

3. البوت لا يستجيب

تأكد من:
- BOT_TOKEN صحيح
- لا يوجد instance آخر شغال
- الـ Telegram IDs في SUPER_ADMIN_IDS صحيحة

---

📞 الدعم

للمساعدة أو الاستفسارات، تواصل مع فريق التطوير.

---

📄 الترخيص

جميع الحقوق محفوظة © 2026