ساختار پروژه و الگوهای طراحی

معماری، لایه‌ها، permissionها، کش و استانداردهای کدنویسی

ساختار دایرکتوری

مسیر	توضیح
`Configurations/`	settings, urls ریشه, wsgi
`Accounts/`	User، OTP، JWT
`RBAC/`	نقش‌ها و دسترسی‌ها (Permission/Role/API/Sync)
`Agents/`	پروفایل مشاور
`Properties/`	ملک، شهر، منطقه، نوع، مالک + cache_service + signals
`Staff/`	پرسنل + FK نقش سازمانی
`Tracking/`	رصد املاک، ورک‌لاین، تأیید، لاگ
`Notifications/`	اعلان‌ها و unread badge
`Notes/`	یادداشت‌های شخصی کاربر (تاریخ‌دار/وضعیت‌دار)
`Tasks/`	تسک مرحله‌ای، ارجاع بین کاربران، رصد کامل
`Reports/`	آمار داشبورد، KPI، روند هفتگی، کاتالوگ گزارش
`Documents/`	مستندات HTML
`media/`	آپلودها
`static/`	CSS/JS داک

الگوهای طراحی

1) APIView

کنترل کامل روی متدها، permission و پاسخ‌ها.

2) Serializer جدا

Read Serializer برای لیست/جزئیات
Create Serializer برای ثبت
Update Serializer برای ویرایش جزئی و مدیریت تصاویر

3) Permission سفارشی

IsAdmin / IsStaff / IsAgent — نوع کاربری
HasAccess — دسترسی ریزدانه‌ای staff بر اساس کد نقش
IsAdminOrStaffOrAgentReadOnly — خواندن برای مشاور، نوشتن فقط admin/staff
IsPropertyAgentOrAdminOrStaff — object-level روی ملک
جزئیات کامل: RBAC

4) Query Optimization

PropertyModel.objects.select_related(
    'agent', 'owner', 'city', 'location', 'property_type'
).prefetch_related('images')

5) Caching با version bump

from Properties.services.cache_service import (
    get_dashboard_cache, get_user_cache_scope, set_dashboard_cache,
    invalidate_property_dashboard_cache,
)
# کلید: property_dashboard:v{version}:{scope}:{hash}
# invalidation: post_save / post_delete روی PropertyModel

قرارداد REST فعلی Properties

Method	Path	کار
GET	/properties/list/	لیست
POST	/properties/create/	ایجاد + duplicate check
GET	/properties/<slug>/	جزئیات
PUT	/properties/<slug>/	ویرایش
DELETE	/properties/<slug>/	حذف
PATCH	/properties/<slug>/edit/	ویرایش تخصصی

جریان احراز هویت

request-otp → ذخیره OTP در cache (TTL 120s)
verify-otp → JWT pair
استفاده از Bearer در درخواست‌های خصوصی
refresh قبل از انقضا

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

Models/Views/Serializers: PascalCase
functions/variables: snake_case
پیام خطا فارسی، کامنت انگلیسی
منطق سنگین در serializer/service نه در view چاق

امنیت

Permission روی هر endpoint
Rate limit روی OTP
Refresh token rotation + blacklist
در production: DEBUG=False و HTTPS