Perintah: catalog:validate

Perintah catalog:validate adalah instrumen audit holistik untuk memverifikasi keutuhan skema, konfigurasi situs, katalog produk kanonik, daftar penawaran harga (offers), dan artikel panduan belanja pada website afiliasi Anda. Berbeda dari validasi ulasan produk individual, perintah ini bertindak sebagai inspektur integritas arsitektur situs secara menyeluruh sebelum proses kompilasi (build) dan publikasi dijalankan ke internet publik.

---

⚡ Fungsi Cepat

• Audit Holistik Ekosistem Situs: Memeriksa 5 pilar berkas operator sekaligus (site.yaml, schema.yaml, copy.yaml, products.csv, offers.csv, guides/*.md, dan snippets/*.html).
• Perlindungan Penawaran Yatim Piatu (Orphan Offer Shield): Menangkap tautan harga atau merchant yang merujuk pada product_id yang tidak terdaftar di katalog produk.
• Penegakan Kontrak Skema Kanonik: Memastikan susunan kolom, tipe data (angka, teks, URL, tanggal), dan required fields pada katalog CSV 100% selaras dengan definisi skema YAML.
• Pencegahan Data Fluktuatif Palsu: Menolak kolom sosial atau manipulasi stok (rating, review_count, reviews, stock, availability) yang dilarang di katalog kanonik CuanAff demi menjaga keaslian data.
• Verifikasi Sumber Bukti Nyata (Provenance Gate): Memastikan setiap fakta spesifikasi teknis yang dipajang ke pengunjung membawa tautan sumber HTTPS resmi yang valid di provenance_json.

---

⚖️ Tabel Komparasi: catalog:validate vs product:validate

Banyak praktisi afiliasi pemula rancu membedakan antara catalog:validate dan product:validate. Keduanya memiliki peran pelindung kualitas yang sangat krusial, namun bekerja pada lapisan (layer) yang berbeda:

Aspek Pembeda	catalog:validate (Audit Holistik Situs)	product:validate (Audit Spesifik Produk)
Cakupan Pemeriksaan (Scope)	Seluruh Ekosistem Situs: Menilai integritas skema, konfigurasi situs, relasi antar-tabel, seluruh penawaran toko, dan artikel panduan.	Konten Ulasan Produk Individual: Memeriksa kesiapan isi artikel ulasan 1 berkas markdown atau seluruh berkas ulasan di folder produk.
Fokus Pemeriksaan Kunci	Kepatuhan skema data, keunikan ID/slug, relasi penawaran harga (orphan offers), larangan kolom terlarang, dan HTTPS provenance.	Kelengkapan foto hero resmi (>800px), kewajaran rentang harga pasar (plausibility gate), opini ulasan (pros, cons, verdict), dan validitas link afiliasi.
Berkas yang Diperiksa	sites/<site>/schema.yaml, site.yaml, copy.yaml, products.csv, offers.csv, guides/*.md, snippets/*.html.	data/<site>/products/*.md (mendukung filter 1 produk spesifik via --slug=<slug>).
Kebutuhan Parameter	Wajib menyertakan opsi nama situs: --site=<nama-situs>.	Opsional: Otomatis mendeteksi situs aktif saat ini jika --site tidak disebutkan.
Waktu Penggunaan Ideal	Saat mendesain struktur situs baru, setelah impor masal data produk/penawaran, atau audit arsitektur sebelum perakitan (build).	Saat selesai menambah produk ulasan baru, setelah mengunduh foto hero (product:media), atau sebelum site:publish.
Tipe Laporan Galat	Menunjukkan nomor baris dan nama kolom spesifik yang melanggar kontrak skema data (misal: header CSV tidak cocok).	Menunjukkan status kelayakan ulasan ulasan (misal: foto resolusi rendah, review pros/cons kosong, draf belum lengkap).

Kapan Harus Menjalankan Masing-Masing Perintah?

Gunakan catalog:validate untuk memastikan fondasi arsitektur dan database relasi situs Anda kokoh tanpa ada penawaran toko yang salah alamat. Setelah fondasi katalog terbukti valid, gunakan product:validate untuk memastikan setiap artikel ulasan produk siap dinikmati dan menghasilkan konversi klik bagi pembaca ulasan Anda.

---

🛠️ Jalur A: Perintah CLI

Jalankan perintah audit integritas katalog situs di terminal komputer Anda:

php cuanaff catalog:validate --site="<slug-situs>" [opsi]

Parameter --site Bersifat Wajib

Berbeda dari perintah ulasan yang dapat mendeteksi situs aktif secara implisit, catalog:validate mewajibkan Anda menyebutkan target situs secara eksplisit melalui opsi --site guna memastikan validasi skema diarahkan tepat ke folder situs yang dituju.

Contoh Praktis Penggunaan:

# 1. Memvalidasi integritas katalog situs koper & tas travel (tas)
php cuanaff catalog:validate --site=tas

# 2. Memvalidasi integritas katalog situs peralatan rumah pintar (aman)
php cuanaff catalog:validate --site=aman

# 3. Menentukan lokasi direktori root kustom jika bekerja di luar root kerja default
php cuanaff catalog:validate --site=pilihlistrik --root="."

# 4. Menjalankan simulasi validasi aman (--dry-run)
php cuanaff catalog:validate --site=tas --dry-run

# 5. Menghasilkan laporan terstruktur dalam format JSON untuk otomasi pipa CI/CD
php cuanaff catalog:validate --site=tas --json

Pratinjau Output Terminal (Status Sukses 100%):

Catalog is valid.

Jika dijalankan dengan opsi --json, sistem CuanAff mengembalikan kontrak payload mesin terperinci:

{
  "schema_version": "1",
  "status": "ok",
  "command": "catalog:validate",
  "operation_id": "203af59281bc9a3f",
  "dry_run": true,
  "exit_code": 0,
  "message": "Catalog is valid.",
  "site": "tas",
  "products": 15,
  "offers": 15,
  "guides": 3,
  "data": {
    "site": "tas",
    "products": 15,
    "offers": 15,
    "guides": 3,
    "errors": []
  },
  "warnings": [],
  "errors": [],
  "artifacts": []
}

Pratinjau Output Terminal (Jika Terdeteksi Kesalahan Data):

Catalog validation failed.
- Baris 1 · Kolom header: products.csv header must exactly match schema.yaml field order: id,slug,name,brand,category,price
- Baris 14 · Kolom product_id: Offer references an unknown product (orphan offer).
- Baris 22 · Kolom provenance_json: Every displayed fact requires an HTTPS URL in provenance_json.

---

🤖 Jalur B: Prompt AI Siap Salin

Anda dapat memanfaatkan asisten coding pintar (Antigravity, CommandCode, Cursor) atau web chat AI (ChatGPT, Claude) untuk mengeksekusi validasi katalog, mengurai pesan error teknis, dan langsung memperbaiki ketidaksesuaian skema di berkas konfigurasi Anda.

Kolaborasi Tanpa Hambat Bersama Coding Agent

Coding agent seperti Antigravity dan CommandCode dapat membaca daftar error baris dan kolom yang dilaporkan oleh catalog:validate --json, lalu secara presisi membuka berkas products.csv atau offers.csv dan membetulkan baris yang rusak secara otomatis.

Template Prompt AI Audit & Perbaikan Struktur Katalog:

Template Prompt AI (Tinggal Salin & Sesuaikan Nama Situs)

Halo AI, tolong bantu saya melakukan audit integritas arsitektur katalog website CuanAff untuk situs target.

Target Pemeriksaan:
- Nama Situs: tas (atau ganti dengan slug situs Anda)

Langkah-langkah yang harus dilakukan:
1. Jalankan perintah validasi katalog di terminal dengan format JSON:
   php cuanaff catalog:validate --site=tas --json

2. Periksa output payload JSON yang dihasilkan:
   - Jika status "ok" dan errors kosong: Konfirmasikan bahwa skema situs, produk, penawaran toko, dan artikel panduan telah 100% valid dan siap dirakit (site:build).
   - Jika status "error": Urai seluruh daftar error yang ditemukan (baris, kolom, dan pesan kesalahan).

3. Jika ditemukan kesalahan, jelaskan akar penyebabnya secara ringkas:
   - Apakah terdapat penawaran yatim piatu (orphan offer) di offers.csv?
   - Apakah ada kolom wajib yang kosong atau tipe datanya tidak sesuai schema.yaml?
   - Apakah urutan header di products.csv tidak sama persis dengan schema.yaml?

4. Bantu saya mengedit dan memperbaiki berkas yang bermasalah, lalu jalankan ulang `catalog:validate --site=tas` hingga 100% PASS.

---

⚙️ Parameter & Opsi Kunci

Berikut adalah seluruh opsi yang didukung oleh perintah catalog:validate:

Parameter / Opsi	Wajib?	Bawaan	Keterangan & Fungsi	Contoh Nilai
--site="<slug>"	Wajib	Tidak ada	Menentukan direktori situs target yang akan divalidasi skema dan datanya.	--site="tas"
--root="<path>"	Opsional	Direktori kerja	Menentukan direktori pangkal (root workspace) proyek jika dijalankan dari lokasi folder luar.	--root="."
--dry-run	Opsional	false	Disediakan untuk konsistensi CLI CuanAff (perintah ini selalu bersifat membaca aman / read-only).	--dry-run
--json	Opsional	false	Mengeluarkan hasil audit lengkap dalam format objek JSON terstruktur untuk otomasi pengujian atau skrip.	--json

---

🔍 5 Pilar Integritas yang Diperiksa Secara Otomatis

Saat Anda mengeksekusi catalog:validate, mesin CuanAff melakukan verifikasi ketat pada 5 pilar aset website:

1. Berkas Konfigurasi & Skema (site.yaml, schema.yaml, copy.yaml):
   • Memastikan schema.yaml mendefinisikan pemetaan fields yang tidak kosong.
   • Memastikan empat bidang inti (core fields) wajib hadir: id, slug, name, dan brand.
2. Katalog Produk Kanonik (products.csv):
   • Kesesuaian Header: Urutan kolom pada baris pertama products.csv wajib sama persis dengan urutan bidang di schema.yaml.
   • Tipe Data Valid: Bidang bertipe integer, number, url, dan date (format YYYY-MM-DD) dicek ketat.
   • Keunikan Data: Memastikan tidak ada duplikasi nilai id atau slug pada baris produk yang berbeda.
   • Larangan Social Proof Palsu: Melarang keberadaan kolom fluktuatif seperti rating, review_count, reviews, stock, dan availability pada katalog kanonik demi integritas ulasan abadi.
3. Daftar Penawaran Harga Toko (offers.csv):
   • Deteksi Penawaran Yatim Piatu (Orphan Offers): Setiap baris penawaran wajib mengaitkan product_id ke produk yang nyata ada di katalog. Penawaran tanpa induk produk akan langsung digagalkan.
   • Pencegahan Duplikasi Toko: Memastikan tidak ada lebih dari satu baris penawaran untuk kombinasi produk dan nama toko (merchant) yang sama.
4. Artikel Panduan Belanja (guides/*.md):
   • Memastikan seluruh berkas panduan memiliki YAML frontmatter yang sah dengan bidang wajib slug, title, dan query.
5. Injeksi Slot Template Snippet (snippets/*.html):
   • Memverifikasi keberadaan dan keterbacaan berkas injeksi kustom: head.html, body-start.html, body-end.html, header.html, inline.html, sidebar.html, dan footer.html.

---

📱 Hasil Nyata & Langkah Selanjutnya

Setelah seluruh aset situs Anda dinyatakan "Catalog is valid" oleh catalog:validate:

1. Bebas Crash Saat Perakitan Situs:
   • Mesin perakit (site builder) dapat memproses seluruh data produk dan penawaran menjadi halaman HTML statis tanpa risiko terhenti di tengah jalan karena inkonsistensi skema.
2. Koneksi Merchant 100% Akurat:
   • Pengunjung ulasan Anda selalu diarahkan ke toko yang tepat dengan harga yang terverifikasi, menjaga kepercayaan pembeli dan rasio konversi komisi afiliasi.
3. Langkah Berikutnya dalam Alur Kerja CuanAff:
   • Bubuhkan Stempel Audit E-E-A-T: Tandai kepengarangan berkas katalog ulasan Anda menggunakan perintah catalog:stamp:

     php cuanaff catalog:stamp --site=tas

   • Validasi Ulasan Konten Publik: Pastikan kelengkapan visual dan pros/cons dengan product:validate:

     php cuanaff product:validate --site=tas

   • Rakit & Publikasikan Website: Lanjutkan ke perakitan situs dengan site:build atau rilis langsung via site:publish.