{
  "openapi": "3.0.0",
  "info": {
    "title": "Flash Card Learning API",
    "description": "API for Flash Card Learning Application - فلش کارت یادگیری",
    "version": "1.0.0",
    "contact": {
      "name": "Support Team",
      "url": "http://vtj.ir"
    },
    "license": {
      "name": "MIT"
    }
  },
  "servers": [
    {
      "url": "http://vtj.ir/api",
      "description": "Production API"
    },
    {
      "url": "http://localhost/flash/api",
      "description": "Local Development API"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "token"
      }
    },
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 1
          },
          "name": {
            "type": "string",
            "example": "احمد محمدی"
          },
          "phone_number": {
            "type": "string",
            "example": "989123456789"
          },
          "email": {
            "type": "string",
            "example": "ahmad@example.com"
          },
          "score": {
            "type": "integer",
            "example": 1250
          },
          "rank": {
            "type": "integer",
            "example": 5
          },
          "wallet_balance": {
            "type": "number",
            "example": 500000
          },
          "profile_image": {
            "type": "string",
            "nullable": true
          },
          "is_active": {
            "type": "boolean",
            "example": true
          },
          "is_blocked": {
            "type": "boolean",
            "example": false
          },
          "last_login": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Category": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "category_id": {
            "type": "string",
            "example": "CAT-english-abc123"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "price": {
            "type": "number",
            "example": 0
          },
          "icon": {
            "type": "string",
            "example": "fas fa-globe"
          },
          "color": {
            "type": "string",
            "example": "#3498db"
          },
          "level": {
            "type": "string",
            "enum": ["beginner", "intermediate", "advanced"]
          },
          "type": {
            "type": "string",
            "enum": ["flashcard", "book"]
          },
          "flashcards_count": {
            "type": "integer"
          },
          "books_count": {
            "type": "integer"
          },
          "purchased": {
            "type": "boolean"
          }
        }
      },
      "Flashcard": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "category_id": {
            "type": "integer"
          },
          "question": {
            "type": "string"
          },
          "question_image_url": {
            "type": "string",
            "nullable": true
          },
          "question_video_url": {
            "type": "string",
            "nullable": true
          },
          "answer": {
            "type": "string"
          },
          "answer_image_url": {
            "type": "string",
            "nullable": true
          },
          "answer_video_url": {
            "type": "string",
            "nullable": true
          },
          "difficulty": {
            "type": "string",
            "enum": ["easy", "medium", "hard"]
          },
          "hint": {
            "type": "string"
          },
          "tags": {
            "type": "string"
          },
          "views_count": {
            "type": "integer"
          }
        }
      },
      "Book": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "author": {
            "type": "string"
          },
          "publisher": {
            "type": "string"
          },
          "isbn": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "category_id": {
            "type": "integer"
          },
          "price": {
            "type": "number"
          },
          "total_pages": {
            "type": "integer"
          },
          "cover_image_url": {
            "type": "string",
            "nullable": true
          },
          "pdf_url": {
            "type": "string",
            "nullable": true
          },
          "epub_url": {
            "type": "string",
            "nullable": true
          },
          "views_count": {
            "type": "integer"
          },
          "downloads_count": {
            "type": "integer"
          },
          "accessible": {
            "type": "boolean"
          }
        }
      },
      "Ticket": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "subject": {
            "type": "string"
          },
          "priority": {
            "type": "string",
            "enum": ["low", "medium", "high"]
          },
          "department": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["open", "in_progress", "closed"]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Score": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "user_id": {
            "type": "integer"
          },
          "activity_type": {
            "type": "string",
            "example": "quiz_completed"
          },
          "score_change": {
            "type": "integer"
          },
          "total_score": {
            "type": "integer"
          },
          "description": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "error"
          },
          "message": {
            "type": "string"
          },
          "code": {
            "type": "string"
          }
        }
      }
    }
  },
  "paths": {
    "/auth/login-otp": {
      "post": {
        "tags": ["Authentication"],
        "summary": "درخواست OTP",
        "description": "کد OTP را برای شماره تماس درخواست کنید",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "phone_number": {
                    "type": "string",
                    "example": "989123456789"
                  }
                },
                "required": ["phone_number"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "کد OTP ارسال شد",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/auth/verify-otp": {
      "post": {
        "tags": ["Authentication"],
        "summary": "تأیید OTP",
        "description": "کد OTP را تأیید کرده و توکن دریافت کنید",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "phone_number": {
                    "type": "string",
                    "example": "989123456789"
                  },
                  "code": {
                    "type": "string",
                    "example": "123456"
                  }
                },
                "required": ["phone_number", "code"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "احراز هویت موفق",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "token": {
                          "type": "string"
                        },
                        "user": {
                          "$ref": "#/components/schemas/User"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "کد OTP نادرست",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/auth/logout": {
      "post": {
        "tags": ["Authentication"],
        "summary": "خروج از حساب",
        "security": [{"bearerAuth": []}],
        "responses": {
          "200": {
            "description": "با موفقیت خارج شدید"
          }
        }
      }
    },
    "/user/profile": {
      "get": {
        "tags": ["User"],
        "summary": "دریافت پروفایل کاربر",
        "security": [{"bearerAuth": []}],
        "responses": {
          "200": {
            "description": "اطلاعات پروفایل",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "data": {
                      "$ref": "#/components/schemas/User"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "توکن معتبر نیست"
          }
        }
      },
      "patch": {
        "tags": ["User"],
        "summary": "بروزرسانی پروفایل",
        "security": [{"bearerAuth": []}],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "profile_image": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "پروفایل بروزرسانی شد"
          },
          "422": {
            "description": "اعتبارسنجی ناموفق"
          }
        }
      }
    },
    "/user/stats": {
      "get": {
        "tags": ["User"],
        "summary": "آمار کاربر",
        "security": [{"bearerAuth": []}],
        "responses": {
          "200": {
            "description": "آمار کاربر",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "score": {
                          "type": "integer"
                        },
                        "rank": {
                          "type": "integer"
                        },
                        "leitner_cards_count": {
                          "type": "integer"
                        },
                        "completed_quizzes": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/user/leaderboard": {
      "get": {
        "tags": ["User"],
        "summary": "جدول رتبه‌بندی",
        "security": [{"bearerAuth": []}],
        "responses": {
          "200": {
            "description": "20 کاربر برتر",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer"
                          },
                          "name": {
                            "type": "string"
                          },
                          "score": {
                            "type": "integer"
                          },
                          "rank": {
                            "type": "integer"
                          },
                          "profile_image": {
                            "type": "string",
                            "nullable": true
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/user/scores": {
      "get": {
        "tags": ["User"],
        "summary": "سابقه امتیازات",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "سابقه امتیازات کاربر",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Score"
                          }
                        },
                        "current_page": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "per_page": {
                          "type": "integer"
                        },
                        "last_page": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/categories/flashcard": {
      "get": {
        "tags": ["Flashcard Categories"],
        "summary": "لیست دسته‌بندی فلش‌کارت",
        "security": [{"bearerAuth": []}],
        "responses": {
          "200": {
            "description": "لیست دسته‌بندی‌ها",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Category"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/categories/flashcard/{id}": {
      "get": {
        "tags": ["Flashcard Categories"],
        "summary": "جزئیات دسته‌بندی فلش‌کارت",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "جزئیات دسته و فلش‌کارت‌ها"
          },
          "403": {
            "description": "دسترسی رد شد"
          },
          "404": {
            "description": "دسته یافت نشد"
          }
        }
      }
    },
    "/flashcards": {
      "get": {
        "tags": ["Flashcards"],
        "summary": "لیست فلش‌کارت‌ها",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "لیست فلش‌کارت‌ها"
          }
        }
      }
    },
    "/flashcards/{id}": {
      "get": {
        "tags": ["Flashcards"],
        "summary": "جزئیات فلش‌کارت",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "جزئیات فلش‌کارت",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Flashcard"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/flashcards/{id}/question-image": {
      "get": {
        "tags": ["Flashcards"],
        "summary": "دانلود تصویر سؤال",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "تصویر سؤال",
            "content": {
              "image/jpeg": {}
            }
          }
        }
      }
    },
    "/flashcards/{id}/question-video": {
      "get": {
        "tags": ["Flashcards"],
        "summary": "دانلود ویدیو سؤال",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "ویدیو سؤال"
          }
        }
      }
    },
    "/flashcards/{id}/answer-image": {
      "get": {
        "tags": ["Flashcards"],
        "summary": "دانلود تصویر پاسخ",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "تصویر پاسخ"
          }
        }
      }
    },
    "/flashcards/{id}/answer-video": {
      "get": {
        "tags": ["Flashcards"],
        "summary": "دانلود ویدیو پاسخ",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "ویدیو پاسخ"
          }
        }
      }
    },
    "/categories/book": {
      "get": {
        "tags": ["Book Categories"],
        "summary": "لیست دسته‌بندی کتاب",
        "security": [{"bearerAuth": []}],
        "responses": {
          "200": {
            "description": "لیست دسته‌بندی‌های کتاب"
          }
        }
      }
    },
    "/categories/book/{id}": {
      "get": {
        "tags": ["Book Categories"],
        "summary": "جزئیات دسته‌بندی کتاب",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "جزئیات دسته و کتاب‌ها"
          }
        }
      }
    },
    "/books": {
      "get": {
        "tags": ["Books"],
        "summary": "لیست کتاب‌ها",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "لیست کتاب‌ها"
          }
        }
      }
    },
    "/books/{id}": {
      "get": {
        "tags": ["Books"],
        "summary": "جزئیات کتاب",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "جزئیات کتاب",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Book"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/books/{id}/cover": {
      "get": {
        "tags": ["Books"],
        "summary": "دانلود کاور کتاب",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "تصویر کاور"
          }
        }
      }
    },
    "/books/{id}/pdf": {
      "get": {
        "tags": ["Books"],
        "summary": "دانلود PDF کتاب",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "فایل PDF"
          }
        }
      }
    },
    "/books/{id}/epub": {
      "get": {
        "tags": ["Books"],
        "summary": "دانلود EPUB کتاب",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "فایل EPUB"
          }
        }
      }
    },
    "/books/{id}/progress": {
      "get": {
        "tags": ["Books"],
        "summary": "دریافت پیشرفت خواندن",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "پیشرفت خواندن"
          }
        }
      },
      "post": {
        "tags": ["Books"],
        "summary": "ذخیره پیشرفت خواندن",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "percentage": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100
                  },
                  "current_page": {
                    "type": "integer",
                    "nullable": true
                  },
                  "cfi": {
                    "type": "string",
                    "nullable": true
                  }
                },
                "required": ["percentage"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "پیشرفت ذخیره شد"
          }
        }
      }
    },
    "/wallet": {
      "get": {
        "tags": ["Wallet"],
        "summary": "موجودی کیف پول",
        "security": [{"bearerAuth": []}],
        "responses": {
          "200": {
            "description": "موجودی کیف پول",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "balance": {
                          "type": "number"
                        },
                        "currency": {
                          "type": "string",
                          "example": "Toman"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/wallet/transactions": {
      "get": {
        "tags": ["Wallet"],
        "summary": "تاریخچه تراکنش‌ها",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "لیست تراکنش‌ها"
          }
        }
      }
    },
    "/wallet/purchase": {
      "post": {
        "tags": ["Wallet"],
        "summary": "خریدن دسته‌بندی",
        "security": [{"bearerAuth": []}],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["category"]
                  },
                  "id": {
                    "type": "integer"
                  }
                },
                "required": ["type", "id"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "خرید موفق"
          },
          "400": {
            "description": "موجودی کافی نیست"
          }
        }
      }
    },
    "/user/tickets": {
      "get": {
        "tags": ["Support"],
        "summary": "لیست تیکت‌های کاربر",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "لیست تیکت‌ها"
          }
        }
      },
      "post": {
        "tags": ["Support"],
        "summary": "ایجاد تیکت جدید",
        "security": [{"bearerAuth": []}],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "subject": {
                    "type": "string"
                  },
                  "priority": {
                    "type": "string",
                    "enum": ["low", "medium", "high"]
                  },
                  "department": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  }
                },
                "required": ["subject", "priority", "department", "message"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "تیکت ایجاد شد"
          },
          "422": {
            "description": "اعتبارسنجی ناموفق"
          }
        }
      }
    },
    "/user/tickets/{id}": {
      "get": {
        "tags": ["Support"],
        "summary": "جزئیات تیکت",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "جزئیات تیکت با پیام‌ها"
          }
        }
      }
    },
    "/user/tickets/{id}/message": {
      "post": {
        "tags": ["Support"],
        "summary": "افزودن پیام به تیکت",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "message": {
                    "type": "string"
                  }
                },
                "required": ["message"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "پیام اضافه شد"
          }
        }
      }
    }
  }
}