first

apps/customers/admin.py

@@ -0,0 +1,17 @@
+from django.contrib import admin
+from .models import ContactGroup, CustomerProfile
+
+
+@admin.register(ContactGroup)
+class ContactGroupAdmin(admin.ModelAdmin):
+    list_display = ("name", "unit", "is_active", "updated_at")
+    list_filter = ("unit", "is_active")
+    search_fields = ("name", "description")
+
+
+@admin.register(CustomerProfile)
+class CustomerProfileAdmin(admin.ModelAdmin):
+    list_display = ("user", "stakeholder_type", "organization_name", "first_name", "last_name")
+    list_filter = ("stakeholder_type", "groups")
+    search_fields = ("user__mobile", "organization_name", "first_name", "last_name")
+    filter_horizontal = ("groups",)

apps/customers/apps.py

@@ -0,0 +1,2 @@
+from django.apps import AppConfig
+class CustomersConfig(AppConfig): name = "apps.customers"

apps/customers/migrations/0001_initial.py

@@ -0,0 +1,32 @@
+# Generated by Django 5.1.1 on 2026-09-05 07:03
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='CustomerProfile',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('first_name', models.CharField(blank=True, max_length=100)),
+                ('last_name', models.CharField(blank=True, max_length=100)),
+                ('customer_type', models.CharField(blank=True, choices=[('PERSON', 'شخص'), ('CONSUMER', 'مصرف\u200cکننده نهایی'), ('SHOP', 'فروشگاه'), ('REPRESENTATIVE', 'نمایندگی'), ('COMPANY', 'شرکت'), ('OTHER', 'سایر')], max_length=20)),
+                ('user', models.OneToOneField(on_delete=django.db.models.deletion.CASCADE, related_name='customer_profile', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'abstract': False,
+            },
+        ),
+    ]

apps/customers/migrations/0002_customerprofile_city_customerprofile_province.py

@@ -0,0 +1,9 @@
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [("customers", "0001_initial")]
+    operations = [
+        migrations.AddField(model_name="customerprofile", name="city", field=models.CharField(blank=True, max_length=100)),
+        migrations.AddField(model_name="customerprofile", name="province", field=models.CharField(blank=True, max_length=100)),
+    ]

apps/customers/migrations/0003_contactgroup_customerprofile_organization_name_and_more.py

@@ -0,0 +1,41 @@
+# Generated by Django 5.1.1 on 2026-09-08 09:57
+
+import apps.core.models
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('customers', '0002_customerprofile_city_customerprofile_province'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='ContactGroup',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('name', models.CharField(max_length=150)),
+                ('description', models.TextField(blank=True)),
+                ('is_active', models.BooleanField(default=True)),
+            ],
+            options={
+                'verbose_name': 'گروه مخاطبان',
+                'verbose_name_plural': 'گروه\u200cهای مخاطبان',
+                'ordering': ['unit__name', 'name'],
+            },
+            bases=(apps.core.models.PersianTextNormalizationMixin, models.Model),
+        ),
+        migrations.AddField(
+            model_name='customerprofile',
+            name='organization_name',
+            field=models.CharField(blank=True, max_length=180),
+        ),
+        migrations.AddField(
+            model_name='customerprofile',
+            name='stakeholder_type',
+            field=models.CharField(choices=[('CUSTOMER', 'مشتری'), ('SUPPLIER', 'تامین\u200cکننده'), ('CARRIER', 'باربری'), ('OTHER', 'سایر')], db_index=True, default='CUSTOMER', max_length=20),
+        ),
+    ]

apps/customers/migrations/0004_contactgroup_unit_customerprofile_groups_and_more.py

@@ -0,0 +1,29 @@
+# Generated by Django 5.1.1 on 2026-09-08 09:57
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('customers', '0003_contactgroup_customerprofile_organization_name_and_more'),
+        ('staff', '0004_organizationalunit_staffprofile_primary_unit_and_more'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='contactgroup',
+            name='unit',
+            field=models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='contact_groups', to='staff.organizationalunit'),
+        ),
+        migrations.AddField(
+            model_name='customerprofile',
+            name='groups',
+            field=models.ManyToManyField(blank=True, related_name='contacts', to='customers.contactgroup'),
+        ),
+        migrations.AddConstraint(
+            model_name='contactgroup',
+            constraint=models.UniqueConstraint(fields=('unit', 'name'), name='unique_contact_group_name_per_unit'),
+        ),
+    ]

apps/customers/models.py

@@ -0,0 +1,54 @@
+from django.conf import settings
+from django.db import models
+from apps.core.models import PersianTextNormalizationMixin, TimeStampedModel
+
+
+class ContactGroup(PersianTextNormalizationMixin, TimeStampedModel):
+    """A unit-owned address-book group; contacts may belong to many groups."""
+
+    persian_text_fields = {"name": False, "description": True}
+    name = models.CharField(max_length=150)
+    unit = models.ForeignKey(
+        "staff.OrganizationalUnit",
+        on_delete=models.CASCADE,
+        related_name="contact_groups",
+    )
+    description = models.TextField(blank=True)
+    is_active = models.BooleanField(default=True)
+
+    class Meta:
+        constraints = [
+            models.UniqueConstraint(fields=["unit", "name"], name="unique_contact_group_name_per_unit")
+        ]
+        ordering = ["unit__name", "name"]
+        verbose_name = "گروه مخاطبان"
+        verbose_name_plural = "گروه‌های مخاطبان"
+
+    def __str__(self):
+        return f"{self.unit}: {self.name}"
+
+
+class CustomerProfile(PersianTextNormalizationMixin, TimeStampedModel):
+    persian_text_fields = {"first_name": False, "last_name": False, "organization_name": False, "province": False, "city": False}
+    class Type(models.TextChoices):
+        PERSON="PERSON","شخص"; CONSUMER="CONSUMER","مصرف‌کننده نهایی"; SHOP="SHOP","فروشگاه"; REPRESENTATIVE="REPRESENTATIVE","نمایندگی"; COMPANY="COMPANY","شرکت"; OTHER="OTHER","سایر"
+    class StakeholderType(models.TextChoices):
+        CUSTOMER = "CUSTOMER", "مشتری"
+        SUPPLIER = "SUPPLIER", "تامین‌کننده"
+        CARRIER = "CARRIER", "باربری"
+        OTHER = "OTHER", "سایر"
+    user = models.OneToOneField(settings.AUTH_USER_MODEL, on_delete=models.CASCADE, related_name="customer_profile")
+    first_name = models.CharField(max_length=100, blank=True)
+    last_name = models.CharField(max_length=100, blank=True)
+    customer_type = models.CharField(max_length=20, choices=Type.choices, blank=True)
+    stakeholder_type = models.CharField(
+        max_length=20,
+        choices=StakeholderType.choices,
+        default=StakeholderType.CUSTOMER,
+        db_index=True,
+    )
+    organization_name = models.CharField(max_length=180, blank=True)
+    groups = models.ManyToManyField(ContactGroup, blank=True, related_name="contacts")
+    province = models.CharField(max_length=100, blank=True)
+    city = models.CharField(max_length=100, blank=True)
+    def __str__(self): return (f"{self.first_name} {self.last_name}".strip() or self.user.mobile or self.user.username)