8.8 KiB
Executable file
8.8 KiB
Executable file
📦 سیستم فضای ذخیره‌سازی (Storage Plans System)
📌 مقدمه
سیستم فضای ذخیره‌سازی به کاربران امکان الصاق فایل‌های مختلف (عکس، فیلم، اسناد و ...) به اسناد حسابداری و سایر بخش‌های نرم‌افزار را می‌دهد. این سیستم با پلن‌های قابل تنظیم و ادغام با کیف پول کار می‌کند.
🎯 ویژگی‌های اصلی
- پلن‌های قابل تنظیم: مدیر می‌تواند پلن‌های مختلف با دوره‌های مختلف (ماهانه، سالانه، مادام‌العمر) ایجاد کند
- چند پلن همزمان: کاربران می‌توانند چندین پلن را همزمان فعال کنند (مثلاً بسته 1 گیگ 3 ماهه و بسته 7 گیگ یک ساله)
- استفاده اضافی: در صورت تجاوز از محدودیت، صورتحساب فوری با تمایل کاربر ایجاد می‌شود
- ادغام با کیف پول: تمام صورتحساب‌ها از کیف پول پرداخت می‌شوند
- حذف خودکار: بعد از انقضای اشتراک و تمام شدن grace period، فایل‌ها به صورت خودکار حذف می‌شوند
- دانلود ZIP: کاربران می‌توانند تمام فایل‌های کسب‌وکار خود را به صورت ZIP دانلود کنند
📊 ساختار دیتابیس
جداول جدید
- storage_plans: پلن‌های ذخیره‌سازی
- business_storage_subscriptions: اشتراک‌های کسب‌وکار
- storage_invoices: صورتحساب‌های ذخیره‌سازی
- storage_usage_transactions: تراکنش‌های استفاده
تغییرات در file_storage
business_id: شناسه کسب‌وکار مالک فایلsubscription_id: پلن فعال در زمان آپلودis_marked_for_deletion: علامت برای حذف خودکارmarked_for_deletion_at: زمان علامت‌گذاری
🔧 سرویس‌ها
storage_plan_service.py
create_storage_plan(): ایجاد پلن جدیدupdate_storage_plan(): ویرایش پلنget_storage_plan(): دریافت جزئیات پلنlist_storage_plans(): لیست پلن‌هاdelete_storage_plan(): حذف/غیرفعال کردن پلن
storage_subscription_service.py
subscribe_to_plan(): اشتراک به یک پلنget_active_subscriptions(): دریافت اشتراک‌های فعالcalculate_total_storage_limit(): محاسبه کل محدودیتcalculate_storage_usage(): محاسبه استفاده فعلیcheck_storage_limit(): بررسی محدودیتrenew_subscription(): تمدید اشتراکcancel_subscription(): لغو اشتراکcheck_expired_subscriptions(): بررسی انقضای اشتراک‌ها
storage_invoice_service.py
create_subscription_invoice(): ایجاد صورتحساب اشتراکcreate_over_usage_invoice(): ایجاد صورتحساب استفاده اضافیcreate_renewal_invoice(): ایجاد صورتحساب تمدیدpay_storage_invoice_from_wallet(): پرداخت از کیف پولlist_storage_invoices(): لیست صورتحساب‌هاget_storage_invoice(): دریافت جزئیات صورتحساب
storage_cleanup_service.py
mark_files_for_deletion(): علامت‌گذاری فایل‌ها برای حذفdelete_marked_files(): حذف فایل‌های علامت‌گذاری شدهcleanup_expired_files(): اجرای کامل فرآیند پاک‌سازی
storage_export_service.py
export_business_files_as_zip(): ایجاد فایل ZIPget_export_info(): دریافت اطلاعات فایل‌های قابل دانلود
🌐 API Endpoints
Admin Endpoints
POST /api/v1/admin/storage-plans
ایجاد پلن جدید
Body:
{
"name": "پلن پایه",
"code": "basic_1gb_3m",
"storage_limit_gb": 1.0,
"period": "monthly",
"period_months": 3,
"price": 50000,
"price_per_gb": 10000,
"is_free": false,
"currency_id": 1,
"description": "پلن پایه 1 گیگابایت 3 ماهه",
"grace_period_days": 30
}
PUT /api/v1/admin/storage-plans/{plan_id}
ویرایش پلن
GET /api/v1/admin/storage-plans
لیست پلن‌ها
GET /api/v1/admin/storage-plans/{plan_id}
جزئیات پلن
DELETE /api/v1/admin/storage-plans/{plan_id}
حذف/غیرفعال کردن پلن
Business Endpoints
GET /api/v1/business/{business_id}/storage/subscriptions
لیست اشتراک‌های فعال
POST /api/v1/business/{business_id}/storage/subscribe
اشتراک به یک پلن
Body:
{
"plan_id": 1,
"auto_renew": false
}
PUT /api/v1/business/{business_id}/storage/subscription/{subscription_id}/renew
تمدید اشتراک
DELETE /api/v1/business/{business_id}/storage/subscription/{subscription_id}
لغو اشتراک
GET /api/v1/business/{business_id}/storage/usage
آمار استفاده
GET /api/v1/business/{business_id}/storage/plans
لیست پلن‌های قابل اشتراک
GET /api/v1/business/{business_id}/storage/invoices
لیست صورتحساب‌ها
POST /api/v1/business/{business_id}/storage/invoices/{invoice_id}/pay
پرداخت صورتحساب از کیف پول
POST /api/v1/business/{business_id}/storage/pay-over-usage
پرداخت برای استفاده اضافی
Body:
{
"over_usage_gb": 0.5,
"file_size_bytes": 536870912
}
GET /api/v1/business/{business_id}/storage/export-zip
دانلود ZIP تمام فایل‌ها
Query Parameters:
module_context(optional): فیلتر بر اساس modulefrom_date(optional): از تاریخto_date(optional): تا تاریخ
GET /api/v1/business/{business_id}/storage/export-info
اطلاعات فایل‌های قابل دانلود
🔄 Background Jobs
storage_cleanup_loop
هر 24 ساعت یکبار اجرا می‌شود:
- بررسی اشتراک‌های منقضی شده
- علامت‌گذاری فایل‌ها برای حذف
- حذف فایل‌های علامت‌گذاری شده (بعد از 7 روز)
storage_subscription_check_loop
هر 6 ساعت یکبار اجرا می‌شود:
- بررسی اشتراک‌های منقضی شده
- به‌روزرسانی وضعیت اشتراک‌ها
📝 Migration
برای اجرای migration:
cd hesabixAPI
alembic upgrade head
Migration شامل:
- ایجاد جداول جدید
- اضافه کردن فیلدهای جدید به
file_storage - ایجاد پلن رایگان پیش‌فرض (1 GB، lifetime)
🔗 یکپارچه‌سازی با سیستم موجود
File Storage Service
file_storage_service.py به‌روزرسانی شده تا:
- قبل از آپلود: بررسی محدودیت ذخیره‌سازی
- بعد از آپلود: ثبت
business_idوsubscription_id - ثبت تراکنش استفاده در
storage_usage_transactions
Wallet Service
تراکنش‌های ذخیره‌سازی در کیف پول نمایش داده می‌شوند:
storage_subscription: پرداخت اشتراکstorage_over_usage: پرداخت استفاده اضافیstorage_renewal: تمدید اشتراک
🎨 Frontend (Flutter)
صفحات مورد نیاز
-
Admin:
storage_plans_admin_page.dart: مدیریت پلن‌ها
-
Business:
storage_subscription_page.dart: مدیریت اشتراکstorage_plans_page.dart: لیست پلن‌ها برای اشتراکstorage_invoices_page.dart: صورتحساب‌هاstorage_files_page.dart: مدیریت فایل‌هاstorage_export_page.dart: دانلود ZIP
ویجت‌ها
storage_usage_widget.dart: نمایش استفادهstorage_limit_warning_dialog.dart: هشدار محدودیتstorage_over_usage_dialog.dart: دیالوگ استفاده اضافی
⚠️ نکات مهم
- محاسبه حجم: تبدیل بایت به گیگابایت با دقت 6 رقم اعشار
- محدودیت فایل: حداکثر حجم هر فایل (مثلاً 500MB)
- Grace Period: قابل تنظیم در هر پلن (پیش‌فرض: 30 روز)
- چند پلن همزمان: محدودیت‌ها جمع می‌شوند
- استفاده اضافی: صورتحساب فوری با تمایل کاربر
🚀 مراحل بعدی
- ✅ ایجاد مدل‌ها و migration
- ✅ ایجاد سرویس‌ها
- ✅ ایجاد API endpoints
- ✅ تنظیم background jobs
- ⏳ پیاده‌سازی Frontend
- ⏳ تست کامل سیستم