# API Design - Jadwal Sholat Masjid

Base URL: `/api/v1/masjid/{masjid_id}/jadwal-sholat`

---

## 1. Get Jadwal Sholat Hari Ini

**Endpoint:** `GET /api/v1/masjid/{masjid_id}/jadwal-sholat`

**Description:** Mendapatkan jadwal sholat untuk hari ini berdasarkan lokasi masjid.

**Query Parameters:**
- `tanggal` (optional): YYYY-MM-DD (default: hari ini)

**Response Codes:**
- `200 OK` - Sukses
- `400 Bad Request` - Format tanggal invalid
- `401 Unauthorized` - Token tidak valid
- `403 Forbidden` - Tidak punya akses ke masjid ini
- `404 Not Found` - Masjid tidak ditemukan
- `500 Internal Server Error` - Server error

**Success Response (200):**
```json
{
  "type": "jadwal_sholat",
  "data": {
    "tanggal": "2026-02-07",
    "hijriah": "1447-08-09",
    "lokasi": {
      "kota": "Jakarta",
      "latitude": -6.2088,
      "longitude": 106.8456
    },
    "jadwal": {
      "imsak": "04:27",
      "subuh": "04:37",
      "syuruq": "05:45",
      "dzuhur": "12:03",
      "ashar": "15:26",
      "maghrib": "18:20",
      "isya": "19:32"
    }
  }
}
```

**Error Response (404):**
```json
{
  "type": "error",
  "message": "Masjid tidak ditemukan",
  "code": "MASJID_NOT_FOUND"
}
```

---

## 2. Get Jadwal Sholat Bulanan

**Endpoint:** `GET /api/v1/masjid/{masjid_id}/jadwal-sholat/bulanan`

**Description:** Mendapatkan jadwal sholat untuk satu bulan penuh.

**Query Parameters:**
- `bulan` (optional): 1-12 (default: bulan ini)
- `tahun` (optional): YYYY (default: tahun ini)

**Response Codes:**
- `200 OK` - Sukses
- `400 Bad Request` - Parameter bulan/tahun invalid
- `401 Unauthorized` - Token tidak valid
- `403 Forbidden` - Tidak punya akses ke masjid ini
- `404 Not Found` - Masjid tidak ditemukan
- `500 Internal Server Error` - Server error

**Success Response (200):**
```json
{
  "type": "jadwal_sholat_bulanan",
  "data": {
    "bulan": 2,
    "tahun": 2026,
    "nama_bulan": "Februari",
    "lokasi": {
      "kota": "Jakarta",
      "latitude": -6.2088,
      "longitude": 106.8456
    },
    "jadwal": [
      {
        "tanggal": "2026-02-01",
        "hijriah": "1447-08-03",
        "hari": "Minggu",
        "imsak": "04:28",
        "subuh": "04:38",
        "syuruq": "05:46",
        "dzuhur": "12:04",
        "ashar": "15:27",
        "maghrib": "18:21",
        "isya": "19:33"
      },
      {
        "tanggal": "2026-02-02",
        "hijriah": "1447-08-04",
        "hari": "Senin",
        "imsak": "04:28",
        "subuh": "04:38",
        "syuruq": "05:46",
        "dzuhur": "12:04",
        "ashar": "15:27",
        "maghrib": "18:21",
        "isya": "19:33"
      }
    ]
  }
}
```

**Error Response (400):**
```json
{
  "type": "error",
  "message": "Parameter bulan harus antara 1-12",
  "code": "INVALID_MONTH_PARAMETER"
}
```

---

## 3. Get Waktu Sholat Berikutnya

**Endpoint:** `GET /api/v1/masjid/{masjid_id}/jadwal-sholat/berikutnya`

**Description:** Mendapatkan waktu sholat berikutnya dari waktu sekarang.

**Response Codes:**
- `200 OK` - Sukses
- `401 Unauthorized` - Token tidak valid
- `403 Forbidden` - Tidak punya akses ke masjid ini
- `404 Not Found` - Masjid tidak ditemukan
- `500 Internal Server Error` - Server error

**Success Response (200):**
```json
{
  "type": "sholat_berikutnya",
  "data": {
    "waktu_sekarang": "2026-02-07T14:30:00+07:00",
    "sholat_berikutnya": {
      "nama": "Ashar",
      "waktu": "15:26",
      "countdown": {
        "jam": 0,
        "menit": 56,
        "detik": 0
      }
    },
    "jadwal_hari_ini": {
      "imsak": "04:27",
      "subuh": "04:37",
      "syuruq": "05:45",
      "dzuhur": "12:03",
      "ashar": "15:26",
      "maghrib": "18:20",
      "isya": "19:32"
    }
  }
}
```

**Error Response (404):**
```json
{
  "type": "error",
  "message": "Masjid tidak ditemukan",
  "code": "MASJID_NOT_FOUND"
}
```

---

## 4. Update Lokasi Masjid

**Endpoint:** `PUT /api/v1/masjid/{masjid_id}/jadwal-sholat/lokasi`

**Description:** Update koordinat lokasi masjid untuk perhitungan jadwal sholat.

**Request Body:**
```json
{
  "kota": "Jakarta",
  "latitude": -6.2088,
  "longitude": 106.8456,
  "timezone": "Asia/Jakarta"
}
```

**Response Codes:**
- `200 OK` - Sukses
- `400 Bad Request` - Data tidak valid
- `401 Unauthorized` - Token tidak valid
- `403 Forbidden` - Tidak punya akses ke masjid ini
- `404 Not Found` - Masjid tidak ditemukan
- `422 Unprocessable Entity` - Validasi gagal
- `500 Internal Server Error` - Server error

**Success Response (200):**
```json
{
  "type": "update_lokasi",
  "data": {
    "message": "Lokasi masjid berhasil diperbarui",
    "lokasi": {
      "kota": "Jakarta",
      "latitude": -6.2088,
      "longitude": 106.8456,
      "timezone": "Asia/Jakarta"
    }
  }
}
```

**Error Response (422):**
```json
{
  "type": "error",
  "message": "Validasi gagal",
  "code": "VALIDATION_ERROR",
  "errors": {
    "latitude": ["Latitude harus antara -90 dan 90"],
    "longitude": ["Longitude harus antara -180 dan 180"]
  }
}
```

---

## 5. Get Pengaturan Koreksi Waktu

**Endpoint:** `GET /api/v1/masjid/{masjid_id}/jadwal-sholat/koreksi`

**Description:** Mendapatkan pengaturan koreksi waktu untuk setiap sholat (untuk penyesuaian lokal).

**Response Codes:**
- `200 OK` - Sukses
- `401 Unauthorized` - Token tidak valid
- `403 Forbidden` - Tidak punya akses ke masjid ini
- `404 Not Found` - Masjid tidak ditemukan
- `500 Internal Server Error` - Server error

**Success Response (200):**
```json
{
  "type": "koreksi_waktu",
  "data": {
    "imsak": 0,
    "subuh": 0,
    "syuruq": 0,
    "dzuhur": 2,
    "ashar": 0,
    "maghrib": 2,
    "isya": 0
  },
  "meta": {
    "satuan": "menit",
    "keterangan": "Nilai positif = mundur, nilai negatif = maju"
  }
}
```

---

## 6. Update Koreksi Waktu

**Endpoint:** `PUT /api/v1/masjid/{masjid_id}/jadwal-sholat/koreksi`

**Description:** Update koreksi waktu untuk penyesuaian jadwal sholat lokal.

**Request Body:**
```json
{
  "imsak": 0,
  "subuh": 0,
  "syuruq": 0,
  "dzuhur": 2,
  "ashar": 0,
  "maghrib": 2,
  "isya": 0
}
```

**Response Codes:**
- `200 OK` - Sukses
- `400 Bad Request` - Data tidak valid
- `401 Unauthorized` - Token tidak valid
- `403 Forbidden` - Tidak punya akses ke masjid ini
- `404 Not Found` - Masjid tidak ditemukan
- `422 Unprocessable Entity` - Validasi gagal
- `500 Internal Server Error` - Server error

**Success Response (200):**
```json
{
  "type": "update_koreksi",
  "data": {
    "message": "Koreksi waktu berhasil diperbarui",
    "koreksi": {
      "imsak": 0,
      "subuh": 0,
      "syuruq": 0,
      "dzuhur": 2,
      "ashar": 0,
      "maghrib": 2,
      "isya": 0
    }
  }
}
```

**Error Response (422):**
```json
{
  "type": "error",
  "message": "Validasi gagal",
  "code": "VALIDATION_ERROR",
  "errors": {
    "dzuhur": ["Koreksi waktu harus antara -30 dan 30 menit"]
  }
}
```

---

## HTTP Status Codes

Semua endpoint menggunakan status code standar:

| Code | Status | Keterangan |
|------|--------|------------|
| 200 | OK | Request berhasil |
| 400 | Bad Request | Parameter tidak valid |
| 401 | Unauthorized | Token tidak valid atau expired |
| 403 | Forbidden | User tidak punya akses ke resource |
| 404 | Not Found | Resource tidak ditemukan |
| 422 | Unprocessable Entity | Validasi data gagal |
| 500 | Internal Server Error | Error di server |

---

## Error Response Format

Semua error menggunakan format konsisten:

```json
{
  "type": "error",
  "message": "Deskripsi error yang human-readable",
  "code": "ERROR_CODE_UPPERCASE"
}
```

**Error Codes:**
- `MASJID_NOT_FOUND` - Masjid tidak ditemukan
- `INVALID_DATE_FORMAT` - Format tanggal tidak valid
- `INVALID_MONTH_PARAMETER` - Parameter bulan tidak valid (harus 1-12)
- `INVALID_YEAR_PARAMETER` - Parameter tahun tidak valid
- `VALIDATION_ERROR` - Validasi data gagal
- `LOCATION_NOT_SET` - Lokasi masjid belum diset
- `UNAUTHORIZED_ACCESS` - Tidak punya akses
- `INVALID_TOKEN` - Token tidak valid

---

## Notes

1. **Autentikasi**: Semua endpoint memerlukan Bearer Token
2. **Akses**: User harus punya akses ke masjid yang diminta
3. **Format Waktu**: Menggunakan format HH:mm (24 jam)
4. **Timezone**: Semua waktu dalam timezone Asia/Jakarta (WIB)
5. **Tanggal**: Format ISO 8601 (YYYY-MM-DD)
6. **Hijriah**: Tanggal Hijriah dalam format YYYY-MM-DD
7. **Koreksi Waktu**: Dalam satuan menit, range -30 sampai +30 menit
8. **Perhitungan**: Menggunakan metode Kementerian Agama RI
9. **Koordinat**: 
   - Latitude: -90 sampai 90
   - Longitude: -180 sampai 180
10. **Cache**: Jadwal sholat di-cache untuk performa optimal

---

## Metode Perhitungan

API ini menggunakan metode perhitungan Kementerian Agama RI dengan parameter:
- **Fajr Angle**: 20°
- **Isha Angle**: 18°
- **Madhab**: Shafi'i (untuk Ashar)
- **High Latitude**: None (Indonesia di khatulistiwa)

---

## Contoh Penggunaan

### Mendapatkan Jadwal Hari Ini
```bash
GET /api/v1/masjid/1/jadwal-sholat
Authorization: Bearer {token}
```

### Mendapatkan Jadwal Bulan Ramadhan
```bash
GET /api/v1/masjid/1/jadwal-sholat/bulanan?bulan=3&tahun=2026
Authorization: Bearer {token}
```

### Cek Sholat Berikutnya
```bash
GET /api/v1/masjid/1/jadwal-sholat/berikutnya
Authorization: Bearer {token}
```

### Update Lokasi Masjid
```bash
PUT /api/v1/masjid/1/jadwal-sholat/lokasi
Authorization: Bearer {token}
Content-Type: application/json

{
  "kota": "Bandung",
  "latitude": -6.9175,
  "longitude": 107.6191,
  "timezone": "Asia/Jakarta"
}
```

### Update Koreksi Waktu
```bash
PUT /api/v1/masjid/1/jadwal-sholat/koreksi
Authorization: Bearer {token}
Content-Type: application/json

{
  "dzuhur": 2,
  "maghrib": 2
}
```
