Peninjauan kualitas jawaban

Ketika pengguna tidak menyukai sebuah jawaban (PUT /messages/{message_id}/feedback dengan "rating": "dislike"), jawaban itu terbuka untuk ditinjau. Tiga route berikut adalah sisi admin dari alur tersebut. Aplikasi admin partner menampilkan layarnya; halaman ini adalah kontrak API-nya.

Metode	Path	Kegunaan
GET	/quality/flagged	Mencantumkan jawaban yang sedang ditinjau, keluhan terbaru lebih dulu.
GET	/quality/flagged/{message_id}	Satu jawaban yang ditandai, beserta akar masalah dan riwayat tinjauannya.
POST	/quality/flagged/{message_id}/review	Menetapkan status tinjauan dan menambahkan catatan.

Ketiganya memerlukan API key yang dikonfigurasi dan principal admin yang terverifikasi: JWT terverifikasi, atau klaim yang diterbitkan edge tepercaya. operator dan user menerima 403. Saat autentikasi terverifikasi nonaktif (require_auth), route ini menghasilkan 503: X-User-Role yang dinyatakan pemanggil tidak memberi akses apa pun, karena tampilan ini memperlihatkan pertanyaan dan catatan semua pengguna. Ini gerbang yang sama dengan pengelolaan MCP dan prompt. Tampilkan menu Kualitas hanya untuk admin. Klien browser melalui BFF same-origin dan tidak pernah memegang API key bersama.

Setiap pembacaan menulis satu baris ai_engine_audit_log (action = read, entityType = message) yang mencatat admin, karena tampilan ini memperlihatkan pertanyaan pengguna. Setiap tinjauan menulis baris review yang mencatat admin, beserta status baru, status yang digantikannya, catatan, dan tautan issue. Perubahan status dan baris itu tersimpan bersama atau tidak sama sekali.

Status tinjauan

open ──▶ reviewing ──▶ resolved
              │
              └──▶ needs_prompt_change ──▶ resolved

Dislike menetapkan open jika jawaban belum memiliki status, dan membukanya kembali sebagai open setelah admin menyelesaikannya. Dislike tidak pernah mengatur ulang tinjauan yang sedang berjalan (reviewing, needs_prompt_change), dan like berikutnya tidak pernah mengubah status. Admin dapat menetapkan salah satu dari empat status. needs_prompt_change mewajibkan issue_url, karena prompt hanya berubah melalui pull request dan deploy. Tidak ada editor prompt; tampilkan teks bantuan "Perubahan prompt melalui tim AI (issue → rilis)".

GET /quality/flagged

Parameter query	Tipe	Arti
status	open | reviewing | needs_prompt_change | resolved	Status tinjauan.
reason	wrong_answer | wrong_citation | incomplete | outdated | offensive_or_sara | other	Alasan umpan balik.
rating	like | dislike	Rating terakhir. Pengguna dapat mengubah dislike menjadi like setelah tinjauan dibuka.
from	date-time ISO 8601	Umpan balik pada atau setelah waktu ini (inklusif). Waktu tanpa offset dibaca sebagai UTC.
to	date-time ISO 8601	Umpan balik sebelum waktu ini (eksklusif).
tool	string	Cocok dengan tool yang membangun grounding, atau tool apa pun yang dipanggil agen.
fallback_reason	string	Fallback yang tercatat, misalnya over_refusal, coverage_incomplete, atau no_answer.
cursor	string	next_cursor dari halaman sebelumnya. Cursor yang tidak diterbitkan API menghasilkan 422.
limit	1–100, bawaan 25	Ukuran halaman.

Filter digabung dengan AND. tool atau fallback_reason yang berisi NUL (U+0000) menghasilkan 422. Paging memakai keyset pada (feedback_at, message_id), sehingga baris yang masuk saat pengguna berpindah halaman tidak terulang.

{
  "items": [
    {
      "message_id": "00000000-0000-0000-0000-000000000102",
      "conversation_id": "00000000-0000-0000-0000-000000000101",
      "question_preview": "Apa isi Qanun Aceh Nomor 7 Tahun 2024 tentang zakat?",
      "rating": "dislike",
      "reason": "wrong_citation",
      "review_status": "open",
      "grounding_rate": 0.78,
      "fallback_reason": null,
      "tool_executed": "vector_search",
      "feedback_at": "2026-11-03T08:00:00+00:00",
      "created_at": "2026-11-03T07:59:12+00:00"
    }
  ],
  "next_cursor": "<opaque cursor>"
}

question_preview adalah 200 karakter pertama pertanyaan pengguna yang dijawab. grounding_rate adalah tingkat keterverifikasian klaim (klaim terverifikasi dari klaim yang disusun, 0–1), dan bernilai null bila tidak ada yang dapat diperiksa atau jawaban lebih lama dari metrik ini. Tampilkan — untuk null, bukan 0%. tool_executed bernilai null pada jawaban yang disimpan sebelum field ini dicatat.

GET /quality/flagged/{message_id}

{
  "message_id": "00000000-0000-0000-0000-000000000102",
  "conversation_id": "00000000-0000-0000-0000-000000000101",
  "question": "Apa isi Qanun Aceh Nomor 7 Tahun 2024 tentang zakat?",
  "answer": "Qanun tersebut mengatur ... [1]",
  "citations": [{"document_id": "…", "chunk_id": "…", "document_title": "…"}],
  "grounding_rate": 0.78,
  "claims_supported": 7,
  "claims_total": 9,
  "feedback": {
    "rating": "dislike",
    "reason": "wrong_citation",
    "note": "Pasal yang dikutip salah",
    "at": "2026-11-03T08:00:00+00:00"
  },
  "review_status": "reviewing",
  "review_history": [
    {
      "actor": "11111111-1111-4111-8111-111111111111",
      "action": "review",
      "status": "reviewing",
      "rating": null,
      "reason": null,
      "note": "Cek ulang pasal",
      "issue_url": null,
      "at": "2026-11-03T09:10:00+00:00"
    }
  ],
  "root_causes": [
    {
      "code": "mis_citation",
      "label_id": "Sitasi tidak valid",
      "label_en": "Claim cited a passage it was not shown",
      "evidence": {"fabricated_label": 1}
    }
  ],
  "trace_available": true,
  "created_at": "2026-11-03T07:59:12+00:00"
}

answer dan citations adalah apa yang ditampilkan kepada pengguna, setelah Kebijakan Pemerintah (Policy Guard). review_history mencantumkan event audit feedback dan review jawaban tersebut, yang terlama lebih dulu.

Akar masalah

Akar masalah dibaca dari apa yang dicatat jawaban: metadata pesannya dan trace per jawaban (ADR-0046). Masing-masing adalah pemeriksaan atas hitungan, kode, atau flag yang tersimpan, bukan penilaian model, dan evidence hanya memuat hitungan dan kode tersebut, tidak pernah teks jawaban atau klaim. Akar masalah mengarahkan peninjau ke suatu tahap; ia tidak memutuskan apakah jawaban salah.

code	Muncul ketika	evidence
retrieval_miss	Fallback-nya no_answer (di bawah ambang tanpa-jawaban), atau trace menunjukkan retrieval berjalan dan tidak mengembalikan kandidat.	fallback_reason, no_answer, atau retrieval_legs + candidates
over_refusal	Fallback-nya over_refusal atau coverage_incomplete.	fallback_reason
mis_citation	Sebuah klaim mengutip label passage yang tidak diperlihatkan kepadanya (/query/v2: verdict invalid_citation).	hitungan fabricated_label atau invalid_citation
unsupported_claims	Pemeriksaan dukungan menolak sebuah klaim (/query/v2: verdict unsupported).	hitungan unsupported atau v2_unsupported
policy_guard_block	Policy Guard memblokir jawaban.	action, dan categories bila tercatat
no_issue_found	Tidak satu pun di atas. Manusia yang memutuskan.	{}

Beberapa akar masalah dapat muncul bersamaan; urutannya mengikuti tabel. Bila baris trace tidak ada, atau ditulis dalam format yang tidak dapat dibaca versi ini, trace_available bernilai false dan akar masalah hanya berasal dari metadata pesan.

message_id yang tidak dikenal, tidak valid, atau tidak pernah ditandai menghasilkan 404.

POST /quality/flagged/{message_id}/review

{
  "status": "needs_prompt_change",
  "note": "Instruksi sitasi perlu diperjelas",
  "issue_url": "https://github.com/insourcedata/superfk-aceh/issues/1234"
}

Field	Aturan
status	Wajib; salah satu dari empat status tinjauan.
note	Opsional; paling banyak 1000 karakter; tanpa NUL (U+0000).
issue_url	URL http(s) opsional tanpa NUL (U+0000); wajib bila status adalah needs_prompt_change.

Field yang tidak dikenal, status tidak valid, catatan terlalu panjang, tautan bukan http(s), NUL di catatan atau tautan, atau tautan yang hilang untuk needs_prompt_change menghasilkan 422, dan tidak ada yang berubah. Responsnya adalah detail terbaru, dengan bentuk yang sama seperti GET /quality/flagged/{message_id}.

Error

Status	Arti
401	API key tidak ada atau tidak valid, atau principal terverifikasi yang diwajibkan tidak ada.
403	Principal terverifikasi bukan administrator.
404	Jawaban tidak dikenal, tidak valid, atau tidak sedang ditinjau.
422	Filter, cursor, atau body tinjauan tidak valid.
503	Autentikasi terverifikasi nonaktif, sehingga layanan tinjauan tidak tersedia.

Belum ada di versi ini

• Endpoint dasbor ringkasan (hitungan per status, alasan, akar masalah). Filter pada daftar sudah mencakup alur tinjauan; endpoint ini akan ditambahkan bila partner memintanya.
• Ringkasan akar masalah yang ditulis AI. Fitur ini memerlukan model judge dan pemeriksaan manual dalam Bahasa Indonesia (ADR-0037).