ATP - استعلام اعتبار باقی‌مانده AvalAI (GET /api/v1/credit)

Endpoint

GET /api/v1/credit

هدف آزمون

خواندن موجودی اعتبار AvalAI از مسیر HTTP همزمان برای نمایش به کاربر در core-api.

شرایط آزمون

• سرویس ai-workflow در حال اجرا باشد
• AVALAI_API_KEY تنظیم شده باشد
• نیازی به احراز هویت در این سرویس نیست؛ احراز هویت کاربر در core-api انجام می‌شود

فرآیند آزمون

1. ارسال درخواست GET به /api/v1/credit
2. ai-workflow با Bearer token به GET https://api.avalai.ir/user/v1/credit درخواست می‌زند
3. دریافت JSON با remaining_unit، remaining_irt، exchange_rate و credit_sources

معرفی ویژگی

استثنای محصول HTTP: موجودی اعتبار lookup ارزان و فوری است، پس روی RabbitMQ نمی‌رود. core-api این endpoint را صدا می‌زند و ai-workflow کلید AvalAI را نگه می‌دارد. خود این فراخوانی User API صورتحساب ندارد؛ مصرف مدل/جستجو از این موجودی کم می‌شود.

• مسیر محصول HTTP: GET /api/v1/credit؛ صف یا رویداد ندارد
• کلید فقط در ai-workflow: مرورگر و core-api کلید AvalAI را نمی‌بینند
• remaining_unit: اعتبار باقی‌مانده به دلار (UNIT)
• remaining_irt: موجودی کیف تومان/IRT (ممکن است صفر باشد اگر اعتبار به UNIT باشد)
• بدون صورتحساب lookup: User API اعتبار را کم نمی‌کند

سناریوی آزمون

سناریو 1: مسیر موفق — موجودی برگردانده شد

1. ارسال GET /api/v1/credit
2. دریافت کد 200
3. بررسی provider: "avalai"
4. بررسی وجود remaining_unit، remaining_irt، total_unit و exchange_rate

سناریو 2: خطا — کلید AvalAI تنظیم نشده

1. اجرای سرویس بدون AVALAI_API_KEY
2. ارسال GET /api/v1/credit
3. دریافت کد 503 با پیام AVALAI_API_KEY is not configured

سناریو 3: خطا — AvalAI در دسترس نیست

1. شبیه‌سازی خطای شبکه یا HTTP 5xx از AvalAI
2. ارسال GET /api/v1/credit
3. دریافت کد 502 با پیام AvalAI credit lookup failed
4. بدنه خطا نباید ایمیل پشتیبانی یا کلید API را فاش کند

سناریو 4: متد پشتیبانی‌نشده

1. ارسال POST /api/v1/credit
2. دریافت کد 405
3. بررسی وجود پاسخ استاندارد Method Not Allowed

قالب API

Swagger

get:
  summary: Read remaining AvalAI prepaid credit
  responses:
    200:
      description: Remaining credit returned
    429:
      description: AvalAI User API rate-limited
    502:
      description: AvalAI credit lookup failed
    503:
      description: AVALAI_API_KEY is not configured

نمونه ورودی

curl -X GET "http://127.0.0.1:8000/api/v1/credit" \
  -H "Accept: application/json"

نمونه خروجی

{
  "provider": "avalai",
  "remaining_unit": 87.3996155,
  "remaining_irt": 0.0,
  "total_unit": 87.3996155,
  "limit": 0.0,
  "exchange_rate": 198150,
  "account_tier": 4,
  "credit_sources": { "grants": [], "packages": [] }
}

Status Codes

• 200: موجودی اعتبار برگردانده شد
• 429: محدودیت نرخ User API AvalAI
• 502: AvalAI پاسخ نامعتبر یا در دسترس نبود
• 503: AVALAI_API_KEY تنظیم نشده

نتیجه مورد انتظار

پاسخ JSON با provider=avalai و فیلدهای remaining_unit، remaining_irt، total_unit، limit، exchange_rate، account_tier و credit_sources با کد HTTP 200.

روال صحت‌سنجی

1. بررسی کد وضعیت 200
2. بررسی فیلد provider برابر "avalai"
3. بررسی remaining_unit عددی و غیرمنفی
4. بررسی credit_sources شامل grants و packages

توضیحات

• مسیر محصول استخراج/پیشینه/پیش‌نویس همچنان رویدادمحور است؛ فقط اعتبار HTTP است
• core-api باید این فراخوانی را پشت RBAC کاربر پروکسی کند؛ این سرویس auth ندارد
• GET /user/v1/credit در AvalAI صورتحساب ندارد