Skip to content

README.md

Latest commit

 

History

History
355 lines (253 loc) · 9.08 KB

README.md

File metadata and controls

355 lines (253 loc) · 9.08 KB
Raw

🏪 نظام تقسيط - Taqsit

Python Flask PostgreSQL License

نظام متكامل لإدارة المبيعات بالتقسيط

العرض التجريبي • التوثيق • التثبيت • المساهمة

📖 نظرة عامة

نظام تقسيط هو تطبيق ويب متكامل مبني بـ Python Flask لإدارة المبيعات بالتقسيط. يوفر النظام حلاً شاملاً للمحلات التجارية التي تقدم خدمات البيع بالتقسيط، مع واجهة مستخدم عربية سهلة الاستخدام ولوحة تحكم متقدمة.

✨ المميزات

🛒 إدارة المبيعات

  • إنشاء فواتير نقدية وتقسيط
  • دعم الباركود للمنتجات
  • حساب تلقائي للأقساط
  • طباعة الفواتير

👥 إدارة العملاء

  • سجل كامل للعملاء
  • تتبع الأقساط لكل عميل
  • سجل المدفوعات
  • إرسال تذكيرات

📦 إدارة المخزون

  • تتبع المنتجات والكميات
  • تنبيهات المخزون المنخفض
  • تصنيفات المنتجات
  • دعم الباركود

💰 إدارة الأقساط

  • جدولة الأقساط التلقائية
  • تتبع المدفوعات
  • تقارير الأقساط المتأخرة
  • غرامات التأخير (اختياري)

📊 التقارير والإحصائيات

  • لوحة تحكم تفاعلية
  • تقارير المبيعات
  • تقارير الأقساط
  • تقارير المخزون
  • تصدير للـ Excel/PDF

🔐 الأمان

  • نظام صلاحيات متعدد المستويات
  • سجل النشاطات
  • API مع مفاتيح مصادقة
  • نسخ احتياطي تلقائي

📱 PWA

  • تطبيق ويب تقدمي
  • يعمل بدون إنترنت
  • قابل للتثبيت على الجوال

🛠️ التقنيات المستخدمة

التقنية الوصف
Backend Python 3.9+, Flask 2.0+
Database PostgreSQL / SQLite
ORM SQLAlchemy
Frontend HTML5, CSS3, JavaScript
Icons Material Icons
Authentication Flask-Login
Migrations Flask-Migrate

📋 المتطلبات

  • Python 3.9 أو أحدث
  • PostgreSQL 13+ (للإنتاج) أو SQLite (للتطوير)
  • pip (مدير حزم Python)

🚀 التثبيت

1. استنساخ المشروع

git clone https://github.com/hany-php/taqsit-python.git
cd taqsit-python

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

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

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

3. تثبيت المتطلبات

pip install -r requirements.txt

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

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

# تعديل الإعدادات حسب بيئتك

محتوى ملف .env:

# Flask Configuration
FLASK_APP=run.py
FLASK_ENV=development
SECRET_KEY=your-secret-key-here

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/taqsit
# أو للتطوير المحلي:
# DATABASE_URL=sqlite:///taqsit.db

# Mail (Optional)
MAIL_SERVER=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password

5. إعداد قاعدة البيانات

# إنشاء الجداول
flask db upgrade

# إضافة بيانات تجريبية (اختياري)
python seed_data.py

6. تشغيل التطبيق

# للتطوير
flask run --host=0.0.0.0 --port=5000

# للإنتاج (مع Gunicorn)
gunicorn -w 4 -b 0.0.0.0:5000 run:app

7. الوصول للتطبيق

افتح المتصفح على: http://localhost:5000

بيانات الدخول الافتراضية:

  • المستخدم: admin
  • كلمة المرور: admin123

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

taqsit-python/
├── app/
│   ├── __init__.py          # تهيئة التطبيق
│   ├── controllers/          # المتحكمات (Routes)
│   │   ├── auth.py
│   │   ├── customers.py
│   │   ├── dashboard.py
│   │   ├── invoices.py
│   │   ├── products.py
│   │   ├── reports.py
│   │   └── settings.py
│   ├── models/               # نماذج قاعدة البيانات
│   │   ├── user.py
│   │   ├── customer.py
│   │   ├── product.py
│   │   ├── invoice.py
│   │   ├── installment.py
│   │   └── payment.py
│   ├── templates/            # قوالب HTML
│   ├── static/               # ملفات ثابتة (CSS, JS, Images)
│   └── utils/                # أدوات مساعدة
├── migrations/               # ملفات الهجرة
├── backups/                  # النسخ الاحتياطية
├── config.py                 # إعدادات التطبيق
├── requirements.txt          # المتطلبات
├── run.py                    # نقطة تشغيل التطبيق
└── .env.example              # مثال ملف البيئة

🔌 API

يوفر النظام API للتكامل مع أنظمة أخرى:

المصادقة

جميع طلبات الـ API تتطلب مفتاح في الـ Header:

X-API-Key: your-api-key

نقاط النهاية المتاحة

Method Endpoint الوصف
GET /api/v1/customers قائمة العملاء
GET /api/v1/customers/{id} بيانات عميل
GET /api/v1/products قائمة المنتجات
GET /api/v1/invoices قائمة الفواتير
GET /api/v1/installments/overdue الأقساط المتأخرة
GET /api/v1/stats إحصائيات عامة

مثال استخدام

import requests

headers = {'X-API-Key': 'your-api-key'}
response = requests.get('http://localhost:5000/api/v1/customers', headers=headers)
print(response.json())

🔧 الإعدادات

إعدادات التقسيط

من لوحة التحكم > الإعدادات > إعدادات التقسيط:

  • عدد أشهر التقسيط الافتراضي: الفترة الافتراضية للتقسيط
  • نسبة غرامة التأخير: نسبة الغرامة على الأقساط المتأخرة
  • أيام السماح: فترة السماح قبل احتساب التأخير
  • التذكير قبل الاستحقاق: عدد أيام التذكير المسبق

خطط التقسيط

يمكن إنشاء خطط تقسيط متعددة مع:

  • عدد الأشهر
  • نسبة الزيادة
  • الحد الأدنى للمقدم

💾 النسخ الاحتياطي

يدعم النظام ثلاثة أنواع من النسخ الاحتياطي:

  1. نسخة كاملة: قاعدة البيانات + جميع ملفات المشروع
  2. قاعدة البيانات فقط: تصدير JSON لجميع البيانات
  3. الملفات فقط: ملفات المشروع والصور

من لوحة التحكم > الإعدادات > النسخ الاحتياطي

🚀 النشر (Deployment)

Render.com

  1. أنشئ حساب على Render
  2. أنشئ Web Service جديد
  3. اربط مستودع GitHub
  4. أضف المتغيرات البيئية
  5. انشر!

Railway

railway login
railway init
railway up

Docker

FROM python:3.9-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
EXPOSE 5000
CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:5000", "run:app"]

🤝 المساهمة

نرحب بمساهماتك!

  1. Fork المشروع
  2. أنشئ branch جديد (git checkout -b feature/amazing-feature)
  3. Commit التغييرات (git commit -m 'Add amazing feature')
  4. Push للـ branch (git push origin feature/amazing-feature)
  5. افتح Pull Request

إرشادات المساهمة

  • اتبع نمط الكود الموجود
  • أضف اختبارات للميزات الجديدة
  • حدّث التوثيق
  • اكتب رسائل commit واضحة

📝 الترخيص

هذا المشروع مرخص تحت MIT License.

📞 الدعم

🙏 شكر خاص

صُنع بـ ❤️ في مصر