API: Admin

Source: backend/app/routers/ai.py, backend/app/routers/import_export.py, backend/app/routers/websites.py

Endpoint khusus admin (role admin atau system_admin). Mencakup:

• AI question generation
• Import/export soal (Excel + JSON dari Sejoli Tryout)
• Manajemen website (multi-tenant)

AI Generation

Prefix: /api/v1/admin/ai

✅ POST /api/v1/admin/ai/generate-preview — Preview Generated Question

Implemented. Generate 1 soal via OpenRouter tanpa save ke DB (playground mode).

POST /api/v1/admin/ai/generate-preview
Authorization: Bearer {admin_token}
X-Website-ID: 1
Content-Type: application/json

{
  "basis_item_id": 42,
  "target_level": "mudah",
  "model": "qwen/qwen-2.5-32b-instruct",
  "operator_notes": "Gunakan bahasa informal untuk audiens SMA"
}

Response 200 OK:

{
  "generated": {
    "stem": "Berapa hasil dari 5 + 3?",
    "options": {"A": "7", "B": "8", "C": "9", "D": "10"},
    "correct": "B",
    "explanation": "5 + 3 = 8"
  },
  "usage": {
    "model": "qwen/qwen-2.5-32b-instruct",
    "prompt_tokens": 250,
    "completion_tokens": 80,
    "total_tokens": 330,
    "estimated_cost_usd": 0.0004
  }
}

✅ POST /api/v1/admin/ai/generate-save — Generate & Save

Implemented. Generate soal langsung simpan ke DB.

POST /api/v1/admin/ai/generate-save
Content-Type: application/json

{
  "basis_item_id": 42,
  "target_level": "mudah",
  "model": "qwen/qwen-2.5-32b-instruct"
}

Response 201 Created:

{
  "item_id": 102,
  "generated_by": "ai",
  "basis_item_id": 42,
  "generation_run_id": 15,
  "variant_status": "active"
}

✅ POST /api/v1/admin/ai/generate-batch — Batch Generate

Implemented. Generate beberapa varian sekaligus.

POST /api/v1/admin/ai/generate-batch
Content-Type: application/json

{
  "basis_item_ids": [42, 43, 44, 45],
  "target_levels": ["mudah", "sulit"],
  "model": "qwen/qwen-2.5-32b-instruct"
}

Response 200 OK:

{
  "generation_run_id": 16,
  "total_requested": 8,
  "succeeded": 7,
  "failed": 1,
  "errors": [{"basis_item_id": 45, "target_level": "mudah", "error": "OpenRouter timeout"}]
}

✅ GET /api/v1/admin/ai/stats — Usage Stats

Implemented. Statistik penggunaan AI per tryout / rentang tanggal.

✅ GET /api/v1/admin/ai/models — Available Models

Implemented. List model yang didukung beserta pricing dinamis.

✅ GET /api/v1/admin/ai/pending-reviews — Pending Variants

Implemented. List varian AI dengan variant_status = 'draft' atau 'pending'.

✅ POST /api/v1/admin/ai/review/{item_id} — Review Variant

Implemented. Approve / reject / archive varian AI.

POST /api/v1/admin/ai/review/102
Content-Type: application/json

{
  "action": "approve",
  "review_notes": "Soal sesuai basis, level tepat"
}

Detail: lihat Modul → AI Generation.

Import / Export

Prefix: /api/v1/import-export

Impor JSON dari Sejoli Tryout (Alur Utama)

⭐ Alur yang paling sering dipakai klien — tryout dibuat di Sejoli, export ke JSON, import ke app.

✅ POST /api/v1/import-export/tryout-json/preview — Preview Import

Implemented. Preview snapshot JSON sebelum commit.

POST /api/v1/import-export/tryout-json/preview
Authorization: Bearer {admin_token}
X-Website-ID: 1
Content-Type: multipart/form-data

(file: sejoli-tryout-132380.json)

Response 200 OK:

{
  "source_tryout_id": "132380",
  "source_key": "tryout_132380",
  "title": "Tryout PEKA Logika Paket 1",
  "permalink": "https://member.theyellowjacket.id/...",
  "question_diff": {
    "total_questions": 50,
    "new_questions": 50,
    "updated_questions": 0,
    "unchanged_questions": 0,
    "removed_questions": 0,
    "missing_option_labels": 0
  },
  "warnings": []
}

✅ POST /api/v1/import-export/tryout-json — Commit Import

Implemented. Eksekusi import dari snapshot.

POST /api/v1/import-export/tryout-json
Content-Type: application/json

{
  "tryout_id": "132380",
  "tryout_name": "Tryout PEKA Logika Paket 1",
  "snapshot_payload": {...}
}

Detail algoritma: lihat Modul → JSON Import.

Impor / Ekspor Excel (Nice-to-have)

Excel import berguna untuk migrasi dari workflow lama, tapi bukan alur utama. Alur utama klien: import JSON dari Sejoli Tryout.

✅ POST /api/v1/import-export/preview — Preview Excel Import

Implemented. Preview file Excel sebelum commit.

✅ POST /api/v1/import-export/questions — Import Excel

Implemented. Bulk insert soal dari Excel.

✅ GET /api/v1/import-export/export/questions — Export to Excel

Implemented. Export semua soal tryout ke format Excel.

Detail format Excel klien: lihat Modul → Excel Import/Export.

Website Management

Prefix: /api/v1

✅ GET /api/v1/websites — List Websites

Implemented (super-admin only). List semua tenant.

✅ POST /api/v1/websites — Create Website

Implemented (super-admin only). Buat tenant baru.

POST /api/v1/websites
Content-Type: application/json

{
  "site_url": "https://example.com",
  "site_name": "Example Site"
}

✅ PUT /api/v1/websites/{website_id} — Update Website

Implemented (super-admin only).

✅ DELETE /api/v1/websites/{website_id} — Delete Website

Implemented (super-admin only). Cascade delete semua data milik website.

Detail: lihat Integrasi → Multi-Tenant.

Permission Matrix

Bacaan Lanjutan

• Modul → AI Generation — detail algoritma & prompt
• Modul → JSON Import — alur utama import
• Modul → Excel Import/Export — alternatif import
• Integrasi → Multi-Tenant — manajemen website