ابزار پردازش فایل‌های اکسل

یک سرویس وب یکپارچه برای پردازش و ادغام فایل‌های اکسل با رابط کاربری فارسی

پیش‌نمایش

معماری پروژه

این پروژه با استفاده از Feature-Sliced Design (FSD) و FastAPI طراحی شده است. کد به صورت ماژولار و بر اساس ویژگی‌های کسب‌وکار سازمان‌دهی شده است، نه لایه‌های فنی. هر ویژگی در پوشه خودش قرار دارد و می‌تواند به صورت مستقل حذف یا اضافه شود.

مزایای معماری

• جداسازی ویژگی‌ها: هر ویژگی در پوشه خودش قرار دارد
• قابلیت توسعه: افزودن ویژگی جدید با ایجاد یک پوشه جدید
• قابلیت نگهداری: مرزهای واضح و جداسازی نگرانی‌ها
• قابلیت تست: ویژگی‌ها به صورت مستقل قابل تست هستند
• API بدون حالت: استفاده از File ID به جای Session برای مقیاس‌پذیری

ویژگی‌ها

• ادغام فایل‌ها: ترکیب چندین فایل اکسل در یک فایل واحد
• پیدا کردن و ادغام تکراری‌ها: شناسایی ردیف‌های تکراری و ادغام آن‌ها با جمع‌آوری مقادیر عددی
• مرتب‌سازی: مرتب‌سازی داده‌ها بر اساس ستون انتخابی (صعودی یا نزولی)
• تبدیل اعداد: تبدیل اعداد فارسی (۰-۹) به انگلیسی (0-9) و بالعکس
• فیلتر داده: فیلتر داده‌ها بر اساس شرایط مختلف
• مدیریت ستون‌ها: حذف، تغییر نام، و مرتب‌سازی مجدد ستون‌ها
• جستجو و جایگزینی: جستجو و جایگزینی متن در ستون‌های مشخص
• تبدیل نوع داده: تبدیل نوع داده ستون‌ها (عدد، متن، تاریخ و ...)
• ستون‌های محاسباتی: افزودن ستون‌های محاسباتی با فرمول‌های مختلف
• تقسیم داده: تقسیم داده به چند فایل بر اساس ستون یا تعداد ردیف
• پشتیبانی از فارسی و انگلیسی: شناسایی خودکار ستون‌ها با نام‌های فارسی و انگلیسی
• رابط کاربری فارسی: رابط کاربری زیبا و کاربرپسند با پشتیبانی کامل از راست‌چین

نیازمندی‌ها

برای اجرای مستقیم:

• Python 3.11 یا بالاتر
• مرورگر وب مدرن

برای اجرای با Docker:

• Docker installed (Install Docker)
• Docker Compose installed (usually included with Docker Desktop)

نصب

1. ایجاد و فعال‌سازی محیط مجازی (توصیه می‌شود):

python3 -m venv venv
source venv/bin/activate  # در ویندوز: venv\Scripts\activate

2. نصب وابستگی‌ها:

pip install -r requirements.txt

استفاده

روش 1: اجرای مستقیم (Development)

1. اجرای برنامه:

uvicorn app.main:app --host 0.0.0.0 --port 5000 --reload

یا:

python -m uvicorn app.main:app --host 0.0.0.0 --port 5000

2. باز کردن مرورگر و رفتن به آدرس:

http://localhost:5000

روش 2: استفاده از Docker (توصیه می‌شود)

روش 2-1: استفاده از Docker Compose (توصیه می‌شود)

1. ساخت و اجرای کانتینر:

   docker compose up -d

2. مشاهده لاگ‌ها:

   docker compose logs -f

3. توقف سرویس:

   docker compose down

4. بازسازی کانتینر (پس از تغییرات):

   docker compose up -d --build

روش 2-2: استفاده مستقیم از Docker

1. ساخت تصویر:

   docker build -t excel-processor .

2. اجرای کانتینر:

   docker run -d \
     --name excel-processing-service \
     -p 5000:5000 \
     -v $(pwd)/uploads:/app/uploads \
     -v $(pwd)/output:/app/output \
     excel-processor

3. مشاهده لاگ‌ها:

   docker logs -f excel-processing-service

4. توقف کانتینر:

   docker stop excel-processing-service
   docker rm excel-processing-service

دسترسی به برنامه

پس از اجرای کانتینر، برنامه در آدرس زیر در دسترس است:

http://localhost:5000

تنظیمات Docker

تغییر پورت:

برای تغییر پورت در docker-compose.yml:

ports:
  - "8080:5000"  # پورت خارجی:پورت داخلی

یا در دستور Docker:

docker run -d -p 8080:5000 ...

متغیرهای محیطی:

می‌توانید متغیرهای محیطی را در docker-compose.yml تنظیم کنید:

environment:
  - HOST=0.0.0.0
  - PORT=5000
  - FLASK_DEBUG=0

مدیریت داده‌ها:

• فایل‌های آپلود شده در پوشه uploads/ ذخیره می‌شوند
• فایل‌های پردازش شده در پوشه output/ ذخیره می‌شوند
• این پوشه‌ها به صورت volume به کانتینر متصل شده‌اند

عیب‌یابی Docker

بررسی وضعیت کانتینر:

docker ps

بررسی لاگ‌های خطا:

docker-compose logs excel-processor

ورود به کانتینر:

docker exec -it excel-processing-service bash

بازسازی کامل:

docker-compose down
docker-compose build --no-cache
docker-compose up -d

به‌روزرسانی

برای به‌روزرسانی برنامه:

# دریافت آخرین تغییرات
git pull

# بازسازی و راه‌اندازی مجدد
docker-compose up -d --build

تولید (Production)

برای محیط تولید، توصیه می‌شود:

1. استفاده از uvicorn با workers متعدد
2. تنظیم reverse proxy (Nginx)
3. استفاده از HTTPS
4. تنظیم محدودیت‌های امنیتی

مثال با uvicorn workers:

uvicorn app.main:app --host 0.0.0.0 --port 5000 --workers 4

استفاده از رابط کاربری:

• آپلود فایل‌های اکسل (می‌توانید چند فایل را همزمان آپلود کنید)
• انتخاب گزینه‌های پردازش مورد نظر
• تنظیم گزینه‌های پیشرفته (ستون‌های گروه‌بندی، مرتب‌سازی و ...)
• کلیک روی دکمه "پردازش فایل‌ها"
• دانلود فایل پردازش شده

ساختار پروژه

Unified_Excel_Service/
├── app/                              # برنامه اصلی FastAPI
│   ├── __init__.py                   # Export اصلی
│   ├── main.py                       # نقطه ورود برنامه
│   ├── config.py                     # تنظیمات برنامه
│   │
│   ├── shared/                       # ابزارهای مشترک
│   │   ├── storage/                  # مدیریت فایل
│   │   │   ├── manager.py            # مدیریت ذخیره‌سازی فایل
│   │   │   └── cleanup.py            # پاکسازی فایل‌های موقت
│   │   ├── excel/                    # ابزارهای اکسل
│   │   │   ├── reader.py             # خواندن ایمن فایل اکسل
│   │   │   ├── column_detector.py    # شناسایی ستون‌ها
│   │   │   └── number_converter.py   # تبدیل اعداد فارسی/انگلیسی
│   │   └── responses.py              # فرمت پاسخ‌های API
│   │
│   ├── features/                     # ماژول‌های ویژگی (FSD)
│   │   ├── __init__.py               # ثبت ویژگی‌ها
│   │   │
│   │   ├── file_upload/              # ویژگی: آپلود فایل
│   │   │   ├── api.py                # مسیرهای FastAPI
│   │   │   ├── service.py            # منطق کسب‌وکار
│   │   │   └── models.py             # مدل‌های Pydantic
│   │   │
│   │   ├── file_preview/             # ویژگی: پیش‌نمایش داده
│   │   ├── statistics/               # ویژگی: آمار و خلاصه
│   │   ├── processing/               # ویژگی: پردازش (Orchestration)
│   │   │   ├── api.py
│   │   │   ├── service.py
│   │   │   ├── models.py
│   │   │   └── pipeline.py           # ساختار خط پردازش
│   │   │
│   │   ├── processors/               # پردازش‌گرهای فردی
│   │   │   ├── __init__.py           # ثبت پردازش‌گرها
│   │   │   ├── concatenate/          # ادغام فایل‌ها
│   │   │   ├── duplicate_detection/  # شناسایی تکراری‌ها
│   │   │   ├── sorting/              # مرتب‌سازی
│   │   │   ├── number_conversion/    # تبدیل اعداد
│   │   │   ├── filtering/            # فیلتر داده
│   │   │   ├── column_removal/       # حذف ستون
│   │   │   ├── column_rename/        # تغییر نام ستون
│   │   │   ├── column_reorder/       # مرتب‌سازی ستون
│   │   │   ├── find_replace/         # جستجو و جایگزینی
│   │   │   ├── type_conversion/      # تبدیل نوع داده
│   │   │   ├── calculated_column/    # ستون محاسباتی
│   │   │   ├── data_splitting/       # تقسیم داده
│   │   │   ├── amount_normalization/  # یکسان‌سازی Amount
│   │   │   ├── aggregation/          # تجمع داده
│   │   │   └── mobile_exclusion/     # حذف بر اساس موبایل
│   │   │
│   │   └── file_download/            # ویژگی: دانلود فایل
│   │
│   └── middleware/                   # Middleware سراسری
│       ├── error_handler.py          # مدیریت خطا
│       └── cleanup.py                # پاکسازی پس‌زمینه
│
├── static/                           # فایل‌های استاتیک
│   ├── css/
│   │   ├── base.css                  # استایل‌های پایه
│   │   └── features/                 # استایل‌های ویژگی‌محور
│   │       ├── file-upload.css
│   │       ├── processing-options.css
│   │       ├── preview.css
│   │       ├── statistics.css
│   │       └── download.css
│   ├── js/
│   │   ├── app.js                    # برنامه اصلی
│   │   ├── api/                      # کلاینت API
│   │   │   ├── client.js
│   │   │   └── endpoints.js
│   │   └── features/                 # ماژول‌های ویژگی
│   │       ├── file-upload/
│   │       ├── preview/
│   │       ├── statistics/
│   │       └── processing/
│   │   └── utils/                     # ابزارهای مشترک
│   │       ├── file-id-manager.js
│   │       └── error-handler.js
│
├── templates/
│   └── index.html                    # رابط کاربری HTML
│
├── uploads/                          # فایل‌های آپلود شده (موقت)
├── output/                           # فایل‌های پردازش شده
│
├── requirements.txt                  # وابستگی‌های Python
├── Dockerfile                        # تصویر Docker
├── docker-compose.yml                # تنظیمات Docker Compose
└── README.md                         # این فایل

گزینه‌های پردازش

1. ادغام فایل‌ها

همه فایل‌های آپلود شده را در یک فایل واحد ترکیب می‌کند.

2. پیدا کردن و ادغام تکراری‌ها

• ردیف‌های تکراری را بر اساس ستون‌های انتخابی شناسایی می‌کند
• مقادیر عددی را جمع می‌زند
• ستون "تعداد تکرار" را اضافه می‌کند که نشان می‌دهد هر ردیف چند بار تکرار شده است

3. مرتب‌سازی بر اساس ستون

• انتخاب ستون برای مرتب‌سازی
• انتخاب جهت مرتب‌سازی (صعودی یا نزولی)

4. تبدیل اعداد فارسی به انگلیسی

همه اعداد فارسی (۰۱۲۳۴۵۶۷۸۹) را به اعداد انگلیسی (0123456789) تبدیل می‌کند.

5. تبدیل اعداد انگلیسی به فارسی

همه اعداد انگلیسی (0123456789) را به اعداد فارسی (۰۱۲۳۴۵۶۷۸۹) تبدیل می‌کند.

6. فیلتر داده

فیلتر داده‌ها بر اساس شرایط مختلف (برابر، شامل، بزرگتر از، کوچکتر از و ...)

7. مدیریت ستون‌ها

• حذف ستون‌های مشخص
• تغییر نام ستون‌ها
• مرتب‌سازی مجدد ستون‌ها

8. جستجو و جایگزینی

جستجو و جایگزینی متن در ستون‌های مشخص

9. تبدیل نوع داده

تبدیل نوع داده ستون‌ها (عدد صحیح، اعشاری، متن، تاریخ، بولین)

10. ستون‌های محاسباتی

افزودن ستون‌های محاسباتی با فرمول‌های مختلف (جمع، میانگین، ضرب، تقسیم و ...)

11. تقسیم داده

تقسیم داده به چند فایل بر اساس ستون یا تعداد ردیف

شناسایی خودکار ستون‌ها

برنامه به طور خودکار ستون‌های زیر را شناسایی می‌کند:

نام ستون‌های فارسی:

• نام: نام، نام و نام خانوادگی، نام خانوادگی
• تلفن: شماره تماس، تلفن، موبایل
• تعداد: تعداد، تعداد اعلام حضور، شمارش

نام ستون‌های انگلیسی:

• نام: name
• تلفن: phone
• تعداد: count

API Endpoints

آپلود فایل

• POST /api/upload - آپلود فایل‌های اکسل
• POST /api/upload-exclusion - آپلود فایل استثنا برای حذف موبایل

پیش‌نمایش و آمار

• POST /api/preview - پیش‌نمایش داده‌ها
• POST /api/statistics - دریافت آمار و خلاصه

پردازش

• POST /api/process - پردازش فایل‌ها با گزینه‌های انتخابی

دانلود

• GET /api/download/{filename} - دانلود فایل پردازش شده

پشتیبانی از فرمت‌ها

• .xlsx (Excel 2007+)
• .xls (Excel 97-2003)

نکات مهم

• حداکثر اندازه فایل: 100 مگابایت
• فایل‌های آپلود شده به صورت موقت ذخیره می‌شوند و پس از پردازش پاک می‌شوند
• در صورت بروز خطا، پیام خطا به فارسی نمایش داده می‌شود
• API بدون حالت است و از File ID برای مدیریت فایل‌ها استفاده می‌کند

توسعه و افزودن ویژگی جدید

برای افزودن یک ویژگی جدید:

1. ایجاد پوشه ویژگی در app/features/
2. ایجاد فایل‌های api.py, service.py, models.py
3. ثبت router در app/features/__init__.py
4. ویژگی به صورت خودکار در برنامه ثبت می‌شود

برای افزودن یک پردازش‌گر جدید:

1. ایجاد پوشه پردازش‌گر در app/features/processors/
2. پیاده‌سازی تابع process(df, config) در processor.py
3. ثبت پردازش‌گر در app/features/processors/__init__.py
4. پردازش‌گر در خط پردازش در دسترس خواهد بود

عیب‌یابی

مشکلات عمومی

مشکل: "ModuleNotFoundError"

• راه حل: وابستگی‌ها را نصب کنید: pip install -r requirements.txt

مشکل: "خطا در خواندن فایل"

• راه حل: مطمئن شوید فایل اکسل معتبر است و فرمت صحیح دارد (.xlsx یا .xls)

مشکل: "هیچ فایلی برای پردازش یافت نشد"

• راه حل: ابتدا فایل‌ها را آپلود کنید و سپس روی دکمه پردازش کلیک کنید

مشکل: "ImportError"

• راه حل: مطمئن شوید که از Python 3.11 یا بالاتر استفاده می‌کنید

مشکلات Docker

برای مشکلات Docker، به بخش "عیب‌یابی Docker" در بالا مراجعه کنید.

مجوز

این پروژه برای اهداف پردازش داده ارائه شده است.

مشارکت

می‌توانید این برنامه را برای نیازهای خاص خود تغییر دهید.