feat(transaction): implement receipt management for transactions

- Added `TransactionReceipt` model to store payment receipts uploaded by users. - Introduced endpoints for uploading receipts and listing receipts associated with transactions. - Updated `TransactionParticipant` model to include a new status 'waiting_approval'. - Enhanced serializers to handle receipt uploads and retrievals, including validation for file uploads. - Updated admin interface to manage transaction receipts effectively. - Added comprehensive API documentation for transaction receipt operations.
6 months ago · c0cd7ff8f9
9 changed files with 968 additions and 26 deletions
--- a/apps/library/migrations/0009_alter_book_language.py
+++ b/apps/library/migrations/0009_alter_book_language.py
@ -0,0 +1,21 @@
 # Generated by Django 5.1.8 on 2025-12-03 23:32
 import dj_language.field
 import django.db.models.deletion
 from django.db import migrations
 class Migration(migrations.Migration):
    dependencies = [
        ('dj_language', '0002_auto_20220120_1344'),
        ('library', '0008_auto_20251203_1533'),
    ]
    operations = [
        migrations.AlterField(
            model_name='book',
            name='language',
            field=dj_language.field.LanguageField(blank=True, default=69, limit_choices_to={'status': True}, null=True, on_delete=django.db.models.deletion.PROTECT, related_name='+', to='dj_language.language', verbose_name='Language'),
        ),
    ]
--- a/apps/transaction/admin.py
+++ b/apps/transaction/admin.py
@ -3,10 +3,10 @@ from django.utils.translation import gettext_lazy as _
 from django.utils.html import format_html
 from django.contrib import messages
 from unfold.admin import ModelAdmin, StackedInline
 from unfold.admin import ModelAdmin, StackedInline, TabularInline
 from unfold.decorators import display
 from apps.transaction.models import TransactionParticipant, ParticipantInfo
 from apps.transaction.models import TransactionParticipant, ParticipantInfo, TransactionReceipt
 from apps.course.models import Participant
 from utils.admin import project_admin_site
@ -21,13 +21,25 @@ class ParticipantInfoInline(StackedInline):
    show_change_link = True
 class TransactionReceiptInline(TabularInline):
    model = TransactionReceipt
    extra = 0
    fields = ['file', 'description', 'uploaded_at']
    readonly_fields = ['uploaded_at']
    classes = ['collapse']
    tab = True
    show_change_link = True
    verbose_name = _('Payment Receipt')
    verbose_name_plural = _('Payment Receipts')
@admin.register(TransactionParticipant)
 class TransactionParticipantAdmin(ModelAdmin):
    list_display = ('user', 'course', 'payment_status', 'price_display', 'participant_status', 'created_at', 'updated_at')
    list_display = ('user', 'course', 'payment_status', 'price_display', 'participant_status', 'receipts_count', 'created_at', 'updated_at')
    list_filter = ('status', 'course', 'created_at')
    search_fields = ('user__email', 'course__title')
    readonly_fields = [ 'created_at', 'updated_at']
    inlines = [ParticipantInfoInline]
    readonly_fields = ['created_at', 'updated_at']
    inlines = [ParticipantInfoInline, TransactionReceiptInline]
    autocomplete_fields = ['user',]
    show_change_link = True
    ordering = ('-created_at',)
@ -48,7 +60,17 @@ class TransactionParticipantAdmin(ModelAdmin):
            return format_html('<span class="unfold-badge unfold-badge--success">Paid</span>')
        elif obj.status == 'failed':
            return format_html('<span class="unfold-badge unfold-badge--danger">Failed</span>')
        elif obj.status == 'waiting_approval':
            return format_html('<span class="unfold-badge unfold-badge--info">Waiting Approval</span>')
        return format_html('<span class="unfold-badge unfold-badge--warning">Pending</span>')
    @display(description=_("Receipts Count"))
    def receipts_count(self, obj):
        """Display count of uploaded receipts"""
        count = obj.receipts.count()
        if count > 0:
            return format_html('<span class="unfold-badge unfold-badge--info">{} receipts</span>', count)
        return format_html('<span class="unfold-badge unfold-badge--secondary">No receipts</span>')
    @display(description=_("Price"), ordering="price")
    def price_display(self, obj):
@ -106,3 +128,32 @@ class TransactionParticipantAdmin(ModelAdmin):
        return super().get_queryset(request).filter(is_deleted=False)
 project_admin_site.register(TransactionParticipant, TransactionParticipantAdmin)
@admin.register(TransactionReceipt)
 class TransactionReceiptAdmin(ModelAdmin):
    list_display = ('transaction', 'file', 'uploaded_at', 'description_preview')
    list_filter = ('uploaded_at', 'transaction__status')
    search_fields = ('transaction__user__email', 'transaction__course__title', 'description')
    readonly_fields = ['uploaded_at']
    autocomplete_fields = ['transaction']
    ordering = ('-uploaded_at',)
    fieldsets = (
        (None, {
            'fields': ('transaction', 'file', 'description')
        }),
        (_('Timestamps'), {
            'fields': ('uploaded_at',),
            'classes': ('collapse',)
        }),
    )
    @display(description=_("Description"))
    def description_preview(self, obj):
        """Display truncated description"""
        if obj.description:
            return obj.description[:50] + '...' if len(obj.description) > 50 else obj.description
        return '-'
 project_admin_site.register(TransactionReceipt, TransactionReceiptAdmin)
--- a/apps/transaction/doc.py
+++ b/apps/transaction/doc.py
@ -0,0 +1,529 @@
 def doc_upload_transaction_receipts():
    return """
 # 🐈 Scenario
 🛠️ آپلود رسید پرداخت برای تراکنش
 این API برای آپلود یک یا چند رسید پرداخت برای یک تراکنش استفاده می‌شود.
 پس از آپلود موفقیت‌آمیز، وضعیت تراکنش به 'waiting_approval' (در انتظار تایید) تغییر می‌کند.
 ---
 ## 🚀 روند آپلود (دو مرحله‌ای)
 ### مرحله 1️⃣: آپلود فایل به سرور موقت
 ابتدا باید فایل‌های خود را به endpoint زیر آپلود کنید:
 ```
 POST /upload-tmp-media/
 Content-Type: multipart/form-data
 Body:
 - file: [فایل رسید]
 ```
 **پاسخ:**
 ```json
 {
  "url": "/static/tmp/xyz123-receipt.jpg",
  "name": "receipt.jpg",
  "size": "1024000",
  "mime_type": "image/jpeg"
 }
 ```
 ### مرحله 2️⃣: ثبت URL فایل‌ها در تراکنش
 سپس URL های دریافتی را به این endpoint ارسال کنید:
 ```
 POST /api/transactions/<transaction_id>/receipts/upload/
 Content-Type: application/json
 ```
 ---
 ## 🚀 درخواست API (مرحله 2)
 ### URL:
 ```
 POST /api/transactions/<transaction_id>/receipts/upload/
 ```
 ### پارامترهای URL:
 | کلید             | نوع داده  | توضیحات                                                  |
 |------------------|-----------|----------------------------------------------------------|
 | `transaction_id` | Integer   | شناسه تراکنش که می‌خواهید رسید برای آن ثبت کنید         |
 ### پارامترهای درخواست (JSON Body):
 | کلید          | نوع داده  | الزامی | توضیحات                                                  |
 |---------------|-----------|--------|----------------------------------------------------------|
 | `files`       | String[]  | بله    | لیست URL های فایل‌های آپلود شده از مرحله 1 (حداکثر 10 فایل) |
 | `description` | String    | خیر    | توضیحات اختیاری درباره رسیدها                            |
 ---
 ## 💡 نکات مهم:
 1. **روند دو مرحله‌ای**:
   - **مرحله 1**: ابتدا فایل‌ها را به `/upload-tmp-media/` آپلود کنید
   - **مرحله 2**: سپس URL های دریافتی را به این API ارسال کنید
 2. **محدودیت فایل‌ها**:
   - حداکثر 10 فایل می‌توانید در هر درخواست ثبت کنید
 3. **وضعیت تراکنش**:
   - فقط می‌توانید برای تراکنش‌هایی با وضعیت 'pending' یا 'waiting_approval' رسید آپلود کنید
   - پس از ثبت موفقیت‌آمیز، وضعیت تراکنش به 'waiting_approval' تغییر می‌کند
 4. **احراز هویت**:
   - باید توکن احراز هویت را در هدر درخواست ارسال کنید
   - فقط می‌توانید برای تراکنش‌های خودتان رسید آپلود کنید
 ---
 ## 📊 پاسخ‌ها
 | کد وضعیت      | توضیحات                                                   |
 |---------------|-----------------------------------------------------------|
 | `201`         | موفقیت‌آمیز - رسیدها با موفقیت ثبت شدند                  |
 | `400`         | داده‌های نامعتبر یا تراکنش قادر به دریافت رسید نیست      |
 | `403`         | عدم دسترسی - شما صاحب این تراکنش نیستید                  |
 | `404`         | تراکنش یافت نشد                                           |
 ---
 ## 📄 نمونه درخواست کامل (JSON):
 ```json
 {
  "files": [
    "/static/tmp/xyz123-receipt1.jpg",
    "/static/tmp/abc456-receipt2.jpg"
  ],
  "description": "Payment receipt for Python course"
 }
 ```
 ---
 ## 📄 نمونه پاسخ موفقیت‌آمیز
 ```json
 {
  "success": true,
  "message": "Receipts uploaded successfully",
  "transaction_status": "waiting_approval",
  "receipts": [
    {
      "id": 1,
      "file": "http://example.com/media/receipts/1/receipt1.jpg",
      "description": "Payment receipt for course enrollment",
      "uploaded_at": "2025-12-03T10:30:00Z"
    },
    {
      "id": 2,
      "file": "http://example.com/media/receipts/1/receipt2.jpg",
      "description": "Payment receipt for course enrollment",
      "uploaded_at": "2025-12-03T10:30:05Z"
    }
  ]
 }
 ```
 ---
 ## 📄 نمونه درخواست کامل (cURL):
 ### مرحله 1 - آپلود فایل:
 ```bash
 curl -X POST \\
  'http://your-api.com/upload-tmp-media/' \\
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \\
  -F 'file=@/path/to/receipt1.jpg'
 ```
 ### مرحله 2 - ثبت رسید:
 ```bash
 curl -X POST \\
  'http://your-api.com/api/transactions/123/receipts/upload/' \\
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \\
  -H 'Content-Type: application/json' \\
  -d '{
    "files": ["/static/tmp/xyz123-receipt1.jpg"],
    "description": "Payment receipt for Python course"
  }'
 ```
 ---
 ## 📄 نمونه پاسخ خطا (403 - عدم دسترسی):
 ```json
 {
  "message": "You don't have permission to upload receipts for this transaction"
 }
 ```
 ---
 ## 📄 نمونه پاسخ خطا (400 - وضعیت نامعتبر):
 ```json
 {
  "message": "Cannot upload receipts for transaction with status 'success'"
 }
 ```
 """
 def doc_list_transaction_receipts():
    return """
 # 🐈 Scenario
 🛠️ لیست رسیدهای پرداخت یک تراکنش
 این API برای دریافت لیست تمام رسیدهای آپلود شده برای یک تراکنش خاص استفاده می‌شود.
 ---
 ## 🚀 درخواست API
 ### URL:
 ```
 GET /api/transactions/<transaction_id>/receipts/
 ```
 ### پارامترهای URL:
 | کلید             | نوع داده  | توضیحات                                                  |
 |------------------|-----------|----------------------------------------------------------|
 | `transaction_id` | Integer   | شناسه تراکنش که می‌خواهید رسیدهای آن را مشاهده کنید      |
 ---
 ## 💡 نکات مهم:
 1. **احراز هویت**:
   - باید توکن احراز هویت را در هدر درخواست ارسال کنید
   - فقط می‌توانید رسیدهای تراکنش‌های خودتان را مشاهده کنید
 2. **مرتب‌سازی**:
   - رسیدها بر اساس تاریخ آپلود (جدیدترین اول) مرتب می‌شوند
 ---
 ## 📊 پاسخ‌ها
 | کد وضعیت      | توضیحات                                                   |
 |---------------|-----------------------------------------------------------|
 | `200`         | موفقیت‌آمیز - لیست رسیدها بازگردانده شد                  |
 | `403`         | عدم دسترسی - شما صاحب این تراکنش نیستید                  |
 | `404`         | تراکنش یافت نشد                                           |
 ---
 ## 📄 نمونه پاسخ موفقیت‌آمیز
 ```json
 [
  {
    "id": 1,
    "file": "http://example.com/media/receipts/1/receipt1.jpg",
    "description": "Payment receipt for course enrollment",
    "uploaded_at": "2025-12-03T10:30:00Z"
  },
  {
    "id": 2,
    "file": "http://example.com/media/receipts/1/receipt2.jpg",
    "description": "Second payment receipt",
    "uploaded_at": "2025-12-03T10:25:00Z"
  }
 ]
 ```
 ---
 ## 📄 توضیحات مقادیر پاسخ
 | کلید          | نوع داده   | توضیحات                                                  |
 |---------------|------------|----------------------------------------------------------|
 | `id`          | Integer    | شناسه یکتای رسید                                         |
 | `file`        | String     | URL کامل فایل رسید آپلود شده                            |
 | `description` | String     | توضیحات اختیاری درباره رسید (ممکن است خالی باشد)        |
 | `uploaded_at` | DateTime   | تاریخ و زمان آپلود رسید                                  |
 ---
 ## 📄 نمونه درخواست (cURL):
 ```bash
 curl -X GET \\
  'http://your-api.com/api/transactions/123/receipts/' \\
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
 ```
 ---
 ## 📄 نمونه پاسخ خطا (403 - عدم دسترسی):
 ```json
 {
  "message": "You don't have permission to view receipts for this transaction"
 }
 ```
 ---
 ## 📄 نمونه پاسخ خطا (404 - تراکنش یافت نشد):
 ```json
 {
  "message": "Transaction not found"
 }
 ```
 """
 def doc_transaction_list():
    return """
 # 🐈 Scenario
 🛠️ لیست تراکنش‌های کاربر
 این API برای دریافت لیست تمام تراکنش‌های کاربر احراز هویت شده استفاده می‌شود.
 ---
 ## 🚀 درخواست API
 ### URL:
 ```
 GET /api/transactions/list/
 ```
 ---
 ## 💡 نکات مهم:
 1. **احراز هویت**:
   - باید توکن احراز هویت را در هدر درخواست ارسال کنید
   - فقط تراکنش‌های خودتان را مشاهده می‌کنید
 2. **فیلترینگ خودکار**:
   - تراکنش‌های حذف شده (soft deleted) نمایش داده نمی‌شوند
 3. **وضعیت‌های تراکنش**:
   - `pending`: در انتظار پرداخت
   - `waiting_approval`: در انتظار تایید (رسید آپلود شده)
   - `success`: پرداخت موفق و تایید شده
   - `failed`: پرداخت ناموفق
 ---
 ## 📊 پاسخ‌ها
 | کد وضعیت      | توضیحات                                                   |
 |---------------|-----------------------------------------------------------|
 | `200`         | موفقیت‌آمیز - لیست تراکنش‌ها بازگردانده شد               |
 | `401`         | عدم احراز هویت                                            |
 ---
 ## 📄 توضیحات مقادیر پاسخ
 | کلید          | نوع داده   | توضیحات                                                  |
 |---------------|------------|----------------------------------------------------------|
 | `id`          | Integer    | شناسه یکتای تراکنش                                       |
 | `course`      | Object     | اطلاعات دوره مرتبط با تراکنش                             |
 | `status`      | String     | وضعیت تراکنش (pending, waiting_approval, success, failed) |
 | `price`       | Decimal    | مبلغ تراکنش                                              |
 | `created_at`  | DateTime   | تاریخ و زمان ایجاد تراکنش                                |
 | `updated_at`  | DateTime   | تاریخ و زمان آخرین به‌روزرسانی تراکنش                    |
 ---
 ## 📄 نمونه پاسخ موفقیت‌آمیز
 ```json
 [
  {
    "id": 1,
    "course": {
      "id": 5,
      "title": "Python Programming Basics",
      "slug": "python-programming-basics",
      "thumbnail": "http://example.com/media/courses/thumbnails/python.jpg",
      "price": "99.00",
      "final_price": "79.00"
    },
    "status": "waiting_approval",
    "price": "79.00",
    "created_at": "2025-12-01T10:00:00Z",
    "updated_at": "2025-12-03T10:30:00Z"
  },
  {
    "id": 2,
    "course": {
      "id": 8,
      "title": "Django Web Development",
      "slug": "django-web-development",
      "thumbnail": "http://example.com/media/courses/thumbnails/django.jpg",
      "price": "149.00",
      "final_price": "149.00"
    },
    "status": "success",
    "price": "149.00",
    "created_at": "2025-11-28T14:20:00Z",
    "updated_at": "2025-11-29T09:15:00Z"
  }
 ]
 ```
 ---
 ## 📄 نمونه درخواست (cURL):
 ```bash
 curl -X GET \\
  'http://your-api.com/api/transactions/list/' \\
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
 ```
 """
 def doc_create_transaction():
    return """
 # 🐈 Scenario
 🛠️ ثبت‌نام در دوره و ایجاد تراکنش
 این API برای ثبت‌نام کاربر در یک دوره و ایجاد تراکنش استفاده می‌شود.
 ---
 ## 🚀 درخواست API
 ### URL:
 ```
 POST /api/transactions/<slug>/join/
 ```
 ### پارامترهای URL:
 | کلید    | نوع داده  | توضیحات                                                  |
 |---------|-----------|----------------------------------------------------------|
 | `slug`  | String    | اسلاگ دوره‌ای که می‌خواهید در آن ثبت‌نام کنید            |
 ### پارامترهای درخواست (JSON Body):
 | کلید                | نوع داده  | الزامی | توضیحات                                                  |
 |---------------------|-----------|--------|----------------------------------------------------------|
 | `participant_infos` | Array     | بله    | لیست اطلاعات شرکت‌کنندگان                                |
 ### ساختار `participant_infos`:
 | کلید          | نوع داده  | الزامی | توضیحات                                                  |
 |---------------|-----------|--------|----------------------------------------------------------|
 | `fullname`    | String    | بله    | نام کامل شرکت‌کننده                                      |
 | `email`       | String    | بله    | ایمیل شرکت‌کننده (برای دوره رایگان باید با ایمیل کاربر احراز هویت شده یکسان باشد) |
 | `phone_number`| String    | خیر    | شماره تلفن شرکت‌کننده                                    |
 | `gender`      | String    | خیر    | جنسیت شرکت‌کننده (male, female)                         |
 | `birthdate`   | Date      | خیر    | تاریخ تولد شرکت‌کننده (فرمت: YYYY-MM-DD)                |
 ---
 ## 💡 نکات مهم:
 1. **دوره رایگان**:
   - اگر دوره رایگان باشد و فقط یک شرکت‌کننده در لیست باشد و ایمیل او با کاربر احراز هویت شده یکسان باشد، تراکنش به صورت خودکار تایید می‌شود (status = 'success')
   - کاربر به صورت خودکار به عنوان دانشجو در دوره ثبت می‌شود
 2. **دوره پولی**:
   - تراکنش با وضعیت 'pending' ایجاد می‌شود
   - کاربر باید رسید پرداخت خود را آپلود کند
   - پس از آپلود رسید، وضعیت به 'waiting_approval' تغییر می‌کند
   - پس از تایید توسط ادمین، وضعیت به 'success' تغییر می‌کند
 3. **احراز هویت**:
   - باید توکن احراز هویت را در هدر درخواست ارسال کنید
 ---
 ## 📊 پاسخ‌ها
 | کد وضعیت      | توضیحات                                                   |
 |---------------|-----------------------------------------------------------|
 | `201`         | موفقیت‌آمیز - تراکنش ایجاد شد                            |
 | `400`         | داده‌های نامعتبر                                          |
 | `404`         | دوره یافت نشد                                             |
 ---
 ## 📄 نمونه درخواست (JSON Body):
 ```json
 {
  "participant_infos": [
    {
      "fullname": "علی رضایی",
      "email": "ali@example.com",
      "phone_number": "+989123456789",
      "gender": "male",
      "birthdate": "1995-05-15"
    }
  ]
 }
 ```
 ---
 ## 📄 نمونه پاسخ موفقیت‌آمیز (دوره رایگان):
 ```json
 {
  "message": "Transaction Participant created successfully.",
  "transaction_id": 123,
  "participant_infos": [
    {
      "fullname": "علی رضایی",
      "email": "ali@example.com",
      "phone_number": "+989123456789",
      "gender": "male",
      "birthdate": "1995-05-15"
    }
  ]
 }
 ```
 ---
 ## 📄 نمونه پاسخ موفقیت‌آمیز (دوره پولی):
 ```json
 {
  "message": "Transaction Participant created successfully.",
  "transaction_id": 124,
  "participant_infos": [
    {
      "fullname": "سارا احمدی",
      "email": "sara@example.com",
      "phone_number": "+989123456789",
      "gender": "female",
      "birthdate": "1998-03-20"
    }
  ]
 }
 ```
 توجه: برای دوره پولی، شما باید با استفاده از `transaction_id` بازگشتی، رسید پرداخت خود را از طریق API آپلود رسید آپلود کنید.
 ---
 ## 📄 نمونه درخواست (cURL):
 ```bash
 curl -X POST \\
  'http://your-api.com/api/transactions/python-programming-basics/join/' \\
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \\
  -H 'Content-Type: application/json' \\
  -d '{
    "participant_infos": [
      {
        "fullname": "علی رضایی",
        "email": "ali@example.com",
        "phone_number": "+989123456789",
        "gender": "male",
        "birthdate": "1995-05-15"
      }
    ]
  }'
 ```
 """
--- a/apps/transaction/migrations/0003_alter_transactionparticipant_status_and_more.py
+++ b/apps/transaction/migrations/0003_alter_transactionparticipant_status_and_more.py
@ -0,0 +1,35 @@
 # Generated by Django 5.1.8 on 2025-12-03 23:32
 import apps.transaction.models
 import django.db.models.deletion
 from django.db import migrations, models
 class Migration(migrations.Migration):
    dependencies = [
        ('transaction', '0002_remove_transactionparticipant_is_paid_and_more'),
    ]
    operations = [
        migrations.AlterField(
            model_name='transactionparticipant',
            name='status',
            field=models.CharField(choices=[('pending', 'Pending'), ('waiting_approval', 'Waiting for Approval'), ('success', 'Success'), ('failed', 'Failed')], default='pending', max_length=20, verbose_name='Transaction Status'),
        ),
        migrations.CreateModel(
            name='TransactionReceipt',
            fields=[
                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
                ('file', models.FileField(help_text='Upload payment receipt image or document', upload_to=apps.transaction.models.receipt_file_upload_to, verbose_name='Receipt File')),
                ('uploaded_at', models.DateTimeField(auto_now_add=True, verbose_name='Uploaded At')),
                ('description', models.TextField(blank=True, help_text='Optional description or notes about the receipt', null=True, verbose_name='Description')),
                ('transaction', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='receipts', to='transaction.transactionparticipant', verbose_name='Transaction')),
            ],
            options={
                'verbose_name': 'Transaction Receipt',
                'verbose_name_plural': 'Transaction Receipts',
                'ordering': ['-uploaded_at'],
            },
        ),
    ]
--- a/apps/transaction/models.py
+++ b/apps/transaction/models.py
@ -1,4 +1,5 @@
 from django.db import models
 import os
 from django.utils.translation import gettext_lazy as _
@ -8,6 +9,10 @@ from phonenumber_field.modelfields import PhoneNumberField
 from utils.validators import validate_possible_number
 def receipt_file_upload_to(instance, filename):
    return os.path.join(f"receipts/{instance.transaction.id}/{filename}")
@ -16,6 +21,7 @@ class TransactionParticipant(models.Model):
    class TransactionStatus(models.TextChoices):
        PENDING = 'pending', _('Pending')
        WAITING_APPROVAL = 'waiting_approval', _('Waiting for Approval')
        SUCCESS = 'success', _('Success')
        FAILED = 'failed', _('Failed')
@ -56,9 +62,9 @@ class ParticipantInfo(models.Model):
        FEMALE = 'female', 'Female'
    transaction_participant = models.ForeignKey(
        TransactionParticipant, 
        on_delete=models.CASCADE, 
        related_name='participant_infos',  
        TransactionParticipant,
        on_delete=models.CASCADE,
        related_name='participant_infos',
        verbose_name="Transaction Participant"
    )
    fullname = models.CharField(max_length=255, verbose_name="Full Name", help_text="Enter the full name of the user.")
@ -73,6 +79,38 @@ class ParticipantInfo(models.Model):
        return f"{self.fullname} (Transaction: {self.transaction_participant.id}) - {self.email}"
 class TransactionReceipt(models.Model):
    """
    Model for storing payment receipts uploaded by users for transactions
    """
    transaction = models.ForeignKey(
        TransactionParticipant,
        on_delete=models.CASCADE,
        related_name='receipts',
        verbose_name=_('Transaction')
    )
    file = models.FileField(
        upload_to=receipt_file_upload_to,
        verbose_name=_('Receipt File'),
        help_text=_('Upload payment receipt image or document')
    )
    uploaded_at = models.DateTimeField(auto_now_add=True, verbose_name=_('Uploaded At'))
    description = models.TextField(
        blank=True,
        null=True,
        verbose_name=_('Description'),
        help_text=_('Optional description or notes about the receipt')
    )
    class Meta:
        verbose_name = _('Transaction Receipt')
        verbose_name_plural = _('Transaction Receipts')
        ordering = ['-uploaded_at']
    def __str__(self):
        return f"Receipt for Transaction #{self.transaction.id} - {self.uploaded_at.strftime('%Y-%m-%d %H:%M')}"
--- a/apps/transaction/serializers.py
+++ b/apps/transaction/serializers.py
@ -1,8 +1,9 @@
 from rest_framework import serializers
 from apps.transaction.models import TransactionParticipant, ParticipantInfo
 from apps.transaction.models import TransactionParticipant, ParticipantInfo, TransactionReceipt
 from apps.course.serializers import CourseDetailSerializer
 from utils import FileFieldSerializer
@ -39,11 +40,57 @@ class TransactionParticipantSerializer(serializers.ModelSerializer):
 class TransactionListSerializer(serializers.ModelSerializer):
    course = serializers.SerializerMethodField()
    receipts = serializers.SerializerMethodField()
    class Meta:
        model = TransactionParticipant
        fields = ['id', 'course', 'status', 'price', 'created_at', 'updated_at']
        fields = ['id', 'course', 'status', 'price', 'receipts', 'created_at', 'updated_at']
    def get_course(self, obj):
        return CourseDetailSerializer(obj.course, context=self.context).data
    def get_receipts(self, obj):
        receipts = obj.receipts.all()
        return TransactionReceiptSerializer(receipts, many=True, context=self.context).data
 class TransactionReceiptSerializer(serializers.ModelSerializer):
    """
    Serializer for uploading payment receipts
    Uses FileFieldSerializer to handle pre-uploaded files from /upload-tmp-media/
    """
    file = FileFieldSerializer()
    class Meta:
        model = TransactionReceipt
        fields = ['id', 'file', 'description', 'uploaded_at']
        read_only_fields = ['id', 'uploaded_at']
 class UploadReceiptsSerializer(serializers.Serializer):
    """
    Serializer for uploading multiple receipt files for a transaction.
    Files should be pre-uploaded using /upload-tmp-media/ endpoint,
    then their URLs should be sent here.
    """
    files = serializers.ListField(
        child=FileFieldSerializer(),
        allow_empty=False,
        max_length=10,
        help_text="List of file URLs (max 10 files) - files should be pre-uploaded via /upload-tmp-media/"
    )
    description = serializers.CharField(
        required=False,
        allow_blank=True,
        max_length=1000,
        help_text="Optional description for the receipts"
    )
    def validate_files(self, files):
        """
        Validate uploaded file URLs
        """
        if len(files) > 10:
            raise serializers.ValidationError("You can upload a maximum of 10 files.")
        return files
--- a/apps/transaction/urls.py
+++ b/apps/transaction/urls.py
@ -9,7 +9,8 @@ urlpatterns = [
    path('<slug:slug>/join/', views.TransactionParticipantCreateView.as_view(), name='transaction-participant-create'),
    path('list/', views.TransactiontListView.as_view(), name='transaction-list'),
    path('<int:pk>/delete/', views.SoftDeleteTransactionParticipantView.as_view(), name='soft-delete-transaction-participant'),
    path('<int:transaction_id>/receipts/upload/', views.UploadTransactionReceiptsView.as_view(), name='upload-transaction-receipts'),
    path('<int:transaction_id>/receipts/', views.TransactionReceiptsListView.as_view(), name='transaction-receipts-list'),
 ]
--- a/apps/transaction/views.py
+++ b/apps/transaction/views.py
@ -3,12 +3,23 @@ from rest_framework.permissions import IsAuthenticated
 from rest_framework.response import Response
 from rest_framework.views import APIView
 from apps.course.models import Participant, Course
 from apps.transaction.models import TransactionParticipant
 from apps.transaction.serializers import TransactionParticipantSerializer, TransactionListSerializer
 from apps.transaction.models import TransactionParticipant, TransactionReceipt
 from apps.transaction.serializers import (
    TransactionParticipantSerializer,
    TransactionListSerializer,
    UploadReceiptsSerializer,
    TransactionReceiptSerializer
 )
 from utils.exceptions import AppAPIException
 from apps.account.models import User
 from drf_yasg.utils import swagger_auto_schema
 from drf_yasg import openapi
 from apps.transaction.doc import (
    doc_upload_transaction_receipts,
    doc_list_transaction_receipts,
    doc_transaction_list,
    doc_create_transaction
 )
@ -17,7 +28,9 @@ class TransactionParticipantCreateView(generics.CreateAPIView):
    serializer_class = TransactionParticipantSerializer
    permission_classes = [IsAuthenticated]
    @swagger_auto_schema(
        operation_description=doc_create_transaction()
    )
    def create(self, request, *args, **kwargs):        
        user = request.user
        course_slug = self.kwargs.get('slug')  # Get the slug from the URL
@ -65,11 +78,13 @@ class TransactionParticipantCreateView(generics.CreateAPIView):
 class TransactiontListView(generics.ListAPIView):
    queryset = TransactionParticipant.objects.all()  # یا هر فیلتر که بخواهید اضافه کنید
    queryset = TransactionParticipant.objects.all()
    serializer_class = TransactionListSerializer
    permission_classes = [IsAuthenticated]  # برای دسترسی کاربران احراز هویت شده
    permission_classes = [IsAuthenticated]
    @swagger_auto_schema(
        operation_description=doc_transaction_list()
    )
    def get_queryset(self):
        queryset = super().get_queryset()
        queryset = queryset.filter(user=self.request.user, is_deleted=False)
@ -79,16 +94,16 @@ class TransactiontListView(generics.ListAPIView):
 class SoftDeleteTransactionParticipantView(APIView):
    permission_classes = [IsAuthenticated]
    @swagger_auto_schema(
        operation_summary="Soft delete a transaction participant",
        operation_description="Marks a transaction participant as deleted without removing it from the database",
        manual_parameters=[
            openapi.Parameter(
                'id', 
                openapi.IN_PATH, 
                description="Transaction Participant ID", 
                type=openapi.TYPE_INTEGER, 
                'id',
                openapi.IN_PATH,
                description="Transaction Participant ID",
                type=openapi.TYPE_INTEGER,
                required=True
            )
        ],
@ -121,6 +136,132 @@ class SoftDeleteTransactionParticipantView(APIView):
                    detail={'message': "You don't have permission to delete this transaction"},
                    status_code=status.HTTP_403_FORBIDDEN
                )
        except TransactionParticipant.DoesNotExist:
            raise AppAPIException({'message': "Transaction participant not found"})
 class UploadTransactionReceiptsView(APIView):
    permission_classes = [IsAuthenticated]
    @swagger_auto_schema(
        operation_summary="Upload payment receipts for a transaction",
        operation_description=doc_upload_transaction_receipts(),
        request_body=UploadReceiptsSerializer,
        responses={
            201: openapi.Response(
                description="Receipts uploaded successfully",
                examples={
                    "application/json": {
                        "success": True,
                        "message": "Receipts uploaded successfully",
                        "transaction_status": "waiting_approval",
                        "receipts": [
                            {
                                "id": 1,
                                "file": "http://example.com/media/receipts/1/receipt.jpg",
                                "description": "Payment receipt",
                                "uploaded_at": "2025-12-03T10:30:00Z"
                            }
                        ]
                    }
                }
            ),
            400: "Invalid data or transaction cannot accept receipts",
            403: "Permission denied",
            404: "Transaction not found"
        }
    )
    def post(self, request, transaction_id):
        try:
            transaction = TransactionParticipant.objects.get(pk=transaction_id, is_deleted=False)
        except TransactionParticipant.DoesNotExist:
            raise AppAPIException({'message': "Transaction not found"})
        # Check if user owns this transaction
        if transaction.user != request.user:
            raise AppAPIException(
                detail={'message': "You don't have permission to upload receipts for this transaction"},
                status_code=status.HTTP_403_FORBIDDEN
            )
        # Check if transaction is in a state that can accept receipts
        if transaction.status not in [
            TransactionParticipant.TransactionStatus.PENDING,
            TransactionParticipant.TransactionStatus.WAITING_APPROVAL
        ]:
            raise AppAPIException(
                detail={'message': f"Cannot upload receipts for transaction with status '{transaction.status}'"},
                status_code=status.HTTP_400_BAD_REQUEST
            )
        # Validate using serializer
        serializer = UploadReceiptsSerializer(data=request.data, context={'request': request})
        serializer.is_valid(raise_exception=True)
        # Create receipt records
        receipts = []
        description = serializer.validated_data.get('description', '')
        file_urls = serializer.validated_data.get('files', [])
        for file_url in file_urls:
            receipt = TransactionReceipt.objects.create(
                transaction=transaction,
                file=file_url,
                description=description
            )
            receipts.append(receipt)
        # Update transaction status to waiting_approval
        transaction.status = TransactionParticipant.TransactionStatus.WAITING_APPROVAL
        transaction.save()
        # Serialize receipts for response
        receipts_data = TransactionReceiptSerializer(receipts, many=True, context={'request': request}).data
        return Response({
            'success': True,
            'message': 'Receipts uploaded successfully',
            'transaction_status': transaction.status,
            'receipts': receipts_data
        }, status=status.HTTP_201_CREATED)
 class TransactionReceiptsListView(generics.ListAPIView):
    serializer_class = TransactionReceiptSerializer
    permission_classes = [IsAuthenticated]
    @swagger_auto_schema(
        operation_summary="List receipts for a transaction",
        operation_description=doc_list_transaction_receipts(),
        manual_parameters=[
            openapi.Parameter(
                'transaction_id',
                openapi.IN_PATH,
                description="Transaction ID",
                type=openapi.TYPE_INTEGER,
                required=True
            )
        ],
        responses={
            200: TransactionReceiptSerializer(many=True),
            403: "Permission denied",
            404: "Transaction not found"
        }
    )
    def get_queryset(self):
        transaction_id = self.kwargs.get('transaction_id')
        try:
            transaction = TransactionParticipant.objects.get(pk=transaction_id, is_deleted=False)
        except TransactionParticipant.DoesNotExist:
            raise AppAPIException({'message': "Transaction not found"})
        # Check if user owns this transaction
        if transaction.user != self.request.user:
            raise AppAPIException(
                detail={'message': "You don't have permission to view receipts for this transaction"},
                status_code=status.HTTP_403_FORBIDDEN
            )
        return TransactionReceipt.objects.filter(transaction=transaction)
--- a/templates/docs.html
+++ b/templates/docs.html
@ -64,6 +64,85 @@
                    </div>
                </div>
            </div>
            <div class="col-12">
                <div class="card">
                    <div class="card-header bg-light header-elements-inline">
                        مستندات API تراکنش‌ها و رسیدهای پرداخت
                    </div>
                    <div class="card-body">
                        <h4>🔹 ثبت‌نام در دوره و ایجاد تراکنش</h4>
                        <p><strong>Endpoint:</strong> <code>POST /api/transactions/&lt;slug&gt;/join/</code></p>
                        <p>این API برای ثبت‌نام کاربر در دوره و ایجاد تراکنش استفاده می‌شود.</p>
                        <ul>
                            <li>برای دوره‌های رایگان، تراکنش به صورت خودکار تایید می‌شود</li>
                            <li>برای دوره‌های پولی، تراکنش با وضعیت <code>pending</code> ایجاد می‌شود</li>
                        </ul>
                        <hr>
                        <h4>🔹 آپلود رسید پرداخت</h4>
                        <p><strong>Endpoint:</strong> <code>POST /api/transactions/&lt;transaction_id&gt;/receipts/upload/</code></p>
                        <p>برای آپلود رسید پرداخت دوره‌های پولی استفاده می‌شود.</p>
                        <ul>
                            <li>حداکثر 10 فایل قابل آپلود در هر درخواست</li>
                            <li>حداکثر حجم هر فایل: 10 مگابایت</li>
                            <li>پس از آپلود موفق، وضعیت تراکنش به <code>waiting_approval</code> تغییر می‌کند</li>
                        </ul>
                        <hr>
                        <h4>🔹 مشاهده رسیدهای یک تراکنش</h4>
                        <p><strong>Endpoint:</strong> <code>GET /api/transactions/&lt;transaction_id&gt;/receipts/</code></p>
                        <p>برای دریافت لیست تمام رسیدهای آپلود شده برای یک تراکنش.</p>
                        <hr>
                        <h4>🔹 لیست تراکنش‌های کاربر</h4>
                        <p><strong>Endpoint:</strong> <code>GET /api/transactions/list/</code></p>
                        <p>برای دریافت لیست تمام تراکنش‌های کاربر احراز هویت شده.</p>
                        <hr>
                        <h4>🔹 وضعیت‌های تراکنش</h4>
                        <table class="table table-bordered">
                            <thead>
                                <tr>
                                    <th>وضعیت</th>
                                    <th>توضیحات</th>
                                </tr>
                            </thead>
                            <tbody>
                                <tr>
                                    <td><span class="badge badge-warning">pending</span></td>
                                    <td>در انتظار پرداخت - کاربر باید رسید را آپلود کند</td>
                                </tr>
                                <tr>
                                    <td><span class="badge badge-info">waiting_approval</span></td>
                                    <td>در انتظار تایید - رسید آپلود شده و منتظر تایید ادمین</td>
                                </tr>
                                <tr>
                                    <td><span class="badge badge-success">success</span></td>
                                    <td>پرداخت موفق و تایید شده - کاربر به دوره دسترسی دارد</td>
                                </tr>
                                <tr>
                                    <td><span class="badge badge-danger">failed</span></td>
                                    <td>پرداخت ناموفق یا رد شده</td>
                                </tr>
                            </tbody>
                        </table>
                        <hr>
                        <h4>📌 نکات مهم برای ادمین</h4>
                        <ul>
                            <li>زمانی که کاربر رسید آپلود می‌کند، وضعیت تراکنش به <code>waiting_approval</code> تغییر می‌کند</li>
                            <li>ادمین باید رسیدها را در پنل ادمین بررسی کرده و وضعیت را به <code>success</code> یا <code>failed</code> تغییر دهد</li>
                            <li>زمانی که وضعیت به <code>success</code> تغییر کند، کاربر به صورت خودکار به عنوان دانشجو در دوره ثبت می‌شود</li>
                            <li>تمام رسیدهای آپلود شده در پنل ادمین قابل مشاهده هستند</li>
                        </ul>
                        <p class="mt-3">
                            <a href="/swagger/" target="_blank" class="btn btn-primary">مشاهده مستندات کامل Swagger</a>
                        </p>
                    </div>
                </div>
            </div>
        </div>
    </div>
 {% endblock %}