{
    "openapi": "3.0.0",
    "info": {
        "title": "Flashcard App API",
        "description": "API documentation for Flashcard App",
        "contact": {
            "email": "admin@example.com"
        },
        "version": "1.0.0"
    },
    "servers": [
        {
            "url": "/api",
            "description": "API Server"
        }
    ],
    "paths": {
        "/auth/login-otp": {
            "post": {
                "tags": [
                    "Authentication"
                ],
                "summary": "درخواست OTP برای ورود",
                "description": "کد OTP را برای شماره تلفن درخواست کنید",
                "operationId": "requestOTP",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "phone_number"
                                ],
                                "properties": {
                                    "phone_number": {
                                        "description": "شماره تلفن کاربر",
                                        "type": "string",
                                        "example": "09363667756"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "کد OTP با موفقیت ارسال شد",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "status": {
                                            "type": "string",
                                            "example": "success"
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "OTP sent successfully (Use 123456 for dev)"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "اعتبارسنجی ناموفق"
                    }
                }
            }
        },
        "/auth/verify-otp": {
            "post": {
                "tags": [
                    "Authentication"
                ],
                "summary": "تایید کد OTP",
                "description": "کد OTP را تایید کنید و توکن احراز هویت دریافت کنید",
                "operationId": "verifyOTP",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "phone_number",
                                    "otp"
                                ],
                                "properties": {
                                    "phone_number": {
                                        "description": "شماره تلفن کاربر",
                                        "type": "string",
                                        "example": "09363667756"
                                    },
                                    "otp": {
                                        "description": "کد OTP دریافت شده",
                                        "type": "string",
                                        "example": "123456"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "ورود موفق - توکن احراز هویت دریافت شد",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "status": {
                                            "type": "string",
                                            "example": "success"
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Logged in successfully"
                                        },
                                        "data": {
                                            "properties": {
                                                "user": {
                                                    "properties": {
                                                        "id": {
                                                            "type": "integer"
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        },
                                                        "phone_number": {
                                                            "type": "string"
                                                        },
                                                        "created_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    },
                                                    "type": "object"
                                                },
                                                "token": {
                                                    "description": "Bearer token برای درخواست‌های بعدی",
                                                    "type": "string"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "کد OTP غلط",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "status": {
                                            "type": "string",
                                            "example": "error"
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Invalid OTP"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "اعتبارسنجی ناموفق"
                    }
                }
            }
        },
        "/auth/logout": {
            "post": {
                "tags": [
                    "Authentication"
                ],
                "summary": "خروج از سیستم",
                "description": "توکن احراز هویت فعلی را ابطال کنید",
                "operationId": "apiLogout",
                "responses": {
                    "200": {
                        "description": "خروج موفق",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "status": {
                                            "type": "string",
                                            "example": "success"
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Logged out successfully"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "توکن معتبر نیست"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/flashcards": {
            "get": {
                "tags": [
                    "Flashcards"
                ],
                "summary": "لیست فلش کارت‌ها",
                "description": "تمام فلش کارت‌های موجود را با صفحه‌بندی دریافت کنید",
                "operationId": "listFlashcards",
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "description": "شماره صفحه",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "لیست فلش کارت‌ها",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "status": {
                                            "type": "string",
                                            "example": "success"
                                        },
                                        "data": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "توکن معتبر نیست"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/flashcards/{id}": {
            "get": {
                "tags": [
                    "Flashcards"
                ],
                "summary": "نمایش جزئیات یک فلش کارت",
                "operationId": "showFlashcard",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "شناسه فلش کارت",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "جزئیات فلش کارت"
                    },
                    "404": {
                        "description": "فلش کارت یافت نشد"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/flashcards/category/{categoryId}": {
            "get": {
                "tags": [
                    "Flashcards"
                ],
                "summary": "فلش کارت‌های یک دسته",
                "description": "فلش کارت‌های مربوط به یک دسته خاص را دریافت کنید",
                "operationId": "flashcardsByCategory",
                "parameters": [
                    {
                        "name": "categoryId",
                        "in": "path",
                        "description": "شناسه دسته",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "فلش کارت‌های دسته"
                    },
                    "403": {
                        "description": "دسترسی رد شد - نیاز به خریدن دسته دارید"
                    },
                    "404": {
                        "description": "دسته یافت نشد"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/flashcards/leitner/due": {
            "get": {
                "tags": [
                    "Leitner System"
                ],
                "summary": "کارت‌های سررسید برای بررسی",
                "description": "کارت‌هایی را که برای بررسی مجدد سررسید هستند دریافت کنید",
                "operationId": "leitnerDue",
                "responses": {
                    "200": {
                        "description": "کارت‌های سررسید"
                    },
                    "401": {
                        "description": "توکن معتبر نیست"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/flashcards/{id}/leitner-action": {
            "post": {
                "tags": [
                    "Leitner System"
                ],
                "summary": "عملیات سیستم Leitner",
                "description": "نتیجه پاسخ به یک کارت در سیستم Leitner را ثبت کنید",
                "operationId": "leitnerAction",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "شناسه فلش کارت",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "action"
                                ],
                                "properties": {
                                    "action": {
                                        "description": "نتیجه (صحیح یا غلط)",
                                        "type": "string",
                                        "enum": [
                                            "correct",
                                            "incorrect"
                                        ],
                                        "example": "correct"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "عملیات با موفقیت انجام شد"
                    },
                    "422": {
                        "description": "اعتبارسنجی ناموفق"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/flashcards/user/stats/{id}": {
            "get": {
                "tags": [
                    "Flashcards"
                ],
                "summary": "آمار کاربر برای یک کارت",
                "description": "آمار کاربر برای یک فلش کارت خاص در سیستم Leitner",
                "operationId": "userCardStats",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "شناسه فلش کارت",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "آمار کاربر"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/flashcards/quiz/start": {
            "post": {
                "tags": [
                    "Quiz"
                ],
                "summary": "شروع یک امتحان",
                "description": "تعداد مشخصی از فلش کارت‌ها را برای امتحان دریافت کنید",
                "operationId": "startQuiz",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "count": {
                                        "description": "تعداد کارت‌ها (پیشفرض: 10)",
                                        "type": "integer",
                                        "example": 10
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "فلش کارت‌های امتحان"
                    },
                    "401": {
                        "description": "توکن معتبر نیست"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/flashcards/quiz/submit": {
            "post": {
                "tags": [
                    "Quiz"
                ],
                "summary": "ارسال نتایج امتحان",
                "description": "نتایج امتحان را ثبت کنید و امتیازات کاربر را به‌روزرسانی کنید",
                "operationId": "submitQuiz",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "total_questions",
                                    "correct_answers"
                                ],
                                "properties": {
                                    "total_questions": {
                                        "description": "تعداد کل سوالات",
                                        "type": "integer",
                                        "example": 10
                                    },
                                    "correct_answers": {
                                        "description": "تعداد پاسخ‌های صحیح",
                                        "type": "integer",
                                        "example": 8
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "نتایج امتحان ثبت شد"
                    },
                    "422": {
                        "description": "اعتبارسنجی ناموفق"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/flashcards/quiz/results": {
            "get": {
                "tags": [
                    "Quiz"
                ],
                "summary": "نتایج امتحان‌های کاربر",
                "description": "تمام نتایج امتحان‌های شما را مشاهده کنید",
                "operationId": "quizResults",
                "responses": {
                    "200": {
                        "description": "نتایج امتحان‌ها"
                    },
                    "401": {
                        "description": "توکن معتبر نیست"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/flashcards/categories": {
            "get": {
                "tags": [
                    "Categories"
                ],
                "summary": "لیست دسته‌بندی‌ها",
                "description": "تمام دسته‌بندی‌های موجود را با تعداد فلش کارت‌ها دریافت کنید",
                "operationId": "listCategories",
                "responses": {
                    "200": {
                        "description": "لیست دسته‌بندی‌ها"
                    },
                    "401": {
                        "description": "توکن معتبر نیست"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/flashcards/categories/{id}": {
            "get": {
                "tags": [
                    "Categories"
                ],
                "summary": "جزئیات یک دسته‌بندی",
                "description": "جزئیات و فلش کارت‌های یک دسته‌بندی را مشاهده کنید",
                "operationId": "categoryDetails",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "شناسه دسته",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "جزئیات دسته‌بندی"
                    },
                    "404": {
                        "description": "دسته یافت نشد"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/flashcards/suggest": {
            "post": {
                "tags": [
                    "Flashcards"
                ],
                "summary": "پیشنهاد فلش کارت جدید",
                "description": "کاربران می‌توانند فلش کارت جدید پیشنهاد دهند",
                "operationId": "suggestFlashcard",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "category_id",
                                    "question",
                                    "answer"
                                ],
                                "properties": {
                                    "category_id": {
                                        "description": "شناسه دسته",
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "question": {
                                        "description": "سوال",
                                        "type": "string",
                                        "example": "سرایندهٔ سرود ملی است؟"
                                    },
                                    "answer": {
                                        "description": "جواب",
                                        "type": "string",
                                        "example": "میرزا حسن رسولی"
                                    },
                                    "difficulty": {
                                        "description": "سطح دشواری",
                                        "type": "string",
                                        "enum": [
                                            "easy",
                                            "medium",
                                            "hard"
                                        ],
                                        "example": "medium"
                                    },
                                    "hint": {
                                        "description": "راهنمایی",
                                        "type": "string",
                                        "example": "یک سیاستمدار و شاعر ایرانی"
                                    },
                                    "tags": {
                                        "description": "برچسب‌ها",
                                        "type": "string",
                                        "example": "ملی,سرود"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "فلش کارت با موفقیت ثبت شد"
                    },
                    "422": {
                        "description": "اعتبارسنجی ناموفق"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/user/profile": {
            "get": {
                "tags": [
                    "User"
                ],
                "summary": "پروفایل کاربر",
                "description": "اطلاعات پروفایل کاربر فعلی را دریافت کنید",
                "operationId": "getUserProfile",
                "responses": {
                    "200": {
                        "description": "اطلاعات پروفایل",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "status": {
                                            "type": "string",
                                            "example": "success"
                                        },
                                        "data": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "توکن معتبر نیست"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "patch": {
                "tags": [
                    "User"
                ],
                "summary": "بروزرسانی پروفایل",
                "description": "اطلاعات پروفایل کاربر را بروزرسانی کنید",
                "operationId": "updateUserProfile",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "example": "احمد محمدی"
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "example": "ahmad@example.com"
                                    },
                                    "profile_image": {
                                        "type": "string",
                                        "example": "https://example.com/image.jpg"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "پروفایل بروزرسانی شد"
                    },
                    "422": {
                        "description": "اعتبارسنجی ناموفق"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/user/stats": {
            "get": {
                "tags": [
                    "User"
                ],
                "summary": "آمار کاربر",
                "description": "امتیازات، رتبه و آمار یادگیری کاربر را دریافت کنید",
                "operationId": "getUserStats",
                "responses": {
                    "200": {
                        "description": "آمار کاربر",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "status": {
                                            "type": "string",
                                            "example": "success"
                                        },
                                        "data": {
                                            "properties": {
                                                "score": {
                                                    "type": "integer",
                                                    "example": 1250
                                                },
                                                "rank": {
                                                    "type": "integer",
                                                    "example": 5
                                                },
                                                "leitner_cards_count": {
                                                    "type": "integer",
                                                    "example": 45
                                                },
                                                "completed_quizzes": {
                                                    "type": "integer",
                                                    "example": 12
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "توکن معتبر نیست"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/user/leaderboard": {
            "get": {
                "tags": [
                    "User"
                ],
                "summary": "جدول رتبه‌بندی",
                "description": "20 کاربر برتر بر اساس امتیازات را دریافت کنید",
                "operationId": "getLeaderboard",
                "responses": {
                    "200": {
                        "description": "جدول رتبه‌بندی"
                    },
                    "401": {
                        "description": "توکن معتبر نیست"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/user/scores": {
            "get": {
                "tags": [
                    "User"
                ],
                "summary": "نتایج امتیازات کاربر",
                "description": "تمام نتایج امتیازات کاربر را مشاهده کنید",
                "operationId": "getUserScores",
                "responses": {
                    "200": {
                        "description": "نتایج امتیازات"
                    },
                    "401": {
                        "description": "توکن معتبر نیست"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/user/tickets": {
            "get": {
                "tags": [
                    "Support"
                ],
                "summary": "تیکت‌های کاربر",
                "description": "تمام تیکت‌های پشتیبانی کاربر را مشاهده کنید",
                "operationId": "userTickets",
                "responses": {
                    "200": {
                        "description": "لیست تیکت‌ها"
                    },
                    "401": {
                        "description": "توکن معتبر نیست"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Support"
                ],
                "summary": "ایجاد تیکت جدید",
                "description": "تیکت پشتیبانی جدید ایجاد کنید",
                "operationId": "createUserTicket",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "subject",
                                    "priority",
                                    "department",
                                    "message"
                                ],
                                "properties": {
                                    "subject": {
                                        "type": "string",
                                        "example": "مشکل در ورود"
                                    },
                                    "priority": {
                                        "type": "string",
                                        "enum": [
                                            "low",
                                            "medium",
                                            "high"
                                        ],
                                        "example": "high"
                                    },
                                    "department": {
                                        "type": "string",
                                        "example": "فنی"
                                    },
                                    "message": {
                                        "type": "string",
                                        "example": "نمی‌توانم وارد اپلیکیشن شوم"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "تیکت ایجاد شد"
                    },
                    "422": {
                        "description": "اعتبارسنجی ناموفق"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/user/tickets/{id}": {
            "get": {
                "tags": [
                    "Support"
                ],
                "summary": "مشاهده جزئیات تیکت",
                "description": "جزئیات یک تیکت و پیام‌های آن را مشاهده کنید",
                "operationId": "showUserTicket",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "شناسه تیکت",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "جزئیات تیکت"
                    },
                    "404": {
                        "description": "تیکت یافت نشد"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/user/tickets/{id}/message": {
            "post": {
                "tags": [
                    "Support"
                ],
                "summary": "افزودن پیام به تیکت",
                "description": "پیام جدید به تیکت پشتیبانی اضافه کنید",
                "operationId": "addUserTicketMessage",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "شناسه تیکت",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "message"
                                ],
                                "properties": {
                                    "message": {
                                        "type": "string",
                                        "example": "لطفا پاسخ بدهید"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "پیام ارسال شد"
                    },
                    "404": {
                        "description": "تیکت یافت نشد"
                    },
                    "422": {
                        "description": "اعتبارسنجی ناموفق"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        }
    },
    "tags": [
        {
            "name": "Authentication",
            "description": "Authentication"
        },
        {
            "name": "Flashcards",
            "description": "Flashcards"
        },
        {
            "name": "Leitner System",
            "description": "Leitner System"
        },
        {
            "name": "Quiz",
            "description": "Quiz"
        },
        {
            "name": "Categories",
            "description": "Categories"
        },
        {
            "name": "User",
            "description": "User"
        },
        {
            "name": "Support",
            "description": "Support"
        }
    ]
}