feat: Add duplicate detection, workflow configurations, and enterprise constraints for CRM entities, alongside model and UI updates.

This commit is contained in:
Ashwin 2025-12-08 08:48:25 +05:30
parent ecc4a539d8
commit bae430856b
21 changed files with 1204 additions and 20 deletions

View file

@ -0,0 +1,121 @@
# Generated by Django 5.2.8 on 2025-12-08 03:05
import django.core.validators
import django.db.models.functions.text
from django.conf import settings
from django.db import migrations, models
from django.db.models import Count
from django.db.models.functions import Lower
def cleanup_duplicate_account_names(apps, schema_editor):
"""
Find duplicate account names (case-insensitive) within each org
and append a numeric suffix to make them unique.
"""
Account = apps.get_model('accounts', 'Account')
# Find duplicates: group by lower(name) + org, having count > 1
duplicates = (
Account.objects
.annotate(name_lower=Lower('name'))
.values('name_lower', 'org_id')
.annotate(count=Count('id'))
.filter(count__gt=1)
)
for dup in duplicates:
# Get all accounts with this name in this org, ordered by created_at
accounts = list(
Account.objects
.filter(org_id=dup['org_id'])
.annotate(name_lower=Lower('name'))
.filter(name_lower=dup['name_lower'])
.order_by('created_at')
)
# Keep the first one (oldest), rename the rest
for i, account in enumerate(accounts[1:], start=2):
original_name = account.name
new_name = f"{account.name} ({i})"
# Ensure the new name is also unique
counter = i
while Account.objects.filter(org_id=account.org_id, name__iexact=new_name).exists():
counter += 1
new_name = f"{original_name} ({counter})"
account.name = new_name
account.save(update_fields=['name'])
print(f" Renamed duplicate account: '{original_name}' -> '{new_name}'")
def cleanup_negative_revenue(apps, schema_editor):
"""Set negative annual_revenue values to NULL."""
Account = apps.get_model('accounts', 'Account')
updated = Account.objects.filter(annual_revenue__lt=0).update(annual_revenue=None)
if updated:
print(f" Set {updated} negative annual_revenue values to NULL")
def reverse_noop(apps, schema_editor):
"""No reverse operation - data cleanup cannot be undone."""
pass
class Migration(migrations.Migration):
dependencies = [
("accounts", "0005_add_currency_fields"),
("common", "0008_enable_rls_product_invoice_line_item"),
("contacts", "0009_alter_contact_created_by_alter_contact_updated_by"),
migrations.swappable_dependency(settings.AUTH_USER_MODEL),
]
operations = [
# Run data cleanup BEFORE adding constraints
migrations.RunPython(
cleanup_duplicate_account_names,
reverse_noop,
elidable=True,
),
migrations.RunPython(
cleanup_negative_revenue,
reverse_noop,
elidable=True,
),
# Now safe to add constraints
migrations.AlterField(
model_name="account",
name="phone",
field=models.CharField(
blank=True,
max_length=25,
null=True,
validators=[
django.core.validators.RegexValidator(
message="Enter a valid phone number (7-25 characters, digits and separators only)",
regex="^[\\d\\s\\-\\(\\)\\+\\.]{7,25}$",
)
],
verbose_name="Phone",
),
),
migrations.AddConstraint(
model_name="account",
constraint=models.UniqueConstraint(
django.db.models.functions.text.Lower("name"),
models.F("org"),
name="unique_account_name_per_org",
),
),
migrations.AddConstraint(
model_name="account",
constraint=models.CheckConstraint(
condition=models.Q(
("annual_revenue__gte", 0),
("annual_revenue__isnull", True),
_connector="OR",
),
name="account_revenue_non_negative",
),
),
]

View file

@ -1,11 +1,14 @@
from django.core.exceptions import ValidationError
from django.db import models
from django.db.models import Q
from django.db.models.functions import Lower
from django.utils.translation import gettext_lazy as _
from django.utils.translation import pgettext_lazy
from common.base import AssignableMixin, BaseModel
from common.models import Org, Profile, Tags, Teams
from common.utils import COUNTRIES, CURRENCY_CODES, INDCHOICES
from common.validators import flexible_phone_validator
from contacts.models import Contact
@ -23,7 +26,13 @@ class Account(AssignableMixin, BaseModel):
# Core Account Information
name = models.CharField(_("Account Name"), max_length=255)
email = models.EmailField(_("Email"), blank=True, null=True)
phone = models.CharField(_("Phone"), max_length=20, null=True, blank=True)
phone = models.CharField(
_("Phone"),
max_length=25,
null=True,
blank=True,
validators=[flexible_phone_validator],
)
website = models.URLField(_("Website"), blank=True, null=True)
# Business Information
@ -80,6 +89,19 @@ class Account(AssignableMixin, BaseModel):
models.Index(fields=["industry"]),
models.Index(fields=["org", "-created_at"]),
]
constraints = [
# Case-insensitive unique account name per organization
models.UniqueConstraint(
Lower("name"),
"org",
name="unique_account_name_per_org",
),
# Annual revenue must be non-negative
models.CheckConstraint(
check=Q(annual_revenue__gte=0) | Q(annual_revenue__isnull=True),
name="account_revenue_non_negative",
),
]
def __str__(self):
return f"{self.name}"

View file

@ -0,0 +1,45 @@
# Generated by Django 5.2.8 on 2025-12-08 03:05
from django.db import migrations, models
class Migration(migrations.Migration):
dependencies = [
("cases", "0007_alter_case_created_by_alter_case_updated_by_and_more"),
]
operations = [
migrations.AddField(
model_name="case",
name="first_response_at",
field=models.DateTimeField(
blank=True, null=True, verbose_name="First Response At"
),
),
migrations.AddField(
model_name="case",
name="resolved_at",
field=models.DateTimeField(
blank=True, null=True, verbose_name="Resolved At"
),
),
migrations.AddField(
model_name="case",
name="sla_first_response_hours",
field=models.PositiveIntegerField(
default=4,
help_text="Target hours for first response",
verbose_name="First Response SLA (hours)",
),
),
migrations.AddField(
model_name="case",
name="sla_resolution_hours",
field=models.PositiveIntegerField(
default=24,
help_text="Target hours for resolution",
verbose_name="Resolution SLA (hours)",
),
),
]

View file

@ -1,4 +1,8 @@
from datetime import timedelta
from django.core.exceptions import ValidationError
from django.db import models
from django.utils import timezone
from django.utils.translation import gettext_lazy as _
from django.utils.translation import pgettext_lazy
@ -37,6 +41,22 @@ class Case(AssignableMixin, BaseModel):
tags = models.ManyToManyField(Tags, related_name="case_tags", blank=True)
org = models.ForeignKey(Org, on_delete=models.CASCADE, related_name="cases")
# SLA Tracking Fields
first_response_at = models.DateTimeField(
_("First Response At"), blank=True, null=True
)
resolved_at = models.DateTimeField(_("Resolved At"), blank=True, null=True)
sla_first_response_hours = models.PositiveIntegerField(
_("First Response SLA (hours)"),
default=4,
help_text="Target hours for first response",
)
sla_resolution_hours = models.PositiveIntegerField(
_("Resolution SLA (hours)"),
default=24,
help_text="Target hours for resolution",
)
class Meta:
verbose_name = "Case"
verbose_name_plural = "Cases"
@ -51,6 +71,69 @@ class Case(AssignableMixin, BaseModel):
def __str__(self):
return f"{self.name}"
def clean(self):
"""Validate case data."""
super().clean()
errors = {}
# Closed date required when status is Closed
if self.status == "Closed" and not self.closed_on:
errors["closed_on"] = _("Closed date is required when closing a case")
if errors:
raise ValidationError(errors)
def save(self, *args, **kwargs):
"""Auto-set SLA values based on priority for new cases."""
from .workflow import DEFAULT_FIRST_RESPONSE_SLA, DEFAULT_RESOLUTION_SLA
# Set default SLA based on priority for new cases
if not self.pk:
if self.sla_first_response_hours == 4: # Default value
self.sla_first_response_hours = DEFAULT_FIRST_RESPONSE_SLA.get(
self.priority, 4
)
if self.sla_resolution_hours == 24: # Default value
self.sla_resolution_hours = DEFAULT_RESOLUTION_SLA.get(
self.priority, 24
)
super().save(*args, **kwargs)
@property
def is_sla_first_response_breached(self) -> bool:
"""Check if first response SLA has been breached."""
if self.first_response_at:
return False
if not self.created_at:
return False
deadline = self.created_at + timedelta(hours=self.sla_first_response_hours)
return timezone.now() > deadline
@property
def is_sla_resolution_breached(self) -> bool:
"""Check if resolution SLA has been breached."""
if self.resolved_at:
return False
if not self.created_at:
return False
deadline = self.created_at + timedelta(hours=self.sla_resolution_hours)
return timezone.now() > deadline
@property
def first_response_sla_deadline(self):
"""Return the deadline for first response."""
if self.created_at:
return self.created_at + timedelta(hours=self.sla_first_response_hours)
return None
@property
def resolution_sla_deadline(self):
"""Return the deadline for resolution."""
if self.created_at:
return self.created_at + timedelta(hours=self.sla_resolution_hours)
return None
class Solution(BaseModel):
"""

26
backend/cases/workflow.py Normal file
View file

@ -0,0 +1,26 @@
"""
Case workflow configuration.
Defines SLA defaults by priority.
"""
# Terminal statuses
TERMINAL_STATUSES = {"Closed", "Rejected", "Duplicate"}
# Statuses that require closed_on date
CLOSED_DATE_REQUIRED_STATUSES = {"Closed"}
# Default SLA by priority (in hours)
DEFAULT_FIRST_RESPONSE_SLA = {
"Low": 24,
"Normal": 8,
"High": 4,
"Urgent": 1,
}
DEFAULT_RESOLUTION_SLA = {
"Low": 72,
"Normal": 48,
"High": 24,
"Urgent": 4,
}

View file

@ -0,0 +1,36 @@
"""
Conditional field requirements configuration.
Reference configuration for which fields are typically required
based on stage, status, or type. These are NOT enforced at the model
level but can be used by serializers or frontend for validation hints.
"""
# Opportunity: Suggested required fields by stage
OPPORTUNITY_REQUIRED_BY_STAGE = {
"PROSPECTING": ["name"],
"QUALIFICATION": ["name"],
"PROPOSAL": ["name", "amount"],
"NEGOTIATION": ["name", "amount"],
"CLOSED_WON": ["name", "amount", "closed_on"],
"CLOSED_LOST": ["name", "closed_on"],
}
# Lead: Suggested required fields by status
LEAD_REQUIRED_BY_STATUS = {
"assigned": [],
"in process": [],
"converted": ["email"], # Only email is enforced
"recycled": [],
"closed": [],
}
# Case: Suggested required fields by status
CASE_REQUIRED_BY_STATUS = {
"New": ["name", "status", "priority"],
"Assigned": ["name", "status", "priority"],
"Pending": ["name", "status", "priority"],
"Closed": ["name", "status", "priority", "closed_on"],
"Rejected": ["name", "status", "priority"],
"Duplicate": ["name", "status", "priority"],
}

View file

@ -0,0 +1,245 @@
"""
Duplicate detection service for CRM entities.
Provides methods to find potential duplicate records based on
email, phone, name, and other identifying fields.
"""
import re
from typing import TYPE_CHECKING
from django.db.models import Q
if TYPE_CHECKING:
from accounts.models import Account
from contacts.models import Contact
from leads.models import Lead
class DuplicateDetector:
"""Service for detecting potential duplicate records."""
@staticmethod
def normalize_phone(phone: str) -> str:
"""
Normalize a phone number by removing all non-digit characters.
Returns the last 10 digits for comparison purposes.
"""
if not phone:
return ""
digits_only = re.sub(r"[^\d]", "", phone)
return digits_only[-10:] if len(digits_only) >= 10 else digits_only
@staticmethod
def normalize_domain(website: str) -> str:
"""Extract and normalize domain from a website URL."""
if not website:
return ""
domain = website.lower()
domain = domain.replace("https://", "").replace("http://", "")
domain = domain.replace("www.", "")
domain = domain.split("/")[0] # Remove path
return domain
@classmethod
def find_duplicate_contacts(
cls,
org,
email: str | None = None,
phone: str | None = None,
first_name: str | None = None,
last_name: str | None = None,
exclude_id=None,
) -> list["Contact"]:
"""
Find potential duplicate contacts based on email, phone, or name.
Args:
org: The organization to search within
email: Email address to match
phone: Phone number to match (normalized)
first_name: First name for fuzzy matching
last_name: Last name for fuzzy matching
exclude_id: ID to exclude from results (for updates)
Returns:
List of potential duplicate Contact objects
"""
from contacts.models import Contact
duplicates = []
base_qs = Contact.objects.filter(org=org, is_active=True)
if exclude_id:
base_qs = base_qs.exclude(pk=exclude_id)
# Exact email match (case-insensitive)
if email:
email_matches = base_qs.filter(email__iexact=email)
duplicates.extend(list(email_matches))
# Normalized phone match
if phone:
normalized = cls.normalize_phone(phone)
if len(normalized) >= 7:
# Get all contacts with phones and filter in Python
phone_candidates = base_qs.exclude(phone__isnull=True).exclude(phone="")
for contact in phone_candidates:
if cls.normalize_phone(contact.phone) == normalized:
if contact not in duplicates:
duplicates.append(contact)
# Name match (first + last name combination)
if first_name and last_name:
name_matches = base_qs.filter(
first_name__iexact=first_name, last_name__iexact=last_name
)
for contact in name_matches:
if contact not in duplicates:
duplicates.append(contact)
return duplicates
@classmethod
def find_duplicate_leads(
cls,
org,
email: str | None = None,
phone: str | None = None,
first_name: str | None = None,
last_name: str | None = None,
company_name: str | None = None,
exclude_id=None,
) -> list["Lead"]:
"""
Find potential duplicate leads based on email, phone, name, or company.
Args:
org: The organization to search within
email: Email address to match
phone: Phone number to match (normalized)
first_name: First name for fuzzy matching
last_name: Last name for fuzzy matching
company_name: Company name for fuzzy matching
exclude_id: ID to exclude from results (for updates)
Returns:
List of potential duplicate Lead objects
"""
from leads.models import Lead
duplicates = []
base_qs = Lead.objects.filter(org=org, is_active=True)
if exclude_id:
base_qs = base_qs.exclude(pk=exclude_id)
# Exact email match (case-insensitive)
if email:
email_matches = base_qs.filter(email__iexact=email)
duplicates.extend(list(email_matches))
# Normalized phone match
if phone:
normalized = cls.normalize_phone(phone)
if len(normalized) >= 7:
phone_candidates = base_qs.exclude(phone__isnull=True).exclude(phone="")
for lead in phone_candidates:
if cls.normalize_phone(lead.phone) == normalized:
if lead not in duplicates:
duplicates.append(lead)
# Name match
if first_name and last_name:
name_matches = base_qs.filter(
first_name__iexact=first_name, last_name__iexact=last_name
)
for lead in name_matches:
if lead not in duplicates:
duplicates.append(lead)
# Company name match (fuzzy - contains)
if company_name and len(company_name) >= 3:
company_matches = base_qs.filter(company_name__icontains=company_name)
for lead in company_matches:
if lead not in duplicates:
duplicates.append(lead)
return duplicates
@classmethod
def find_duplicate_accounts(
cls,
org,
name: str | None = None,
email: str | None = None,
website: str | None = None,
phone: str | None = None,
exclude_id=None,
) -> list["Account"]:
"""
Find potential duplicate accounts based on name, email, website, or phone.
Args:
org: The organization to search within
name: Account name to match (fuzzy)
email: Email address to match
website: Website URL to match (domain normalized)
phone: Phone number to match (normalized)
exclude_id: ID to exclude from results (for updates)
Returns:
List of potential duplicate Account objects
"""
from accounts.models import Account
duplicates = []
base_qs = Account.objects.filter(org=org, is_active=True)
if exclude_id:
base_qs = base_qs.exclude(pk=exclude_id)
# Exact name match (case-insensitive)
if name:
name_matches = base_qs.filter(name__iexact=name)
duplicates.extend(list(name_matches))
# Also check for partial matches on first word (for company variations)
first_word = name.split()[0] if name else ""
if len(first_word) >= 3:
partial_matches = base_qs.filter(
name__istartswith=first_word
).exclude(name__iexact=name)
for account in partial_matches:
if account not in duplicates:
duplicates.append(account)
# Exact email match
if email:
email_matches = base_qs.filter(email__iexact=email)
for account in email_matches:
if account not in duplicates:
duplicates.append(account)
# Website domain match
if website:
domain = cls.normalize_domain(website)
if domain:
website_candidates = base_qs.exclude(website__isnull=True).exclude(
website=""
)
for account in website_candidates:
if cls.normalize_domain(account.website) == domain:
if account not in duplicates:
duplicates.append(account)
# Normalized phone match
if phone:
normalized = cls.normalize_phone(phone)
if len(normalized) >= 7:
phone_candidates = base_qs.exclude(phone__isnull=True).exclude(phone="")
for account in phone_candidates:
if cls.normalize_phone(account.phone) == normalized:
if account not in duplicates:
duplicates.append(account)
return duplicates

View file

@ -515,9 +515,32 @@ class Command(BaseCommand):
sources = [c[0] for c in LEAD_SOURCE]
ratings = ["HOT", "WARM", "COLD"]
# Lead title templates for realistic data
lead_title_templates = [
"Enterprise Deal",
"Website Inquiry",
"Demo Request",
"Partnership Opportunity",
"Inbound Lead",
"Referral Opportunity",
"Trade Show Contact",
"Product Inquiry",
"Upgrade Opportunity",
"Expansion Deal",
"New Business Inquiry",
"Consultation Request",
]
for _ in range(count):
status = self._weighted_choice(self.LEAD_STATUS_WEIGHTS)
# Generate a title - either from templates or using faker
if random.random() > 0.3:
title = random.choice(lead_title_templates)
else:
title = f"{self.fake.catch_phrase()} Opportunity"
lead = Lead.objects.create(
title=title,
first_name=self.fake.first_name(),
last_name=self.fake.last_name(),
email=self.fake.company_email(),

View file

@ -0,0 +1,35 @@
"""
Common validators for CRM models.
"""
import re
from django.core.validators import RegexValidator
from django.utils.translation import gettext_lazy as _
# E.164 format: +[country code][number] (max 15 digits total)
# Examples: +12025551234, +442071234567
e164_phone_validator = RegexValidator(
regex=r"^\+[1-9]\d{1,14}$",
message=_("Phone must be in E.164 format (e.g., +12025551234)"),
)
# Flexible phone format allowing common separators
# Allows: digits, spaces, dashes, parentheses, plus sign
# Examples: +1 (202) 555-1234, 202-555-1234, +44 20 7123 4567
flexible_phone_validator = RegexValidator(
regex=r"^[\d\s\-\(\)\+\.]{7,25}$",
message=_("Enter a valid phone number (7-25 characters, digits and separators only)"),
)
def normalize_phone(phone: str) -> str:
"""
Normalize a phone number by removing all non-digit characters.
Returns the last 10 digits for comparison purposes.
"""
if not phone:
return ""
digits_only = re.sub(r"[^\d]", "", phone)
# Return last 10 digits for normalized comparison
return digits_only[-10:] if len(digits_only) >= 10 else digits_only

View file

@ -0,0 +1,98 @@
# Generated by Django 5.2.8 on 2025-12-08 03:05
import django.core.validators
import django.db.models.functions.text
from django.conf import settings
from django.db import migrations, models
from django.db.models import Count
from django.db.models.functions import Lower
def cleanup_duplicate_contact_emails(apps, schema_editor):
"""
Find duplicate contact emails (case-insensitive) within each org
and clear email on duplicates (keep oldest).
"""
Contact = apps.get_model('contacts', 'Contact')
# Find duplicates: group by lower(email) + org, having count > 1
duplicates = (
Contact.objects
.exclude(email__isnull=True)
.exclude(email='')
.annotate(email_lower=Lower('email'))
.values('email_lower', 'org_id')
.annotate(count=Count('id'))
.filter(count__gt=1)
)
for dup in duplicates:
# Get all contacts with this email in this org, ordered by created_at
contacts = list(
Contact.objects
.filter(org_id=dup['org_id'])
.exclude(email__isnull=True)
.exclude(email='')
.annotate(email_lower=Lower('email'))
.filter(email_lower=dup['email_lower'])
.order_by('created_at')
)
# Keep the first one (oldest), clear email on the rest
for contact in contacts[1:]:
old_email = contact.email
contact.email = None
contact.save(update_fields=['email'])
print(f" Cleared duplicate email on contact {contact.id}: '{old_email}'")
def reverse_noop(apps, schema_editor):
"""No reverse operation - data cleanup cannot be undone."""
pass
class Migration(migrations.Migration):
dependencies = [
("accounts", "0006_add_enterprise_constraints"),
("common", "0008_enable_rls_product_invoice_line_item"),
("contacts", "0009_alter_contact_created_by_alter_contact_updated_by"),
migrations.swappable_dependency(settings.AUTH_USER_MODEL),
]
operations = [
# Run data cleanup BEFORE adding constraints
migrations.RunPython(
cleanup_duplicate_contact_emails,
reverse_noop,
elidable=True,
),
# Now safe to add constraints
migrations.AlterField(
model_name="contact",
name="phone",
field=models.CharField(
blank=True,
max_length=25,
null=True,
validators=[
django.core.validators.RegexValidator(
message="Enter a valid phone number (7-25 characters, digits and separators only)",
regex="^[\\d\\s\\-\\(\\)\\+\\.]{7,25}$",
)
],
verbose_name="Phone",
),
),
migrations.AddConstraint(
model_name="contact",
constraint=models.UniqueConstraint(
django.db.models.functions.text.Lower("email"),
models.F("org"),
condition=models.Q(
("email__isnull", False), models.Q(("email", ""), _negated=True)
),
name="unique_contact_email_per_org",
),
),
]

View file

@ -1,9 +1,12 @@
from django.db import models
from django.db.models import Q
from django.db.models.functions import Lower
from django.utils.translation import gettext_lazy as _
from common.base import AssignableMixin, BaseModel
from common.models import Org, Profile, Tags, Teams
from common.utils import COUNTRIES
from common.validators import flexible_phone_validator
class Contact(AssignableMixin, BaseModel):
@ -16,7 +19,13 @@ class Contact(AssignableMixin, BaseModel):
first_name = models.CharField(_("First name"), max_length=255)
last_name = models.CharField(_("Last name"), max_length=255)
email = models.EmailField(_("Email"), blank=True, null=True)
phone = models.CharField(_("Phone"), max_length=20, null=True, blank=True)
phone = models.CharField(
_("Phone"),
max_length=25,
null=True,
blank=True,
validators=[flexible_phone_validator],
)
# Professional Information
organization = models.CharField(_("Company"), max_length=255, blank=True, null=True)
@ -70,6 +79,15 @@ class Contact(AssignableMixin, BaseModel):
indexes = [
models.Index(fields=["org", "-created_at"]),
]
constraints = [
# Case-insensitive unique email per organization (when email is not null)
models.UniqueConstraint(
Lower("email"),
"org",
name="unique_contact_email_per_org",
condition=Q(email__isnull=False) & ~Q(email=""),
),
]
def __str__(self):
return self.first_name

View file

@ -0,0 +1,172 @@
# Generated by Django 5.2.8 on 2025-12-08 03:05
import django.core.validators
import django.db.models.functions.text
from django.conf import settings
from django.db import migrations, models
from django.db.models import Count
from django.db.models.functions import Lower, Length
def cleanup_duplicate_lead_emails(apps, schema_editor):
"""
Find duplicate lead emails (case-insensitive) within each org
and clear email on duplicates (keep oldest).
"""
Lead = apps.get_model('leads', 'Lead')
# Find duplicates: group by lower(email) + org, having count > 1
duplicates = (
Lead.objects
.exclude(email__isnull=True)
.exclude(email='')
.annotate(email_lower=Lower('email'))
.values('email_lower', 'org_id')
.annotate(count=Count('id'))
.filter(count__gt=1)
)
for dup in duplicates:
# Get all leads with this email in this org, ordered by created_at
leads = list(
Lead.objects
.filter(org_id=dup['org_id'])
.exclude(email__isnull=True)
.exclude(email='')
.annotate(email_lower=Lower('email'))
.filter(email_lower=dup['email_lower'])
.order_by('created_at')
)
# Keep the first one (oldest), clear email on the rest
for lead in leads[1:]:
old_email = lead.email
lead.email = None
lead.save(update_fields=['email'])
print(f" Cleared duplicate email on lead {lead.id}: '{old_email}'")
def cleanup_long_phone_numbers(apps, schema_editor):
"""
Truncate phone numbers longer than 25 characters.
Phone field max_length is being reduced from 50 to 25.
"""
Lead = apps.get_model('leads', 'Lead')
long_phones = Lead.objects.annotate(
phone_len=Length('phone')
).filter(phone_len__gt=25)
for lead in long_phones:
old_phone = lead.phone
lead.phone = lead.phone[:25] if lead.phone else None
lead.save(update_fields=['phone'])
print(f" Truncated long phone on lead {lead.id}: '{old_phone}' -> '{lead.phone}'")
def cleanup_invalid_probability(apps, schema_editor):
"""Fix probability values outside 0-100 range."""
Lead = apps.get_model('leads', 'Lead')
# Set negative probabilities to 0
updated = Lead.objects.filter(probability__lt=0).update(probability=0)
if updated:
print(f" Set {updated} negative probability values to 0")
# Set probabilities over 100 to 100
updated = Lead.objects.filter(probability__gt=100).update(probability=100)
if updated:
print(f" Set {updated} probability values over 100 to 100")
def cleanup_negative_amounts(apps, schema_editor):
"""Set negative opportunity_amount values to NULL."""
Lead = apps.get_model('leads', 'Lead')
updated = Lead.objects.filter(opportunity_amount__lt=0).update(opportunity_amount=None)
if updated:
print(f" Set {updated} negative opportunity_amount values to NULL")
def reverse_noop(apps, schema_editor):
"""No reverse operation - data cleanup cannot be undone."""
pass
class Migration(migrations.Migration):
dependencies = [
("common", "0008_enable_rls_product_invoice_line_item"),
("contacts", "0010_add_enterprise_constraints"),
("leads", "0010_add_currency_fields"),
migrations.swappable_dependency(settings.AUTH_USER_MODEL),
]
operations = [
# Run data cleanup BEFORE adding constraints
migrations.RunPython(
cleanup_duplicate_lead_emails,
reverse_noop,
elidable=True,
),
migrations.RunPython(
cleanup_long_phone_numbers,
reverse_noop,
elidable=True,
),
migrations.RunPython(
cleanup_invalid_probability,
reverse_noop,
elidable=True,
),
migrations.RunPython(
cleanup_negative_amounts,
reverse_noop,
elidable=True,
),
# Now safe to add constraints
migrations.AlterField(
model_name="lead",
name="phone",
field=models.CharField(
blank=True,
max_length=25,
null=True,
validators=[
django.core.validators.RegexValidator(
message="Enter a valid phone number (7-25 characters, digits and separators only)",
regex="^[\\d\\s\\-\\(\\)\\+\\.]{7,25}$",
)
],
verbose_name="Phone",
),
),
migrations.AddConstraint(
model_name="lead",
constraint=models.UniqueConstraint(
django.db.models.functions.text.Lower("email"),
models.F("org"),
condition=models.Q(
("email__isnull", False), models.Q(("email", ""), _negated=True)
),
name="unique_lead_email_per_org",
),
),
migrations.AddConstraint(
model_name="lead",
constraint=models.CheckConstraint(
condition=models.Q(("probability__gte", 0), ("probability__lte", 100)),
name="lead_probability_range",
),
),
migrations.AddConstraint(
model_name="lead",
constraint=models.CheckConstraint(
condition=models.Q(
("opportunity_amount__gte", 0),
("opportunity_amount__isnull", True),
_connector="OR",
),
name="lead_amount_non_negative",
),
),
]

View file

@ -1,4 +1,8 @@
from django.core.exceptions import ValidationError
from django.db import models
from django.db.models import Q
from django.db.models.functions import Lower
from django.utils import timezone
from django.utils.translation import gettext_lazy as _
from common.base import AssignableMixin, BaseModel
@ -10,6 +14,7 @@ from common.utils import (
LEAD_SOURCE,
LEAD_STATUS,
)
from common.validators import flexible_phone_validator
from contacts.models import Contact
@ -38,7 +43,13 @@ class Lead(AssignableMixin, BaseModel):
first_name = models.CharField(_("First name"), null=True, max_length=255)
last_name = models.CharField(_("Last name"), null=True, max_length=255)
email = models.EmailField(null=True, blank=True)
phone = models.CharField(_("Phone"), max_length=50, null=True, blank=True)
phone = models.CharField(
_("Phone"),
max_length=25,
null=True,
blank=True,
validators=[flexible_phone_validator],
)
job_title = models.CharField(
_("Job Title"), max_length=255, blank=True, null=True,
help_text="Person's job title (e.g., 'VP of Sales', 'CTO')"
@ -113,8 +124,69 @@ class Lead(AssignableMixin, BaseModel):
models.Index(fields=["source"]),
models.Index(fields=["org", "-created_at"]),
]
constraints = [
# Case-insensitive unique email per organization (when email is not null)
models.UniqueConstraint(
Lower("email"),
"org",
name="unique_lead_email_per_org",
condition=Q(email__isnull=False) & ~Q(email=""),
),
# Probability must be 0-100
models.CheckConstraint(
check=Q(probability__gte=0) & Q(probability__lte=100),
name="lead_probability_range",
),
# Opportunity amount must be non-negative
models.CheckConstraint(
check=Q(opportunity_amount__gte=0) | Q(opportunity_amount__isnull=True),
name="lead_amount_non_negative",
),
]
def __str__(self):
name_parts = [self.salutation, self.first_name, self.last_name]
return " ".join(part for part in name_parts if part) or f"Lead {self.id}"
def clean(self):
"""Validate lead data."""
super().clean()
errors = {}
# Email required for conversion (need contact info to create Contact)
if self.status == "converted" and not self.email:
errors["email"] = _("Email is required to convert lead")
if errors:
raise ValidationError(errors)
@property
def days_since_last_contact(self) -> int:
"""Return the number of days since last contact or creation."""
if self.last_contacted:
return (timezone.now().date() - self.last_contacted).days
if self.created_at:
return (timezone.now().date() - self.created_at.date()).days
return 0
@property
def is_stale(self) -> bool:
"""Check if lead is stale (>30 days without contact and not closed/converted)."""
if self.status in ["converted", "closed"]:
return False
return self.days_since_last_contact > 30
@property
def days_until_follow_up(self) -> int | None:
"""Return the number of days until next follow-up (negative if overdue)."""
if not self.next_follow_up:
return None
return (self.next_follow_up - timezone.now().date()).days
@property
def is_follow_up_overdue(self) -> bool:
"""Check if follow-up date has passed."""
if not self.next_follow_up:
return False
return timezone.now().date() > self.next_follow_up

11
backend/leads/workflow.py Normal file
View file

@ -0,0 +1,11 @@
"""
Lead workflow configuration.
Reference configuration for lead lifecycle management.
"""
# Statuses that represent terminal states
TERMINAL_STATUSES = {"converted", "closed"}
# Status that requires email
EMAIL_REQUIRED_STATUSES = {"converted"}

View file

@ -0,0 +1,74 @@
# Generated by Django 5.2.8 on 2025-12-08 03:05
from django.conf import settings
from django.db import migrations, models
def cleanup_invalid_probability(apps, schema_editor):
"""Fix probability values outside 0-100 range."""
Opportunity = apps.get_model('opportunity', 'Opportunity')
# Set negative probabilities to 0
updated = Opportunity.objects.filter(probability__lt=0).update(probability=0)
if updated:
print(f" Set {updated} negative probability values to 0")
# Set probabilities over 100 to 100
updated = Opportunity.objects.filter(probability__gt=100).update(probability=100)
if updated:
print(f" Set {updated} probability values over 100 to 100")
def cleanup_negative_amounts(apps, schema_editor):
"""Set negative amount values to NULL."""
Opportunity = apps.get_model('opportunity', 'Opportunity')
updated = Opportunity.objects.filter(amount__lt=0).update(amount=None)
if updated:
print(f" Set {updated} negative amount values to NULL")
def reverse_noop(apps, schema_editor):
"""No reverse operation - data cleanup cannot be undone."""
pass
class Migration(migrations.Migration):
dependencies = [
("accounts", "0006_add_enterprise_constraints"),
("common", "0008_enable_rls_product_invoice_line_item"),
("contacts", "0010_add_enterprise_constraints"),
("opportunity", "0004_alter_opportunity_created_by_and_more"),
migrations.swappable_dependency(settings.AUTH_USER_MODEL),
]
operations = [
# Run data cleanup BEFORE adding constraints
migrations.RunPython(
cleanup_invalid_probability,
reverse_noop,
elidable=True,
),
migrations.RunPython(
cleanup_negative_amounts,
reverse_noop,
elidable=True,
),
# Now safe to add constraints
migrations.AddConstraint(
model_name="opportunity",
constraint=models.CheckConstraint(
condition=models.Q(("probability__gte", 0), ("probability__lte", 100)),
name="opportunity_probability_range",
),
),
migrations.AddConstraint(
model_name="opportunity",
constraint=models.CheckConstraint(
condition=models.Q(
("amount__gte", 0), ("amount__isnull", True), _connector="OR"
),
name="opportunity_amount_non_negative",
),
),
]

View file

@ -1,4 +1,6 @@
from django.core.exceptions import ValidationError
from django.db import models
from django.db.models import Q
from django.utils.timesince import timesince
from django.utils.translation import gettext_lazy as _
from django.utils.translation import pgettext_lazy
@ -88,6 +90,18 @@ class Opportunity(AssignableMixin, BaseModel):
models.Index(fields=["stage"]),
models.Index(fields=["org", "-created_at"]),
]
constraints = [
# Probability must be 0-100
models.CheckConstraint(
check=Q(probability__gte=0) & Q(probability__lte=100),
name="opportunity_probability_range",
),
# Amount must be non-negative
models.CheckConstraint(
check=Q(amount__gte=0) | Q(amount__isnull=True),
name="opportunity_amount_non_negative",
),
]
def __str__(self):
return f"{self.name}"
@ -95,3 +109,31 @@ class Opportunity(AssignableMixin, BaseModel):
@property
def created_on_arrow(self):
return timesince(self.created_at) + " ago"
def clean(self):
"""Validate opportunity data."""
super().clean()
errors = {}
# Closed date required for closed stages
if self.stage in ["CLOSED_WON", "CLOSED_LOST"] and not self.closed_on:
errors["closed_on"] = _(
"Close date is required when stage is Closed Won/Lost"
)
# Amount required for closed won
if self.stage == "CLOSED_WON" and not self.amount:
errors["amount"] = _("Amount is required for Closed Won opportunities")
if errors:
raise ValidationError(errors)
def save(self, *args, **kwargs):
"""Auto-set probability based on stage if not manually set."""
from .workflow import STAGE_PROBABILITIES
# Auto-set probability based on stage (only if probability is default/0)
if self.probability == 0 or self.probability is None:
self.probability = STAGE_PROBABILITIES.get(self.stage, 0)
super().save(*args, **kwargs)

View file

@ -0,0 +1,21 @@
"""
Opportunity workflow configuration.
Defines auto-probability mapping for the sales pipeline.
"""
# Default probability by stage (auto-set if probability is 0/None)
STAGE_PROBABILITIES = {
"PROSPECTING": 10,
"QUALIFICATION": 25,
"PROPOSAL": 50,
"NEGOTIATION": 75,
"CLOSED_WON": 100,
"CLOSED_LOST": 0,
}
# Stages that require closed_on date
CLOSED_STAGES = {"CLOSED_WON", "CLOSED_LOST"}
# Stages that require amount
AMOUNT_REQUIRED_STAGES = {"CLOSED_WON"}

View file

@ -0,0 +1,21 @@
# Generated by Django 5.2.8 on 2025-12-08 03:05
from django.db import migrations
class Migration(migrations.Migration):
dependencies = [
("tasks", "0007_alter_board_created_by_alter_board_updated_by_and_more"),
]
operations = [
migrations.AlterModelOptions(
name="task",
options={
"ordering": ("-created_at",),
"verbose_name": "Task",
"verbose_name_plural": "Tasks",
},
),
]

View file

@ -1,5 +1,6 @@
from django.core.exceptions import ValidationError
from django.db import models
from django.utils import timezone
from django.utils.translation import gettext_lazy as _
from accounts.models import Account
@ -251,7 +252,7 @@ class Task(AssignableMixin, BaseModel):
verbose_name = "Task"
verbose_name_plural = "Tasks"
db_table = "task"
ordering = ("-due_date",)
ordering = ("-created_at",)
indexes = [
models.Index(fields=["status"]),
models.Index(fields=["due_date"]),
@ -282,3 +283,19 @@ class Task(AssignableMixin, BaseModel):
def save(self, *args, **kwargs):
self.full_clean()
super().save(*args, **kwargs)
@property
def is_overdue(self) -> bool:
"""Check if task is overdue (past due date and not completed)."""
if self.status == "Completed":
return False
if self.due_date:
return timezone.now().date() > self.due_date
return False
@property
def days_until_due(self) -> int | None:
"""Return days until due (negative if overdue). None if no due date."""
if not self.due_date:
return None
return (self.due_date - timezone.now().date()).days

View file

@ -221,7 +221,23 @@
<tbody>
{#each data as row (row.id)}
<tr
class="group transition-all duration-100 ease-out hover:bg-gray-50/30 dark:hover:bg-gray-900/30"
class="group transition-all duration-100 ease-out hover:bg-gray-50/30 dark:hover:bg-gray-900/30 {onRowClick
? 'cursor-pointer'
: ''}"
onclick={(e) => {
if (!onRowClick) return;
// Don't trigger row click if clicking on interactive elements
const target = /** @type {HTMLElement} */ (e.target);
if (
target.closest('button') ||
target.closest('input') ||
target.closest('[data-dropdown-trigger]') ||
target.closest('[role="menu"]')
) {
return;
}
onRowClick(row);
}}
>
{#if onRowClick}
<td class="w-8 px-1 py-3">

View file

@ -185,13 +185,6 @@
width: 'w-32',
format: (value, row) => formatCurrency(value, row?.currency || 'USD', true)
},
{
key: 'numberOfEmployees',
label: 'Employees',
type: 'number',
width: 'w-28',
emptyText: ''
},
{ key: 'phone', label: 'Phone', type: 'text', width: 'w-36', emptyText: '' },
{
key: 'createdAt',
@ -205,14 +198,7 @@
];
// Default visible columns (excludes website; status removed - using tabs instead)
const DEFAULT_VISIBLE_COLUMNS = [
'name',
'industry',
'annualRevenue',
'numberOfEmployees',
'phone',
'createdAt'
];
const DEFAULT_VISIBLE_COLUMNS = ['name', 'industry', 'annualRevenue', 'phone', 'createdAt'];
// Column visibility state - use defaults (excludes website)
let visibleColumns = $state([...DEFAULT_VISIBLE_COLUMNS]);