Перейти до змісту

Module: CRM & Sales Pipeline

Статус: ✅ Реалізовано — повний MVP + Pipeline analytics (2026-04-22)

✅ Реалізовано від попередніх ітерацій: - 9 моделей у crm/: LeadSource, SalesStage, Lead, Contact, Activity, Deal, Quotation + QuotationLine, SalesOrder. - Зв'язки з Essentials: Client (як Account), Item, Currency. - Generic CRUD UI через config crm.ts. - Lead → convert-to-deal action (створює Client + Deal з Lead). - Quotation → convert-to-order action. - Deal → change-stage explicit action з автозаписом у PipelineHistoryJournal.

✅ Реалізовано (Phase D, 2026-04-22): - Auto-history: override DealViewSet.perform_update записує PipelineHistoryJournal при зміні Deal.stage через будь-який PATCH (а не лише через /change-stage/). - Auto-ledger: override ActivityViewSet.perform_create/perform_destroy записує/видаляє ActivityLedger рядок на кожну створену/видалену Activity. - 4 analytics endpoints (crm/views_analytics.py): - GET /api/v1/crm/analytics/funnel/ — снапшот воронки (count + amount + weighted_amount per stage). - GET /api/v1/crm/analytics/stage-duration/ — середній час у стадії (з PipelineHistoryJournal). - GET /api/v1/crm/analytics/win-loss/ — win-rate, loss-rate, конверсія за період. - GET /api/v1/crm/analytics/manager-activity/ — KPI по менеджерах: calls/meetings/emails/tasks/notes + deals_won/lost/open + win_rate_pct. - 2 dashboard-сторінки: - SalesFunnelDashboard — funnel bars + win/loss KPI cards + stage-duration table в одному view. - ManagerActivityDashboard — таблиця менеджерів + KPI cards (total calls/meetings/emails/won deals). - 11 нових backend-тестів (record_stage_change, perform_update auto-history, record_activity, всі 4 analytics endpoints). - Зареєстровано в crm.ts як Analytics → Reports → Sales Funnel / Manager Activity.

Цей модуль відповідає за повний цикл роботи з клієнтом: від першого контакту (Lead) до перетворення його на постійного контрагента та успішне закриття угоди (Deal).

Реалізована аналітика — деталі

Auto-tracking

  • PipelineHistoryJournal заповнюється двома шляхами:
  • Explicit endpoint POST /deals/{id}/change-stage/ з comment.

  • Звичайний PATCH /deals/{id}/ зі зміненим stage — override perform_update зловить різницю стадії й викличе record_stage_change(). Без цього DealViewSet.update обходив запис історії, і реальна історія не корелювала з фактичною eolutionю Deal.stage.

  • ActivityLedger заповнюється perform_create (запис на кожну створену Activity) і чиститься через perform_destroy + remove_activity(). Кожен рядок: (client, deal, assigned_to, activity_type, count=1, date).

Analytics services (crm/services/)

  • record_stage_change(deal, from_stage, to_stage, *, user, comment, when) — створює одну PipelineHistoryJournal запис; пропускає self-transition (from == to).
  • record_activity(activity) — створює ActivityLedger рядок, що дзеркалить ключові поля Activity.
  • remove_activity(activity) — для cleanup при destroy.

Endpoints

URL Опис
/funnel/ Поточний снапшот: {lines: [{stage, deal_count, total_amount, weighted_amount, probability, color, is_won, is_lost}], no_stage, summary}
/stage-duration/ Середні дні в кожній стадії, обчислені з історії. Open-deals рахуються до date_to.
/win-loss/ {won: {count, amount}, lost: {...}, open: {...}, summary: {win_rate_pct, loss_rate_pct, ...}}
/manager-activity/ {managers: [{user_id, full_name, calls, meetings, emails, tasks, notes, total_activities, deals_won, deals_lost, deals_open, amount_won, amount_open, win_rate_pct}]}

Усі endpoints мають фільтр ?date_from=...&date_to=...&assigned_to=... (де доречно).

Frontend components

  • SalesFunnelDashboard — фільтри (period, assignee), KPI cards (Won/Open/Lost/Win-rate), funnel bars з нормалізованим масштабом (excluding won/lost), table «Stage duration». Колір кожного bar повторює SalesStage.color.
  • ManagerActivityDashboard — фільтр period, KPI cards (calls/meetings/emails/won deals total), таблиця рядків per assignee з колонками для кожного типу активності + deal counters + win-rate badge (teal ≥50%, orange ≥20%, red <20%).

Master data, transactions та плановані розширення (далі)

1. Master Data (Мастер-дані)

Сутність Опис Ключові поля
Leads Потенційні клієнти, які ще не пройшли кваліфікацію Name, Source, Contact Info, Status, Assigned To
Accounts Компанії або приватні особи (вже кваліфіковані) ID, Legal Name, Industry, Segment (A/B/C), Tags
Contacts Конкретні люди, пов'язані з Accounts Name, Role, Phone, Email, LinkedIn, Preferences
Sales Stages Етапи воронки продажів (Pipeline) Stage Name, Probability (%), Order, Is_Final (Won/Lost)
Lead Sources Канали залучення (Marketing) Name (Web, Referral, Cold Call, Ads), UTM-params

2. Transaction Data (Транзакційні дані)

  1. Activity (Подія):
  2. Фіксація будь-якої взаємодії: дзвінок, лист, зустріч, коментар.
  3. Має дедлайн та статус виконання.
  4. Opportunity / Deal (Угода):
  5. Основний документ продажу.
  6. Пов’язаний з продуктами (Quotes), сумою, валютою та етапом Pipeline.
  7. Quotation (Комерційна пропозиція):
  8. Версійна пропозиція з переліком товарів/послуг та цінами.
  9. Може бути акцептована клієнтом (перехід у Sales Order).
  10. Sales Order (Замовлення покупця):
  11. Фінальний документ, що резервує товар на складі та ініціює роботу в модулі Inventory & Finance.

3. Journals & Ledgers (Журнали та реєстри)

Для CRM реєстри фокусуються на подіях та змінах станів, а не лише на грошах.

A. Pipeline History Journal (Журнал станів)

Зберігає історію переміщення кожної угоди по етапах. * Dimensions: Opportunity_ID, Stage_ID, User_ID. * Resources: Days_in_Stage, Change_Timestamp.

B. Activity Ledger (Реєстр активностей)

Накопичувальний підсумок зусиль менеджерів. * Dimensions: User_ID, Activity_Type, Account_ID. * Resources: Count, Duration_Minutes.

4. Business Processes (Бізнес-процеси)

  • Lead Qualification: Процес перетворення Lead -> Account + Contact + Opportunity.
  • Automated Follow-ups: Система нагадувань, якщо по угоді немає активності більше X днів.
  • Conversion to Order: Автоматичне створення Sales Order з Quotation із перевіркою залишків (через API до Inventory Core).
  • Lead Scoring (AI-ready): Ранжування лідів на основі ймовірності закриття (тут ми можемо підключити твої знання з Python/AI).

5. Analytics & BI (Аналітика)

  • Sales Funnel (Воронка): Візуалізація конверсії між етапами (Leads -> Opportunities -> Won).
  • Win/Loss Analysis: Аналіз причин програшу угод.
  • Average Cycle Length: Середній час від першого контакту до оплати.
  • Revenue Forecast: Прогноз надходжень на основі ймовірності (Probability %) відкритих угод.
  • Manager Performance: Порівняння KPI менеджерів (кількість дзвінків vs закрита сума).