hesabixArc/hesabixAPI/docs/PERMISSIONS_SYSTEM.md

سیستم دسترسی دو سطحی

این سیستم دسترسی‌ها را در دو سطح جداگانه مدیریت می‌کند:

1. دسترسی‌های اپلیکیشن (App-Level Permissions)

در users.app_permissions ذخیره می‌شود و شامل:

دسترسی‌های موجود:

• superadmin: دسترسی کامل به سیستم
• user_management: مدیریت کاربران در سطح اپلیکیشن
• business_management: مدیریت کسب و کارها
• system_settings: دسترسی به تنظیمات سیستم

مثال JSON:

{
  "superadmin": true,
  "user_management": true,
  "business_management": true
}

2. دسترسی‌های کسب و کار (Business-Level Permissions)

در business_permissions.business_permissions ذخیره می‌شود و شامل:

بخش‌های موجود:

• sales: فروش
• purchases: خرید
• accounting: حسابداری
• inventory: موجودی
• reports: گزارش‌ها
• settings: تنظیمات کسب و کار
• marketing: بازاریابی

عملیات‌های موجود:

• read: خواندن
• write: نوشتن
• delete: حذف
• approve: تأیید
• export: صادرات
• manage_users: مدیریت کاربران (فقط در settings)

مثال JSON:

{
  "sales": {
    "write": true,
    "delete": true,
    "approve": true
  },
  "accounting": {
    "write": true
  },
  "reports": {
    "export": true
  },
  "settings": {
    "manage_users": true
  }
}

نحوه استفاده

1. بررسی دسترسی در AuthContext:

# دسترسی‌های اپلیکیشن
ctx.has_app_permission("superadmin")
ctx.is_superadmin()
ctx.can_manage_users()
ctx.can_manage_businesses()

# دسترسی‌های کسب و کار
ctx.has_business_permission("sales", "write")
ctx.can_read_section("sales")
ctx.can_write_section("sales")
ctx.can_delete_section("sales")
ctx.can_approve_section("sales")
ctx.can_export_section("reports")
ctx.can_manage_business_users()

# ترکیب دسترسی‌ها
ctx.has_any_permission("sales", "write")  # app یا business
ctx.can_access_business(business_id)

2. استفاده از Decorator ها:

from app.core.permissions import (
    require_superadmin,
    require_user_management,
    require_sales_write,
    require_business_access
)

# دسترسی اپلیکیشن
@require_superadmin()
def admin_function():
    pass

@require_user_management()
def manage_users():
    pass

# دسترسی کسب و کار
@require_business_access("business_id")
@require_sales_write()
def create_sale(business_id: int):
    pass

3. بررسی دسترسی در API:

@router.post("/business/{business_id}/sales")
def create_sale(
    business_id: int,
    ctx: AuthContext = Depends(get_current_user)
):
    # بررسی دسترسی به کسب و کار
    if not ctx.can_access_business(business_id):
        raise ApiError("FORBIDDEN", "No access to this business")
    
    # بررسی دسترسی نوشتن فروش
    if not ctx.has_business_permission("sales", "write"):
        raise ApiError("FORBIDDEN", "No permission to create sales")
    
    # ایجاد فروش
    pass

قوانین دسترسی

1. SuperAdmin:

• دسترسی خودکار: تمام دسترسی‌های اپلیکیشن را خودکار دارد
• دسترسی کامل: به تمام بخش‌های سیستم دسترسی دارد
• دسترسی کسب و کار: می‌تواند به هر کسب و کاری دسترسی داشته باشد
• تمام عملیات: تمام عملیات را می‌تواند انجام دهد

2. مالک کسب و کار:

• دسترسی اپلیکیشن: فقط دسترسی‌های مشخص شده در app_permissions
• دسترسی خودکار کسب و کار: تمام دسترسی‌های کسب و کار خود را خودکار دارد
• دسترسی کامل: تمام عملیات در کسب و کار خود را می‌تواند انجام دهد
• مدیریت کاربران: می‌تواند کاربران کسب و کار خود را مدیریت کند

3. کاربران عادی:

• دسترسی اپلیکیشن: فقط دسترسی‌های مشخص شده در app_permissions
• دسترسی کسب و کار: دسترسی‌های مشخص شده در business_permissions
• دسترسی محدود: فقط به کسب و کارهای خود دسترسی دارند
• قوانین بخش: اگر بخش در دسترسی‌ها وجود دارد اما خالی است، فقط خواندن مجاز است

3. ذخیره‌سازی بهینه:

• فقط دسترسی‌های موجود ذخیره می‌شود
• false یا null ذخیره نمی‌شود
• کاهش حجم داده و بهبود عملکرد

مثال‌های عملی

کاربر مدیر فروش:

{
  "app_permissions": {},
  "business_permissions": {
    "sales": {
      "write": true,
      "delete": true,
      "approve": true
    },
    "inventory": {
      "write": true
    }
  }
}

کاربر کارمند حسابداری:

{
  "app_permissions": {},
  "business_permissions": {
    "accounting": {
      "write": true
    },
    "reports": {
      "export": true
    }
  }
}

SuperAdmin:

{
  "app_permissions": {
    "superadmin": true
  },
  "business_permissions": {}  // دسترسی کامل به همه
}

// نتایج:
// - has_app_permission("user_management") → True (خودکار)
// - has_app_permission("business_management") → True (خودکار)
// - has_business_permission("sales", "write") → True (برای هر کسب و کار)
// - is_superadmin() → True
// - is_business_owner() → False (مگر اینکه مالک کسب و کار باشد)

مالک کسب و کار:

{
  "app_permissions": {},
  "business_permissions": {
    "sales": {"write": true, "delete": true}
  }
}

// نتایج:
// - has_app_permission("user_management") → False
// - has_business_permission("sales", "write") → True (از JSON)
// - has_business_permission("accounting", "write") → True (خودکار - مالک)
// - has_business_permission("reports", "export") → True (خودکار - مالک)
// - is_business_owner() → True

توسعه سیستم

اضافه کردن بخش جدید:

# فقط در business_permissions اضافه می‌شود
{
  "new_section": {
    "write": true,
    "approve": true
  }
}

اضافه کردن عملیات جدید:

# در هر بخش قابل اضافه کردن
{
  "sales": {
    "write": true,
    "new_action": true
  }
}

اضافه کردن دسترسی اپلیکیشن جدید:

# در app_permissions اضافه می‌شود
{
  "new_app_permission": true
}