# openapi.yaml
openapi: 3.0.0
info:
  title: Telegram Bot Management API
  version: 2.0.0
  description: |
    API مدیریت ربات تلگرام پیشرفته
    با سیستم دسترسی سلسله‌مراتبی و فوروارد هوشمند

servers:
  - url: https://api.yourdomain.com
    description: Production server
  - url: http://localhost:8000
    description: Development server

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  
  schemas:
    User:
      type: object
      properties:
        chat_id:
          type: integer
          description: شناسه چت تلگرام کاربر
          example: 123456789
        username:
          type: string
          nullable: true
          description: یوزرنیم تلگرام
          example: "username"
        first_name:
          type: string
          nullable: true
          description: نام کاربر
          example: "علی"
        last_name:
          type: string
          nullable: true
          description: نام خانوادگی کاربر
          example: "محمدی"
        daily_limit:
          type: integer
          description: سقف ارسال روزانه
          example: 50
        used_today:
          type: integer
          description: تعداد ارسال امروز
          example: 12
        is_active:
          type: boolean
          description: وضعیت فعال بودن
          example: true
        added_at:
          type: string
          format: date-time
          description: تاریخ اضافه شدن
    
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: شرح خطا
          example: "کاربر یافت نشد"

paths:
  /api/v1/users:
    get:
      summary: دریافت لیست کاربران
      security:
        - BearerAuth: []
      parameters:
        - name: skip
          in: query
          schema:
            type: integer
            minimum: 0
          description: تعداد رکوردهای رد شده
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
          description: تعداد رکوردهای بازگشتی
      responses:
        200:
          description: موفق
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        401:
          description: عدم احراز هویت
        403:
          description: دسترسی غیرمجاز
    
    post:
      summary: افزودن کاربر جدید
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - chat_id
                - actor_chatid
              properties:
                chat_id:
                  type: integer
                  description: شناسه چت کاربر جدید
                actor_chatid:
                  type: integer
                  description: شناسه چت درخواست دهنده
                username:
                  type: string
                  nullable: true
                first_name:
                  type: string
                  nullable: true
                last_name:
                  type: string
                  nullable: true
                daily_limit:
                  type: integer
                  minimum: 1
                  maximum: 1000
      responses:
        201:
          description: کاربر با موفقیت اضافه شد
        400:
          description: درخواست نامعتبر
        403:
          description: دسترسی غیرمجاز