Lokasi (Locations)

Pendahuluan

Modul Lokasi menyediakan akses baca-saja ke data provinsi dan kota di Indonesia. Data bersumber dari file benih (seed) dengan pemisah pipa (pipe-delimited) di disk, bukan dari database. Fitur ini digunakan oleh frontend untuk pemilihan alamat organisasi dan penetapan lokasi aset. Logika bisnis dienkapsulasi dalam LocationService.

---

Controller

File: API/Controllers/Locations/LocationsController.cs Rute: api/locations Mewarisi: ControllerBase Auth: Tidak ada (titik akhir publik) Delegasi ke: ILocationService

Titik Akhir (Endpoints)

Titik Akhir	Metode	Auth	Deskripsi
api/locations/provinces	GET	Publik	Daftar semua provinsi diurutkan berdasarkan nama
api/locations/provinces/{provinceId}/cities	GET	Publik	Daftar kota dalam provinsi tertentu
api/locations/cities	GET	Publik	Cari semua kota dengan filter opsional

Parameter Kueri (GET cities)

Parameter	Tipe	Wajib	Deskripsi
search	string	Tidak	Filter berdasarkan nama kota (case-insensitive contains)
provinceId	int	Tidak	Filter berdasarkan ID provinsi

Format Respons

Semua titik akhir mengembalikan respons standar ApiEnvelope:

{
  "success": true,
  "data": {
    "items": [...],
    "count": 42
  },
  "errors": []
}

---

Layanan

File: Infrastructure/Services/LocationService.cs Antarmuka: ILocationService Masa Pakai (Lifetime): Scoped

Sumber Data

Data lokasi dimuat dari file teks dengan pemisah pipa di direktori Seed/:

File	Ukuran	Konten
province.txt	~1 KB	Data provinsi (34 provinsi)
city.txt	~14 KB	Data kota/kabupaten

File benih tambahan ada (country.txt, district.txt, subdistricts.txt) tetapi saat ini tidak digunakan oleh API.

Format File

province.txt: id|unknown|code|name|abbreviation

city.txt: id|province_id|type_code|unknown|code|name|unknown

• type_code: 1 = Kabupaten, lainnya = Kota

Metode Layanan

Metode	Mengembalikan	Deskripsi
GetProvinces()	IReadOnlyList<ProvinceDto>	Semua provinsi, diurutkan berdasarkan nama
GetCitiesByProvince(int)	IReadOnlyList<CityDto>	Kota dalam sebuah provinsi, diurutkan nama
GetAllCities(string?, int?)	IReadOnlyList<CityDto>	Pencarian kota dengan filter, diurutkan nama

---

DTO

File: Application/DTOs/LocationDtos.cs

public sealed record ProvinceDto(int Id, string Code, string Name, string Abbreviation);

public sealed record CityDto(int Id, int ProvinceId, string Type, string Code, string Name, string FullName);

• CityDto.Type: Berupa "Kabupaten" atau "Kota"
• CityDto.FullName: Diawali dengan tipe, contoh "Kabupaten Bandung", "Kota Bandung"

---

Catatan Desain

1. Tanpa dependensi database — Data lokasi bersifat statis dan dibaca dari file disk, menjaga database tetap fokus pada entitas dinamis.
2. Pembacaan sinkron — I/O file dilakukan secara sinkron karena file data berukuran kecil.
3. Tanpa caching — File dibaca ulang pada setiap permintaan. Mengingat ukuran file yang kecil dan frekuensi panggilan yang umum, hal ini dapat diterima tetapi dapat dioptimalkan dengan cache dalam memori (in-memory cache).
4. Tanpa autentikasi — Titik akhir lokasi bersifat publik karena hanya berisi data referensi.

---

Perbaikan di Masa Depan

Terbuka

• Menambahkan caching dalam memori untuk menghindari pembacaan ulang file benih pada setiap permintaan.
• Mendukung pencarian kecamatan (district) dan kelurahan (subdistrict) menggunakan data benih yang sudah ada.