Reports — گزارش و آمار داشبورد

چرا این آمار؟

به‌جای «ثبت ملک و ثبت کاربر»، داشبورد عملیات واقعی آژانس را نشان می‌دهد:

• ارجاع vs فروش — ورودی کار تأییدشده در برابر خروجی فروش
• KPIهای عملیاتی — صف تأیید، رصد فعال، overdue، تسک‌های عقب‌افتاده

۱) KPIهای داشبورد

GET /reports/dashboard/kpis/

دسترسی: سیستم‌منیجر / ادمین

نمونه پاسخ:

{
  "as_of": "2026-07-19T15:10:00+00:00",
  "week": {
    "label": "هفته اخیر",
    "start": "2026-07-18",
    "end": "2026-07-24"
  },
  "kpis": {
    "pending_approval": 7,
    "active_tracking": 12,
    "overdue_tracking": 2,
    "sold_this_week": 3,
    "referred_this_week": 8,
    "open_tasks": 15,
    "overdue_tasks": 4,
    "registered_today": 2
  }
}

۲) روند هفتگی (چارت دوخطی)

GET /reports/dashboard/weekly-trend/
GET /reports/dashboard/weekly-trend/?metric=referral_vs_sold&range=week
GET /reports/dashboard/weekly-trend/?metric=register_vs_approve&range=last_week
GET /reports/dashboard/weekly-trend/?metric=tasks_created_vs_done&range=week

Query params

متریک‌های آماده

نمونه پاسخ (پیش‌فرض referral_vs_sold):

{
  "metric": "referral_vs_sold",
  "title": "روند ارجاع و فروش املاک",
  "subtitle": "آمار هفتگی عملیات",
  "range": {
    "key": "week",
    "label": "هفته اخیر",
    "start": "2026-07-18",
    "end": "2026-07-24"
  },
  "series": [
    { "key": "referred", "label": "ارجاع‌شده", "color_hint": "purple" },
    { "key": "sold", "label": "فروخته‌شده", "color_hint": "green" }
  ],
  "points": [
    {
      "date": "2026-07-18",
      "weekday": "شنبه",
      "weekday_index": 5,
      "values": { "referred": 1, "sold": 0 }
    },
    {
      "date": "2026-07-19",
      "weekday": "یکشنبه",
      "weekday_index": 6,
      "values": { "referred": 3, "sold": 1 }
    },
    {
      "date": "2026-07-20",
      "weekday": "دوشنبه",
      "weekday_index": 0,
      "values": { "referred": 2, "sold": 0 }
    },
    {
      "date": "2026-07-21",
      "weekday": "سه‌شنبه",
      "weekday_index": 1,
      "values": { "referred": 4, "sold": 2 }
    },
    {
      "date": "2026-07-22",
      "weekday": "چهارشنبه",
      "weekday_index": 2,
      "values": { "referred": 1, "sold": 1 }
    },
    {
      "date": "2026-07-23",
      "weekday": "پنجشنبه",
      "weekday_index": 3,
      "values": { "referred": 2, "sold": 0 }
    },
    {
      "date": "2026-07-24",
      "weekday": "جمعه",
      "weekday_index": 4,
      "values": { "referred": 3, "sold": 2 }
    }
  ],
  "totals": {
    "referred": 16,
    "sold": 6
  },
  "available_metrics": [
    { "key": "referral_vs_sold", "title": "روند ارجاع و فروش املاک" },
    { "key": "register_vs_approve", "title": "روند ثبت و تأیید املاک" },
    { "key": "tasks_created_vs_done", "title": "روند تسک‌های تیم" }
  ]
}

چطور فرانت چارت را بکشد؟

1. title و subtitle را بالای کارت بگذار.
2. دراپ‌داون «هفته اخیر / هفته قبل» → پارامتر range.
3. اگر سوییچ متریک خواستی، از available_metrics یا اندپوینت catalog استفاده کن.
4. محور X: points[].weekday (شنبه … جمعه).
5. دو خط: برای هر series[].key مقدار points[].values[key].
6. color_hint فقط راهنمای رنگ است؛ الزام UI نیست.

const res = await api.get('/reports/dashboard/weekly-trend/', {
  params: { metric: 'referral_vs_sold', range: 'week' },
});

const labels = res.data.points.map((p) => p.weekday);
const seriesA = res.data.points.map((p) => p.values.referred);
const seriesB = res.data.points.map((p) => p.values.sold);
// بده به Chart.js / Recharts / ApexCharts

۳) کاتالوگ گزارش‌ها (توسعه‌پذیر)

GET /reports/catalog/

دسترسی: ادمین، یا staff با پرمیشن reports.view

این اندپوینت فهرست متریک‌ها و مسیرهای داشبورد را برمی‌گرداند تا فرانت بتواند UI گزارش را داینامیک بسازد و بعداً گزارش‌های جدید بدون hardcode اضافه شوند.

{
  "dashboard": {
    "kpis": "/reports/dashboard/kpis/",
    "weekly_trend": "/reports/dashboard/weekly-trend/"
  },
  "weekly_trend_metrics": [
    {
      "key": "referral_vs_sold",
      "title": "روند ارجاع و فروش املاک",
      "subtitle": "آمار هفتگی عملیات",
      "series": [
        { "key": "referred", "label": "ارجاع‌شده", "color_hint": "purple" },
        { "key": "sold", "label": "فروخته‌شده", "color_hint": "green" }
      ]
    }
  ]
}

خطاهای رایج

• 401 — توکن نیست / منقضی شده
• 403 — کاربر سیستم‌منیجر نیست
• 400 — metric یا range نامعتبر

مجوزهای RBAC

• reports.view — مشاهده گزارش‌ها / catalog
• reports.manage — مدیریت گزارش‌های آینده

بعد از اضافه شدن: python manage.py sync_rbac

چطور آمار جدید اضافه کنیم؟

1. در Reports/services/dashboard.py یک تابع سری جدید بنویس.
2. آن را به TREND_METRICS و SERIES_BUILDERS اضافه کن.
3. فرانت بدون تغییر بک‌اند خاص، از available_metrics / catalog متریک جدید را می‌بیند.
4. برای گزارش‌های ذخیره‌شونده بعدی می‌توان مدل در Reports/models.py تعریف کرد.

اندپوینت‌های جدید (PART G)

• GET /reports/dashboard/agent-type-breakdown/?range=week — قیف سه رنج
• GET /reports/dashboard/visits-by-agent/?range=week&agent_id= — بازدید به تفکیک مشاور
• GET /reports/dashboard/agent/me/ — داشبورد خود مشاور
• پارامترهای agent_type و agent_id روی weekly-trend و kpis

متریک‌های تب جدید: sale_outcomes, rent_outcomes, not_closed_at_agency, in_progress_vs_closed, visits_trend, workline_funnel

جزئیات پارت‌ها: changelog-parts

نقشه سریع

GET /reports/dashboard/kpis/
GET /reports/dashboard/weekly-trend/?metric=sale_outcomes&range=week&agent_type=Apartment
GET /reports/dashboard/agent-type-breakdown/?range=week
GET /reports/dashboard/visits-by-agent/?range=week
GET /reports/dashboard/agent/me/
GET /reports/catalog/

• کد: Reports/
• سرویس آمار: Reports/services/dashboard.py
• Base URL: /reports/