Kelengkapan Data dan `missings.json`

has_path dan api/missings.json adalah dua artefak turunan yang lahir setelah API statis dan polygon terbentuk. Keduanya membaca satu sumber kebenaran yang sama, yaitu isi direktori api/paths/: keberadaan api/paths/{id}.json menentukan nilai has_path, dan wilayah yang tidak punya berkas itu atau tidak punya koordinat dicatat sebagai missing. Urutan perintah lengkapnya ada di Pipeline Generate dengan Go Tools, sedangkan bentuk polygon dan endpoint paths dibahas di Polygon dan Boundary.

graph LR
  paths["api/paths/*.json"] --> set["buildHasPathSet"]
  set --> add["add-has-path"]
  set --> mis["generate-missings"]
  api["api/provinces.json, provinces/, regencies/, districts/, villages/"] --> add
  add --> patched["endpoint JSON + has_path"]
  patched --> mis
  mis --> out["api/missings.json"]
  style paths fill:#336791,color:#fff
  style api fill:#336791,color:#fff
  style set fill:#8b5cf6,color:#fff
  style add fill:#f59e0b,color:#000
  style mis fill:#f59e0b,color:#000
  style patched fill:#2d7d46,color:#fff
  style out fill:#2d7d46,color:#fff
%% fig: Satu himpunan kode polygon menjadi dua artefak turunan
%% desc: buildHasPathSet membaca api/paths lalu dipakai add-has-path untuk memflag endpoint dan generate-missings untuk menulis api/missings.json.

Kedua perintah adalah subcommand dari go run ./tools: add-has-path (alias add_has_path) dan generate-missings (alias generate-missing, generate_missings, missings) tools/main.go:20-22¹. Flag keduanya identik tools/add_has_path.go:30-43² dan tools/generate_missings.go:39-46³.

add-has-path: dari direktori paths ke flag has_path

buildHasPathSet membaca api/paths dan memakai nama berkas tanpa akhiran .json sebagai kode wilayah, jadi api/paths/32.73.01.json menyumbang kode 32.73.01 tools/add_has_path.go:110-127⁴. Direktori yang tidak ada bukan error: fungsi mengembalikan map kosong tools/add_has_path.go:112-117⁵.

⚠️ Karena map kosong tidak memicu error, -paths yang salah arah membuat seluruh item mendapat has_path: false tanpa peringatan apa pun. Gejalanya baru terlihat di missings.json: total_missing meledak mendekati jumlah seluruh wilayah.

Target patch dikumpulkan dari api/provinces.json di akar, lalu semua berkas .json di api/provinces, api/regencies, api/districts, dan api/villages. Subdirektori yang belum ada dilewati begitu saja tools/add_has_path.go:63-92⁶.

Pada cabang array, setiap item yang punya id non-kosong diberi m["has_path"] = hasPathSet[id]; pada cabang object, has_path diisi dari data.id, dan bila id kosong dipakai nama berkas tanpa .json. Nilainya selalu ditulis, true maupun false, sehingga field ini tidak pernah hilang dari response tools/add_has_path.go:143-170⁷. Berkas yang tidak punya key data menghasilkan missing data key, dicatat sebagai warning, lalu dilewati tanpa menghentikan proses; di akhir muncul log patched N/M files tools/add_has_path.go:138-141⁸ dan tools/add_has_path.go:94-107⁹.

meta ikut diubah: generated_at dihapus dan updated_at diisi tanggal UTC berformat 2006-01-02 tools/add_has_path.go:172-176¹⁰. Berkas ditulis ulang secara compact tanpa indent lewat writeGenJSONCompactPatched tools/add_has_path.go:188-197¹¹.

⚠️ Patch ini menulis ulang ribuan berkas dan menghapus meta.generated_at secara permanen. Diff di git akan tampak besar walau isi data tidak berubah selain has_path dan updated_at.

Aturan has_latlng dan seleksi masuk daftar

generate-missings tidak membaca field has_path hasil patch; ia menghitung ulang himpunan kode dari api/paths lewat buildHasPathSet yang sama tools/generate_missings.go:66-70¹². Berkas yang discan sama persis: api/provinces.json di akar plus empat subdirektori level, dengan urutan provinsi lebih dulu tools/generate_missings.go:72-100¹³. extractItemsForMissings mengubah tiap berkas menjadi missingItem berisi id, name, has_path, dan has_latlng tools/generate_missings.go:179-226¹⁴, dengan nama field JSON persis seperti struct-nya tools/generate_missings.go:31-36¹⁵.

hasLatLngFromMap mengembalikan false pada empat keadaan tools/generate_missings.go:228-247¹⁶:

toFloat64 menerima float64, float32, int, int64, dan json.Number; tipe lain langsung dianggap gagal tools/generate_missings.go:249-267²². Karena pasangan 0,0 dianggap placeholder, wilayah dengan lat 0 tetapi lng bukan 0 tetap dihitung punya koordinat.

Satu wilayah bisa muncul di berkas daftar sekaligus berkas detail, jadi entri disaring dengan !it.HasPath || !it.HasLatLng lalu dideduplikasi per id; kemunculan pertama yang dipertahankan tools/generate_missings.go:102-116²³. Hasilnya diurutkan menaik berdasarkan id sebelum dilaporkan tools/generate_missings.go:118-123²⁴, sehingga diff missings.json antar build stabil.

Diagram berikut memetakan keputusan untuk satu item yang dibaca dari sebuah berkas endpoint.

stateDiagram-v2
    [*] --> ReadItem
    ReadItem --> SkipNoID: id kosong
    ReadItem --> PathGate: id terisi
    PathGate --> Candidate: has_path false
    PathGate --> LatLngGate: has_path true
    LatLngGate --> Candidate: has_latlng false
    LatLngGate --> SkipComplete: has_latlng true
    Candidate --> Dedupe
    Dedupe --> SortByID: id belum tercatat
    Dedupe --> SkipDuplicate: id sudah tercatat
    SortByID --> Summary
    SkipComplete --> [*]
    SkipDuplicate --> [*]
    Summary --> [*]
    classDef storage fill:#336791,color:#fff
    classDef caution fill:#f59e0b,color:#000
    classDef derived fill:#8b5cf6,color:#fff
    classDef bad fill:#dc2626,color:#fff
    classDef good fill:#2d7d46,color:#fff
    class ReadItem storage
    class PathGate,LatLngGate caution
    class Candidate bad
    class Dedupe,SortByID,Summary derived
    class SkipComplete,SkipDuplicate,SkipNoID good
%% fig: Keputusan satu wilayah masuk missings.json
%% desc: Item gugur bila id kosong atau lengkap punya polygon dan koordinat; sisanya masuk daftar, dideduplikasi, lalu diurutkan untuk summary.

Isi api/missings.json

Keluaran berupa objek dengan tiga kunci: data berisi slice missingItem yang sudah terurut, meta berisi updated_at dan level: 0, serta summary berisi hitungan agregat tools/generate_missings.go:159-168²⁵. Berkas ditulis lewat writeGenJSON dengan indent = false, jadi hasilnya satu baris compact tanpa spasi hiasan tools/generate_static_api.go:581-595²⁶.

Semua angka di tabel itu dihitung dalam satu putaran atas missings sebelum summary disusun tools/generate_missings.go:125-157²⁷. by_level memakai genLevelCount(id), yaitu jumlah titik pada kode, lalu memetakan 0 ke province, 1 ke regency, 2 ke district, dan 3 ke village tools/generate_missings.go:138-148²⁸ dan tools/generate_static_api.go:164²⁹.

⚠️ by_level memakai jumlah titik, sedangkan meta.level di endpoint wilayah biasa adalah jumlah titik ditambah satu. Jadi kode 11.01 masuk by_level.regency (1 titik) tetapi response regencies/11.json menandainya level 2. Jangan menyamakan kedua skala ini saat menyusun dashboard kelengkapan.

Kontrak sisi klien cukup sederhana: setiap item di endpoint wilayah selalu punya has_path, dan cek flag itu sebelum memanggil /paths/{id}.json supaya tidak kena 404 README.md:74³⁰. Daftar wilayah yang belum lengkap tersedia sebagai satu endpoint datar beserta summary README.md:94-95³¹. Contoh response lengkap dengan angka total_missing 360, total_missing_path 320, total_missing_latlng 40, dan total_missing_both 12 ada di README.md:493-519³². Urutan pemanggilan add-has-path lalu generate-missings dalam build ada di README.md:614-618³³.