andri
/
ApiTerasKotaMagelang
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ApiTerasKotaMagelang/DOKUMENTASI_FORM.md

6.2 KiB
Raw Blame History

[cite_start]Berdasarkan bedah dokumen Surat Edaran (SE) Musrenbang RKPD 2027[cite: 114], berikut adalah rancangan spesifikasi API (API Blueprint) untuk sistem ORARIBET.

Rancangan ini difokuskan untuk mengakomodasi alur bisnis, validasi, dan struktur data yang diwajibkan dalam SE tersebut. Anda bisa memberikan prompt ini langsung ke AI Copilot untuk mulai coding.

Spesifikasi API Service: Modul Perencanaan (Renja RT)

Base URL: /api/v2/perencanaan

1. Master Data & Aturan Bisnis

[cite_start]Digunakan untuk mempopulate dropdown form dan validasi batasan anggaran sesuai Lampiran II SE[cite: 952].

  • Endpoint: GET /master/menu-kegiatan
  • Description: Mengambil daftar menu kegiatan (Wajib/Pilihan/Tematik) beserta pagu harga dan aturan.
  • Response Body: 
    {
  "success": true,
  "data": [
    {
      "id": 1,
      "kategori": "PELAYANAN DASAR",
      [cite_start]"sifat": "WAJIB", // [cite: 953]
      "menu": "PARENTING",
      "sub_menu": "Keluarga dengan anak usia 0-18 tahun",
      "pagu_max": 200000,
      "satuan_pagu": "per_keluarga_per_tahun",
      [cite_start]"opd_pengampu": "DPMP4KB" // [cite: 953]
    },
    {
      "id": 2,
      "kategori": "INFRASTRUKTUR LINGKUNGAN",
      "sifat": "PILIHAN",
      [cite_start]"menu": "RTLH", // [cite: 969]
      "pagu_max": 17500000,
      [cite_start]"syarat_dokumen": ["ktp", "kk", "surat_tanah", "foto_kondisi"] // [cite: 970]
    }
  ]
}

2. Modul Profiling RT (Basis Data)

[cite_start]Sesuai Lampiran I, Profil RT wajib diisi sebelum Musrenbang[cite: 197]. Data ini sangat banyak, jadi dibagi per seksi.

  • Endpoint: POST /profil-rt/update
  • Description: Menyimpan data profil (Perumahan, Individu, Aset, RTLH).
  • Request Body: 
    {
  "tahun_anggaran": 2027,
  "kode_rt": "003",
  "kode_rw": "006",
  "kode_kelurahan": "REJOWINANGUN_SELATAN",
  [cite_start]"data_perumahan": { // [cite: 238-272]
    "status_lahan": {
      "milik_sendiri": 10,
      "sewa": 5
    },
    "sumber_air": {
      "pdam": 12,
      "sumur": 3
    },
    "sanitasi": {
      "jamban_sendiri": 15,
      "mc_umum": 0
    }
  },
  [cite_start]"data_individu": { // [cite: 273-331]
    "jumlah_penduduk": {
      "laki_laki": 20,
      "perempuan": 25
    },
    [cite_start]"disabilitas": { // [cite: 301]
      "tuna_daksa": 1,
      "tuna_netra": 0
    }
  }
}

3. Modul Input Usulan (Renja RT)

[cite_start]Ini adalah core transaction di mana RT menginput usulan kegiatan senilai Rp 50.000.000[cite: 146].

  • Endpoint: POST /renja/usulan
  • Description: Tambah usulan baru ke dalam keranjang Renja RT.
  • Request Body: 
    {
  "id_rt": "RT001",
  "tahun": 2027,
  [cite_start]"jenis_usulan": "UTAMA", // Enum: UTAMA, CADANGAN [cite: 219]
  "kategori_id": 2, // Referensi ke Master Menu
  [cite_start]"uraian_kegiatan": "Perbaikan Rumah Tidak Layak Huni Bpk. Fulan", // [cite: 409]
  "volume": 1,
  "satuan": "Unit",
  "harga_satuan": 17500000, // Harus validasi cross-check dengan SSH
  "total_biaya": 17500000,
  [cite_start]"lokasi_koordinat": "-7.4728, 110.2198", // [cite: 409]
  [cite_start]"rujukan_ssh": "Halaman 45, Item A.1", // [cite: 409]
  "dokumen_pendukung": {
     [cite_start]"surat_izin_lahan": "url_file.pdf", // Wajib jika di lahan pribadi [cite: 204]
     [cite_start]"proposal": "url_file.pdf" // Wajib jika Tematik Baru [cite: 214]
  }
}

4. Modul Validasi Pagu (Logic Checker)

Untuk memastikan total usulan tidak melebihi Rp 50 Juta sebelum submit.

  • Endpoint: GET /renja/summary/{id_rt}
  • Response Body: 
    {
  [cite_start]"total_alokasi": 50000000, // [cite: 146]
  "total_terpakai": 48500000,
  "sisa_anggaran": 1500000,
  "status_valid": true, // False jika minus
  "detail_per_kategori": {
    "pelayanan_dasar": 20000000,
    "tematik": 28500000
  },
  [cite_start]"usulan_cadangan_count": 2 // [cite: 219]
}

5. Modul Berita Acara (Output)

Untuk generate laporan PDF sesuai format lampiran.

  • Endpoint: POST /dokumen/generate-ba
  • Description: Generate PDF Berita Acara Musrenbang RT.
  • Request Body: 
    {
  "id_transaksi_renja": "TRX-2027-RT001",
  [cite_start]"tanggal_musrenbang": "2025-12-10", // [cite: 221]
  [cite_start]"jumlah_peserta": 45, // Validasi min 2/3 warga [cite: 393]
  "foto_dokumentasi": ["img1.jpg", "img2.jpg"],
  "ttd_ketua_rt": "base64_signature",
  "ttd_rw": "base64_signature",
  [cite_start]"ttd_fasilitator": "base64_signature" // [cite: 410]
}

6. Modul Verifikasi (Kelurahan & Kecamatan)

Digunakan oleh Kelurahan/Kecamatan untuk Approval usulan.

  • Endpoint: POST /verifikasi/approval
  • Request Body: 
    {
  "id_usulan": 12345,
  "level_verifikasi": "KELURAHAN", // Enum: KELURAHAN, KECAMATAN, KOTA
  "status": "DITOLAK", // Enum: DISETUJUI, DITOLAK
  [cite_start]"alasan_penolakan": "Tidak sesuai kriteria teknis RTLH", // Wajib jika ditolak [cite: 500]
  [cite_start]"id_usulan_pengganti": 67890 // ID dari Usulan Cadangan jika ada swap [cite: 501]
}

Instruksi untuk Copilot/Developer

  1. [cite_start]Validasi Dokumen: Pastikan pada endpoint /renja/usulan, jika kategori kegiatan adalah fisik di tanah bukan aset Pemkot, API wajib me-return error jika surat_izin_lahan null[cite: 204].
  2. [cite_start]Validasi Waktu: Endpoint input Renja RT harus dikunci (read-only) setelah Minggu ke-2 Desember 2025[cite: 141].
  3. [cite_start]Logika Usulan Cadangan: Saat verifikasi kelurahan (/verifikasi/approval), jika status DITOLAK, sistem harus menawarkan pop-up/opsi untuk mengambil data dari jenis_usulan: CADANGAN[cite: 501].
  4. Integrasi Profil: Data dari endpoint /profil-rt/update harus menjadi baseline. Misal: Jika di profil tercatat tidak ada RTLH, maka saat input usulan RTLH, berikan warning atau blocker.