update documentation

Author: ardie069

README.md

@@ -1,7 +1,7 @@
 # 🕌 Kalender Hijriyah Digital API Berbasis Golang & NASA SPICE 🌙
 
 [![Go Release](https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat-square&logo=go)](https://go.dev/)
-[![Framework: Gin](https://img.shields.io/badge/Framework-Gin-009688?style=flat-square&logo=gin)](https://gin-gonic.com/)
+[![Framework: Gin](https://img.shields.io/badge/Framework-Gin-059669?style=flat-square&logo=gin)](https://gin-gonic.com/)
 [![Engine: SPICE Toolkit](https://img.shields.io/badge/Engine-SPICE%20C--Kernel-10b981?style=flat-square)](https://naif.jpl.nasa.gov/naif/toolkit.html)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 
@@ -11,21 +11,22 @@ Aplikasi ini berfokus murni pada penyediaan REST API untuk perhitungan **tanggal
 
 ## 🧠 Perencanaan
 
-Proyek ini telah dire-write dari Python/FastAPI ke **Golang** untuk memaksimalkan performa dan konkurensi, menggunakan binding ke pustaka **NASA SPICE (CSPICE)**.
+Aplikasi ini dibangun menggunakan **Golang** untuk memaksimalkan performa dan konkurensi, dengan integrasi langsung ke pustaka **NASA SPICE (CSPICE)** melalui CGO. Hal ini memungkinkan perhitungan astronomi dilakukan dengan standar ketelitian tingkat wahana antariksa.
 
 1. Data astronomi dikalkulasi dari ephemeris riil NASA JPL `de440s.bsp` untuk tingkat ketelitian luar angkasa.
 2. Menjembatani perbedaan metode penetapan Hijriyah (KHGT, Umm al-Qura, MABIMS, Wujudul Hilal) di dalam satu platform.
-3. Memastikan pergantian hari Hijriyah **tepat saat Matahari terbenam** (Maghrib lokal pengamat).
+3. Memastikan pergantian hari Hijriyah **tepat saat Matahari terbenam** (Maghrib lokal pengamat) dengan pencarian *bisection* presisi.
 
 ---
 
 ## ✨ Fitur Utama
 
 - 📡 **Real-time Lunar Telemetry**: Sinkronisasi dan perhitungan lintasan matahari dan bulan dengan CSPICE.
-- 🌅 **Precise Sunset/Fajr Bisection**: Bisection search presisi tinggi 24 jam untuk mendeteksi maghrib dan subuh lintas batasan zona waktu.
+- 🌅 **Precise Solar Events**: Deteksi *Maghrib* (Sunset) dan *Subuh* (Fajr) menggunakan metode *bisection search* 24 jam untuk akurasi tinggi di berbagai lintang.
+- 🕋 **Prayer Times Engine**: Perhitungan jadwal shalat multi-metode (Kemenag, MWL, ISNA, Umm Al-Qura, dll) dengan dukungan koreksi lintang tinggi.
 - 🧪 **Multi-Method Engine**:
-  - 🌍 **KHGT**: Kalender Hijriyah Global Tunggal (Turki 2016).
-  - 🕋 **Umm al-Qura**: Standar otoritas Makkah.
+  - 🌍 **KHGT**: Kalender Hijriyah Global Tunggal (Turki 2016) dengan pemindaian visibilitas global.
+  - 🕋 **Umm al-Qura**: Standar kalender resmi Arab Saudi (Makkah).
   - 🔢 **Hisab**: Berdasarkan Wujudul Hilal.
   - 🔭 **Rukyatul Hilal**: Berdasarkan kriteria MABIMS (2022).
 - 🔮 **Global Scan Optimizations**: Scan visibilitas komprehensif dari barat (Benua Amerika) untuk hisab global dengan koreksi ekuinoks/midnight UTC.
@@ -38,7 +39,7 @@ Proyek ini telah dire-write dari Python/FastAPI ke **Golang** untuk memaksimalka
 
 - **Golang**: Bahasa yang sangat cepat dengan concurrency yang handal.
 - **Gin**: HTTP Web framework yang simpel dan cepat.
-- **CGO & CSPICE**: Toolkit geometri navigasi antariksa standar NASA yang ditautkan via CGO.
+- **CGO & CSPICE**: Menggunakan `spice_bridge.go` untuk mengakses fungsi CSPICE secara aman dengan mekanisme `sync.Mutex` karena keterbatasan *thread-safety* pada pustaka C asli.
 - **Docker**: Siap deploy dimana saja secara konsisten dengan multi-stage build.
 
 ---
@@ -64,22 +65,24 @@ kalender-hijriyah/
 ├── cmd/
 │   └── api/              # Entry point Gin API Server
 ├── data/                 # SPICE Kernels (de440s.bsp, naif0012.tls, dll)
-├── internal/
+├── core/
 │   ├── api/              # HTTP Handlers
 │   ├── astronomy/        # SPICE CGO Bindings & Kalkulator Orbit
 │   ├── calendar/         # Logika KHGT, Umm al-Qura, MABIMS
 │   ├── models/           # Skema logika Golang
+│   ├── prayer/           # Konfigurasi & Kalkulasi Jadwal Shalat
 │   └── services/         # Orkestrasi Kalender Utama
-├── docs/                 # Dokumentasi Metode Hijriyah
+├── docs/                 # Dokumentasi Detail & Teori Falak
 └── README.md
 ```
 
 🌐 API Endpoints Utama
 
-| Endpoint                                     | Method | Fungsi                                      | Parameter Query                                                                 |
-| -------------------------------------------- | ------ | ------------------------------------------- | ------------------------------------------------------------------------------- |
-| `/api/v4/hijri/date?lat={lat}&lon={lon}`     | GET    | Perhitungan prediksi bulan                  | lat, lon                                                                        |
-| `/api/v4/moon/telemetry?lat={lat}&lon={lon}` | GET    | Informasi bulan berdasarkan lokasi pengguna | lat, lon, altitude, elongation, azimuth, distance km, illumination, phase, time |
+| Endpoint                 | Method | Fungsi                                      | Parameter Query                    |
+| ------------------------ | ------ | ------------------------------------------- | ---------------------------------- |
+| `/api/v4/hijri/date`     | GET    | Konversi tanggal ke Hijriyah (Multi-metode) | lat, lon, method, date             |
+| `/api/v4/prayer/times`   | GET    | Jadwal Salat harian presisi                 | lat, lon, method, asr_method, date |
+| `/api/v4/moon/telemetry` | GET    | Data astronomi Bulan real-time              | lat, lon, date                     |
 
 ---
 

docs/api-design.md

@@ -13,6 +13,7 @@ API dirancang agar:
 Mengembalikan tanggal Hijriyah hari ini beserta prediksi pergantian bulan dari berbagai metode penetapan.
 
 Parameter Query Opsional:
+
 - `date`: Tanggal ISO 8601 (Contoh: `2026-03-18T12:00:00Z`). Default: current time.
 - `lat`: Latitude observer (Contoh: `-7.98`). Default: Malang.
 - `lon`: Longitude observer (Contoh: `112.63`). Default: Malang.

docs/astronomical-model.md

@@ -18,6 +18,84 @@ untuk menghitung posisi Matahari dan Bulan menggunakan binding ke pustaka NASA S
 - Analisis Elongasi Geosentrik (Sudut pisah pusat Bumi-Bulan-Matahari) dan Toposentrik.
 - Prediksi Konjungsi Presisi (Ijtima).
 
+## 🌦 Refraksi Atmosfer
+
+Untuk kriteria berbasis Toposentrik (seperti MABIMS), sistem menerapkan koreksi refraksi atmosfer pada fungsi `ApplyRefraction`.
+Kami menggunakan model aproksimasi Bennett/Sæmundsson yang menghitung deviasi cahaya berdasarkan ketinggian geometris hilal. Hal ini sangat krusial karena hilal yang secara geometris berada di bawah ufuk bisa jadi terlihat secara visual karena pembiasan atmosfer.
+
+## 🛠 Arsitektur Teknis: SPICE, CGO, & Thread-Safety
+
+Sistem ini mengintegrasikan pustaka **CSPICE** (versi C dari toolkit SPICE NASA) ke dalam ekosistem **Golang** untuk mendapatkan akurasi tingkat tinggi yang setara dengan navigasi wahana antariksa.
+
+### 1. Integrasi CGO
+
+Karena CSPICE adalah pustaka berbasis C, kami menggunakan **CGO** sebagai jembatan. File `spice_bridge.go` bertindak sebagai *wrapper* yang memetakan fungsi-fungsi C (seperti `spkpos_c`, `str2et_c`, `furnsh_c`) ke fungsi Go. Hal ini memungkinkan logika bisnis kalender tetap berada di level tinggi (Go) sementara perhitungan geometri astronomi yang kompleks dilakukan oleh mesin SPICE yang sudah teruji.
+
+### 2. Keterbatasan Thread-Safety
+
+Pustaka CSPICE asli **tidak bersifat thread-safe**. Pustaka ini menggunakan variabel statis dan global internal untuk manajemen state (seperti error handling dan pool kernel). Jika dua goroutine mencoba memanggil fungsi SPICE secara bersamaan, hal ini dapat menyebabkan *memory corruption*, hasil kalkulasi yang tidak konsisten, atau aplikasi berhenti mendadak (*crash*).
+
+### 3. Mekanisme `sync.Mutex`
+
+Untuk mengatasi masalah keamanan thread tersebut, aplikasi ini menerapkan kebijakan **Global Lock** menggunakan `sync.Mutex` (didefinisikan sebagai `spiceMu`).
+
+Setiap kali fungsi jembatan astronomi dipanggil:
+
+1. `spiceMu.Lock()` dijalankan untuk memastikan hanya satu goroutine yang memiliki akses ke engine SPICE pada satu waktu.
+2. Fungsi internal SPICE dieksekusi melalui CGO.
+3. `spiceMu.Unlock()` (biasanya melalui `defer`) dijalankan segera setelah operasi selesai untuk memberikan giliran kepada goroutine lain.
+
+**Dampak Performa:**
+Meskipun akses ke SPICE dilakukan secara berurutan (*serialized*), performa sistem tetap sangat tinggi. Hal ini dikarenakan:
+
+- Operasi matematika SPICE sangat efisien dan berbasis memori.
+- Bottleneck aplikasi biasanya berada pada I/O jaringan, bukan pada kecepatan CPU dalam menghitung orbit.
+- Mekanisme ini jauh lebih aman dan stabil untuk lingkungan server yang melayani banyak permintaan secara konkuren.
+
+## 🏗 Setup Environment CGO & CSPICE
+
+Untuk mengompilasi proyek ini, sistem Anda harus memiliki compiler C (GCC/Clang) dan library CSPICE yang sudah terpasang di struktur folder yang benar.
+
+### 1. Persyaratan Sistem
+
+- **Linux/macOS**: GCC atau Clang terpasang.
+- **Windows**: MSYS2 atau MinGW-w64.
+- **Go**: Versi 1.25+ dengan `CGO_ENABLED=1`.
+
+### 2. Download CSPICE Toolkit
+
+Unduh toolkit sesuai dengan arsitektur sistem Anda dari NASA NAIF Website. [Klik di sini](https://naif.jpl.nasa.gov/pub/naif/toolkit/C/).
+
+### 3. Struktur Direktori Library
+
+Berdasarkan arahan `#cgo` di `core/astronomy/spice_bridge.go`, library harus diletakkan sebagai berikut:
+
+```plaintext
+core/astronomy/
+├── include/           <-- Salin semua file .h dari direktori 'include' CSPICE
+│   ├── SpiceUsr.h
+│   ├── SpiceZpl.h
+│   └── ...
+├── lib/               <-- Salin file library (.a atau .so) dari direktori 'lib'
+│   ├── cspice.a
+│   └── csupport.a
+└── spice_bridge.go
+```
+
+### 4. Kompilasi
+
+Pastikan variabel lingkungan `CGO_ENABLED` aktif saat melakukan build:
+
+```bash
+# Linux / macOS
+CGO_ENABLED=1 go build -o hilal-engine ./cmd/api
+
+# Windows (PowerShell)
+$env:CGO_ENABLED="1"; go build -o hilal-engine.exe ./cmd/api
+```
+
+*Catatan: Jika Anda menggunakan Docker, proses ini sudah diotomatisasi di dalam Dockerfile menggunakan multi-stage build untuk memastikan library C ter-link secara statis atau tersedia di runtime.*
+
 ## Catatan
 
 - Sistem ini **tidak menggantikan observasi lapangan** (Rukyatul Hilal aktual).

docs/calendar-logic.md

@@ -13,16 +13,18 @@ yang dikomputasi oleh API Golang v4.
 ## Alur Orkestrasi (Service Layer)
 
 1. Tentukan target `Date` (UTC) dan lokasi `Lat/Lon`.
-2. Hitung waktu sunset (Maghrib) lokal via Bisection Search 24H.
-3. Tentukan Ijtima (konjungsi) menggunakan pencarian dinamis (FindPreviousIjtima), bukan berdasarkan data tabular statis.
-4. Tentukan apakah waktu request *sebelum* atau *sesudah* Maghrib.
-5. Jalankan Evaluasi Multi-Metode:
-   - **KHGT (Global)**: Melakukan scan global (65° LU/LS) untuk mencari terpenuhinya kriteria Turki 2016 sebelum dan sesudah 24:00 UTC, termasuk *override* Ijtima Selandia Baru. Menggunakan parameter **Geosentris**.
-   - **Hisab Lokal**:
-     - **MABIMS**: Menggunakan proyeksi **Toposentrik** (termasuk refraksi atmosfer untuk ketinggian nyata).
-     - **Wujudul Hilal**: Menggunakan proyeksi **Geosentris**.
-   - **Umm al-Qura**: Mencocokkan dengan standar observatorium Makkah (Toposentris).
+2. Ambil tanggal Hijriyah **Tabular** sebagai pijakan awal untuk estimasi bulan dan tahun (`baseH`).
+3. Cari waktu **Ijtima (Konjungsi)** sebelumnya dalam rentang 30 hari menggunakan `FindPreviousIjtima`.
+4. Tentukan waktu evaluasi (Sunset/Maghrib) berdasarkan kriteria:
+   - **UMM_AL_QURA**: Lokasi Makkah.
+   - **MABIMS**: Lokasi Sabang (titik barat Indonesia).
+   - **Lokal**: Lokasi observer (`lat/lon`).
+   - **KHGT**: Pemindaian Global (tidak terikat satu lokasi).
+5. Tentukan apakah waktu request *sebelum* atau *sesudah* Maghrib.
+6. Tentukan `monthStartDate` (H+1 atau H+2 dari Ijtima) berdasarkan hasil evaluasi kriteria (`isNewMonth`).
+7. Hitung selisih hari (`daysElapsed`) antara target dengan awal bulan.
+8. Lakukan koreksi **Rollover** (jika `hDay < 1` atau `hDay > 30`) untuk menyesuaikan bulan dan tahun secara dinamis.
 
 ## Mengatasi Limitasi "Hari H+1"
 
-Sistem menggunakan fungsi pembantu `PredictHijriDate` untuk mengeliminasi statik +1 hari. Ini memastikan bulan ber-rollover dengan dinamis (menjadi hari ke-1 bulan selanjutnya) jika Hisab menyatakan wujud/imkanur rukyat, dan mengunci ke hari ke-30 (Istikmal) apabila tidak terlihat.
+Sistem secara dinamis menghitung hari Hijriyah (`hDay`) berdasarkan selisih waktu antara tanggal yang diminta dengan `monthStartDate` yang sudah dievaluasi. Logika ini memastikan pergantian bulan (rollover) terjadi secara akurat: menjadi hari ke-1 bulan selanjutnya jika kriteria hisab/rukyat terpenuhi, atau mengunci ke hari ke-30 (Istikmal) apabila hilal tidak terlihat. Penyesuaian bulan dan tahun juga dilakukan secara otomatis jika `hDay` berada di luar rentang bulan saat ini.

docs/hisab-vs-rukyat.md

@@ -21,10 +21,10 @@ Kalender Hijriyah API v4 tidak menyatukan Hisab dan Rukyat, melainkan menampilka
 - Diadopsi dari **Kongres Turki 2016**.
 - Bertujuan menyatukan kalender Islam sedunia menggunakan Hisab Imkanur Rukyat *Global*.
 - Kriteria global (Turki 2016):
-  - Hilal harus mencapai **Elongasi ≥ 8°** dan **Altitude Geosentrik ≥ 5°** di *mana pun* di bumi sebelum pukul **24:00 UTC**.
+  - Hilal harus mencapai **Elongasi ≥ 8°** dan **Altitude Geosentrik ≥ 5°** di belahan bumi *mana pun* sebelum pukul **24:00 UTC**.
   - **Pengecualian Rollover**: Jika kriteria di atas hanya terpenuhi *setelah* 24:00 UTC, bulan baru tetap masuk jika:
     1. Kriteria terpenuhi di wilayah **daratan Benua Amerika**.
-    2. **Ijtimak** (konjungsi) terjadi sebelum fajar di **Selandia Baru**.
+    2. **Ijtimak** (konjungsi) terjadi sebelum subuh di **Selandia Baru**.
 
 ## Implikasi API v4