adding

apps/orders/admin.py

@@ -0,0 +1,28 @@
+from django.contrib import admin
+
+from .models import Order, OrderStage, OrderStageLog
+
+
+@admin.register(OrderStage)
+class OrderStageAdmin(admin.ModelAdmin):
+    list_display = ("label", "user", "sort_order", "template", "requires_extra_input")
+    list_filter = ("user", "requires_extra_input")
+    search_fields = ("label", "user__phone")
+
+
+class OrderStageLogInline(admin.TabularInline):
+    model = OrderStageLog
+    extra = 0
+    readonly_fields = ("stage_label", "message_body", "extra_input_value", "created_at")
+    can_delete = False
+
+    def has_add_permission(self, request, obj=None):
+        return False
+
+
+@admin.register(Order)
+class OrderAdmin(admin.ModelAdmin):
+    list_display = ("customer_name", "customer_phone", "user", "current_stage", "is_completed", "updated_at")
+    list_filter = ("is_completed",)
+    search_fields = ("customer_name", "customer_phone", "user__phone", "tracking_code")
+    inlines = [OrderStageLogInline]

apps/orders/api/serializers.py

@@ -0,0 +1,52 @@
+from rest_framework import serializers
+
+from apps.orders.models import Order, OrderStage, OrderStageLog
+
+
+class OrderStageSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = OrderStage
+        fields = [
+            "id",
+            "label",
+            "template",
+            "sort_order",
+            "requires_extra_input",
+            "extra_input_label",
+            "updated_at",
+        ]
+        read_only_fields = ["updated_at"]
+
+    def validate_template(self, template):
+        if template is None:
+            return template
+        request = self.context["request"]
+        if template.user_id != request.user.id:
+            raise serializers.ValidationError("این قالب متعلق به شما نیست.")
+        return template
+
+
+class OrderStageLogSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = OrderStageLog
+        fields = ["id", "stage", "stage_label", "message_body", "extra_input_value", "created_at"]
+        read_only_fields = fields
+
+
+class OrderSerializer(serializers.ModelSerializer):
+    current_stage_label = serializers.CharField(source="current_stage.label", read_only=True, default="")
+
+    class Meta:
+        model = Order
+        fields = [
+            "id",
+            "customer_name",
+            "customer_phone",
+            "tracking_code",
+            "current_stage",
+            "current_stage_label",
+            "is_completed",
+            "created_at",
+            "updated_at",
+        ]
+        read_only_fields = ["current_stage", "is_completed", "created_at", "updated_at"]

apps/orders/api/services.py

@@ -0,0 +1,83 @@
+import re
+import uuid
+
+from django.db import transaction
+
+from apps.account.models import User
+from apps.banker.models import Contact
+from apps.messaging.api.services import BulkMessageService
+from apps.messaging.models import Channel
+from apps.orders.models import Order, OrderStage, OrderStageLog
+
+_FIELD_PATTERN = re.compile(r"\{(.*?)\}")
+
+
+class OrderStageService:
+    @staticmethod
+    def _render(order: Order, stage: OrderStage, extra_input_value: str = "") -> str:
+        body = stage.template.body if stage.template else ""
+        values = {
+            "نام": order.customer_name,
+            "شماره": order.customer_phone,
+            "کد پیگیری": order.tracking_code,
+            "مرحله": stage.label,
+            "ورودی": extra_input_value,
+        }
+        return _FIELD_PATTERN.sub(lambda m: values.get(m.group(1), m.group(0)), body)
+
+    @staticmethod
+    def _upsert_contact(user: User, order: Order) -> Contact:
+        contact = Contact.objects.filter(user=user, phone=order.customer_phone).first()
+        if contact:
+            return contact
+        return Contact.objects.create(
+            id=str(uuid.uuid4()), user=user, name=order.customer_name, phone=order.customer_phone
+        )
+
+    @staticmethod
+    @transaction.atomic
+    def advance(user: User, order_id: str, extra_input_value: str = "") -> Order:
+        order = Order.objects.select_for_update().get(pk=order_id, user=user)
+        if order.is_completed:
+            raise ValueError("این سفارش قبلا به آخرین مرحله رسیده است.")
+
+        stages = list(OrderStage.objects.filter(user=user).order_by("sort_order"))
+        if not stages:
+            raise ValueError("اول باید حداقل یک مرحله برای پیگیری سفارش تعریف کنی.")
+
+        if order.current_stage_id is None:
+            next_stage = stages[0]
+        else:
+            current_index = next((i for i, s in enumerate(stages) if s.id == order.current_stage_id), None)
+            if current_index is None or current_index + 1 >= len(stages):
+                raise ValueError("این سفارش قبلا به آخرین مرحله رسیده است.")
+            next_stage = stages[current_index + 1]
+
+        extra_input_value = (extra_input_value or "").strip()
+        if next_stage.requires_extra_input and not extra_input_value:
+            label = next_stage.extra_input_label or "ورودی این مرحله"
+            raise ValueError(f"برای این مرحله باید «{label}» را وارد کنی.")
+
+        contact = OrderStageService._upsert_contact(user, order)
+        rendered = OrderStageService._render(order, next_stage, extra_input_value)
+        if rendered:
+            BulkMessageService.create_and_dispatch(
+                user=user,
+                channels=[Channel.SMS],
+                contact_ids=[contact.id],
+                body_override=rendered,
+            )
+
+        order.current_stage = next_stage
+        order.is_completed = next_stage.id == stages[-1].id
+        order.save(update_fields=["current_stage", "is_completed", "updated_at"])
+
+        OrderStageLog.objects.create(
+            id=str(uuid.uuid4()),
+            order=order,
+            stage=next_stage,
+            stage_label=next_stage.label,
+            message_body=rendered,
+            extra_input_value=extra_input_value,
+        )
+        return order

apps/orders/api/views.py

@@ -0,0 +1,79 @@
+from rest_framework import generics, status
+from rest_framework.exceptions import NotFound, ValidationError
+from rest_framework.permissions import IsAuthenticated
+from rest_framework.response import Response
+from rest_framework.views import APIView
+
+from apps.billing.permissions import HasActiveFeature
+from apps.orders.api.services import OrderStageService
+from apps.orders.models import Order, OrderStage, OrderStageLog
+
+from .serializers import OrderSerializer, OrderStageLogSerializer, OrderStageSerializer
+
+
+class _UserScopedListCreateView(generics.ListCreateAPIView):
+    permission_classes = [IsAuthenticated, HasActiveFeature]
+    feature_key = "orders"
+
+    def get_queryset(self):
+        return self.model.objects.filter(user=self.request.user)
+
+    def perform_create(self, serializer):
+        serializer.save(user=self.request.user)
+
+
+class _UserScopedDetailView(generics.RetrieveUpdateDestroyAPIView):
+    permission_classes = [IsAuthenticated, HasActiveFeature]
+    feature_key = "orders"
+
+    def get_queryset(self):
+        return self.model.objects.filter(user=self.request.user)
+
+
+class OrderStageListCreateView(_UserScopedListCreateView):
+    model = OrderStage
+    serializer_class = OrderStageSerializer
+
+
+class OrderStageDetailView(_UserScopedDetailView):
+    model = OrderStage
+    serializer_class = OrderStageSerializer
+
+
+class OrderListCreateView(_UserScopedListCreateView):
+    model = Order
+    serializer_class = OrderSerializer
+
+
+class OrderDetailView(_UserScopedDetailView):
+    model = Order
+    serializer_class = OrderSerializer
+
+
+class AdvanceOrderStageView(APIView):
+    """با هر بار زدن «مرحله‌ی بعد»، سفارش را به مرحله‌ی بعدیِ تعریف‌شده
+    می‌برد و طبق قالبِ همان مرحله برای مشتریِ همین سفارش پیامک می‌فرستد."""
+
+    permission_classes = [IsAuthenticated, HasActiveFeature]
+    feature_key = "orders"
+
+    def post(self, request, pk):
+        if not Order.objects.filter(pk=pk, user=request.user).exists():
+            raise NotFound("سفارش یافت نشد.")
+        extra_input_value = request.data.get("extra_input_value", "")
+        try:
+            order = OrderStageService.advance(request.user, pk, extra_input_value)
+        except Order.DoesNotExist:
+            raise NotFound("سفارش یافت نشد.")
+        except ValueError as exc:
+            raise ValidationError(str(exc))
+        return Response(OrderSerializer(order).data, status=status.HTTP_200_OK)
+
+
+class OrderStageLogListView(generics.ListAPIView):
+    serializer_class = OrderStageLogSerializer
+    permission_classes = [IsAuthenticated, HasActiveFeature]
+    feature_key = "orders"
+
+    def get_queryset(self):
+        return OrderStageLog.objects.filter(order_id=self.kwargs["pk"], order__user=self.request.user)

apps/orders/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class OrdersConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "apps.orders"
+    verbose_name = "پیگیری سفارش"

apps/orders/migrations/0001_initial.py

@@ -0,0 +1,69 @@
+# Generated by Django 5.1.15 on 2026-08-23 21:57
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('banker', '0002_structuredtemplate_structuredtemplatefield'),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='OrderStage',
+            fields=[
+                ('id', models.CharField(max_length=36, primary_key=True, serialize=False)),
+                ('label', models.CharField(max_length=150, verbose_name='عنوان مرحله')),
+                ('sort_order', models.PositiveIntegerField(default=0, verbose_name='ترتیب')),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('template', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='order_stages', to='banker.messagetemplate', verbose_name='قالب پیامک این مرحله')),
+                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='order_stages', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'verbose_name': 'مرحله\u200cی پیگیری سفارش',
+                'verbose_name_plural': 'مراحل پیگیری سفارش',
+                'ordering': ['sort_order'],
+            },
+        ),
+        migrations.CreateModel(
+            name='Order',
+            fields=[
+                ('id', models.CharField(max_length=36, primary_key=True, serialize=False)),
+                ('customer_name', models.CharField(max_length=150, verbose_name='نام مشتری')),
+                ('customer_phone', models.CharField(max_length=20, verbose_name='شماره مشتری')),
+                ('tracking_code', models.CharField(blank=True, max_length=100, verbose_name='کد پیگیری پستی')),
+                ('is_completed', models.BooleanField(default=False, verbose_name='تکمیل\u200cشده')),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='orders', to=settings.AUTH_USER_MODEL)),
+                ('current_stage', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='orders', to='orders.orderstage')),
+            ],
+            options={
+                'verbose_name': 'سفارش',
+                'verbose_name_plural': 'سفارش\u200cها',
+                'ordering': ['-updated_at'],
+            },
+        ),
+        migrations.CreateModel(
+            name='OrderStageLog',
+            fields=[
+                ('id', models.CharField(max_length=36, primary_key=True, serialize=False)),
+                ('stage_label', models.CharField(max_length=150, verbose_name='عنوان مرحله')),
+                ('message_body', models.TextField(blank=True, verbose_name='متن پیامک ارسالی')),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('order', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='stage_logs', to='orders.order')),
+                ('stage', models.ForeignKey(null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='+', to='orders.orderstage')),
+            ],
+            options={
+                'verbose_name': 'تاریخچه\u200cی مرحله\u200cی سفارش',
+                'verbose_name_plural': 'تاریخچه\u200cی مراحل سفارش',
+                'ordering': ['created_at'],
+            },
+        ),
+    ]

apps/orders/migrations/0002_orderstage_extra_input_label_and_more.py

@@ -0,0 +1,28 @@
+# Generated by Django 5.1.15 on 2026-08-24 12:11
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('orders', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='orderstage',
+            name='extra_input_label',
+            field=models.CharField(blank=True, help_text='مثلا: کد تسویه، کد محصول — وقتی سفارش به این مرحله می\u200cرسد از کاربر پرسیده می\u200cشود.', max_length=100, verbose_name='عنوان ورودی اضافه'),
+        ),
+        migrations.AddField(
+            model_name='orderstage',
+            name='requires_extra_input',
+            field=models.BooleanField(default=False, verbose_name='این مرحله به یک ورودی اضافه نیاز دارد'),
+        ),
+        migrations.AddField(
+            model_name='orderstagelog',
+            name='extra_input_value',
+            field=models.CharField(blank=True, max_length=255, verbose_name='ورودی اضافه\u200cی این مرحله'),
+        ),
+    ]

apps/orders/models.py

@@ -0,0 +1,86 @@
+from django.conf import settings
+from django.db import models
+from django.utils.translation import gettext_lazy as _
+
+from apps.banker.models import MessageTemplate
+
+# برای آنلاین‌شاپ‌های کوچک: صاحب کسب‌وکار مراحل کارش را تعریف می‌کند (مثلا
+# «آماده‌سازی» -> «بسته‌بندی» -> «ارسال» -> «تحویل»)، هر مرحله به یک قالب
+# پیام (apps.banker.MessageTemplate) وصل است، و برای هر سفارش با زدن «مرحله‌ی
+# بعد» یک پیامک خودکار از روی همان قالب برای مشتری آن سفارش می‌رود.
+
+
+class OrderStage(models.Model):
+    id = models.CharField(max_length=36, primary_key=True)
+    user = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE, related_name="order_stages")
+    label = models.CharField(max_length=150, verbose_name=_("عنوان مرحله"))
+    template = models.ForeignKey(
+        MessageTemplate,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="order_stages",
+        verbose_name=_("قالب پیامک این مرحله"),
+    )
+    sort_order = models.PositiveIntegerField(default=0, verbose_name=_("ترتیب"))
+    requires_extra_input = models.BooleanField(
+        default=False, verbose_name=_("این مرحله به یک ورودی اضافه نیاز دارد")
+    )
+    extra_input_label = models.CharField(
+        max_length=100,
+        blank=True,
+        verbose_name=_("عنوان ورودی اضافه"),
+        help_text=_("مثلا: کد تسویه، کد محصول — وقتی سفارش به این مرحله می‌رسد از کاربر پرسیده می‌شود."),
+    )
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        verbose_name = _("مرحله‌ی پیگیری سفارش")
+        verbose_name_plural = _("مراحل پیگیری سفارش")
+        ordering = ["sort_order"]
+
+    def __str__(self):
+        return self.label
+
+
+class Order(models.Model):
+    id = models.CharField(max_length=36, primary_key=True)
+    user = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE, related_name="orders")
+    customer_name = models.CharField(max_length=150, verbose_name=_("نام مشتری"))
+    customer_phone = models.CharField(max_length=20, verbose_name=_("شماره مشتری"))
+    tracking_code = models.CharField(max_length=100, blank=True, verbose_name=_("کد پیگیری پستی"))
+    current_stage = models.ForeignKey(
+        OrderStage, on_delete=models.SET_NULL, null=True, blank=True, related_name="orders"
+    )
+    is_completed = models.BooleanField(default=False, verbose_name=_("تکمیل‌شده"))
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        verbose_name = _("سفارش")
+        verbose_name_plural = _("سفارش‌ها")
+        ordering = ["-updated_at"]
+
+    def __str__(self):
+        return f"{self.customer_name} ({self.customer_phone})"
+
+
+class OrderStageLog(models.Model):
+    """تاریخچه‌ی مراحل طی‌شده‌ی یک سفارش. عنوان مرحله و متن پیام همان لحظه
+    اسنپ‌شات می‌شود تا اگر بعدا مرحله ویرایش/حذف شد، تاریخچه دست‌نخورده بماند."""
+
+    id = models.CharField(max_length=36, primary_key=True)
+    order = models.ForeignKey(Order, on_delete=models.CASCADE, related_name="stage_logs")
+    stage = models.ForeignKey(OrderStage, on_delete=models.SET_NULL, null=True, related_name="+")
+    stage_label = models.CharField(max_length=150, verbose_name=_("عنوان مرحله"))
+    message_body = models.TextField(blank=True, verbose_name=_("متن پیامک ارسالی"))
+    extra_input_value = models.CharField(max_length=255, blank=True, verbose_name=_("ورودی اضافه‌ی این مرحله"))
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    class Meta:
+        verbose_name = _("تاریخچه‌ی مرحله‌ی سفارش")
+        verbose_name_plural = _("تاریخچه‌ی مراحل سفارش")
+        ordering = ["created_at"]
+
+    def __str__(self):
+        return f"{self.order} — {self.stage_label}"

apps/orders/urls.py

@@ -0,0 +1,20 @@
+from django.urls import path
+
+from .api.views import (
+    AdvanceOrderStageView,
+    OrderDetailView,
+    OrderListCreateView,
+    OrderStageDetailView,
+    OrderStageListCreateView,
+    OrderStageLogListView,
+)
+
+app_name = "orders"
+urlpatterns = [
+    path("stages/", OrderStageListCreateView.as_view(), name="stage-list"),
+    path("stages/<str:pk>/", OrderStageDetailView.as_view(), name="stage-detail"),
+    path("orders/", OrderListCreateView.as_view(), name="order-list"),
+    path("orders/<str:pk>/", OrderDetailView.as_view(), name="order-detail"),
+    path("orders/<str:pk>/advance/", AdvanceOrderStageView.as_view(), name="order-advance"),
+    path("orders/<str:pk>/logs/", OrderStageLogListView.as_view(), name="order-logs"),
+]