api_aplicare_go/README.md

# 🚀 BPJS & Retribusi Management API

> **Sistem manajemen data BPJS dan retribusi berbasis API dengan arsitektur modern untuk integrasi layanan kesehatan dan manajemen tarif**

## 📑 Daftar Isi

- [✨ Fitur Utama](#-fitur-utama)
- [🏗️ Arsitektur](#%EF%B8%8F-arsitektur)
- [⚡ Quick Start](#-quick-start)
- [🔐 Autentikasi](#-autentikasi)
- [📊 API Endpoints](#-api-endpoints)
- [🛠️ Development](#%EF%B8%8F-development)
- [🚀 Deployment](#-deployment)
- [📚 Dokumentasi](#-dokumentasi)

***

## ✨ Fitur Utama

### Core Features

- **🏥 BPJS Integration** - Integrasi dengan layanan BPJS Kesehatan
- **💰 Retribusi Management** - Manajemen tarif dan retribusi dinas
- **🔒 JWT Authentication** - Autentikasi dengan Keycloak integration
- **🔍 Dynamic Filtering** - Filter dan pencarian data retribusi
- **📊 Health Monitoring** - Monitoring kesehatan sistem
- **📖 API Documentation** - Dokumentasi Swagger yang interaktif

### Developer Experience

- **🔥 Hot Reload** - Development dengan auto-restart
- **🐳 Docker Ready** - Deployment dengan container
- **⚡ Code Generator** - Generator handler otomatis
- **🗄️ Multi Database** - Support PostgreSQL, MySQL, MongoDB
- **📈 Real-time Updates** - WebSocket notifications

***

## 🏗️ Arsitektur

### Clean Architecture Layers

```
┌─────────────────────────────────────┐
│           Presentation Layer        │  ← handlers/, routes/
├─────────────────────────────────────┤
│           Application Layer         │  ← middleware/, validators/
├─────────────────────────────────────┤
│              Domain Layer           │  ← models/, interfaces/
├─────────────────────────────────────┤
│          Infrastructure Layer       │  ← database/, external APIs
└─────────────────────────────────────┘
```


### Struktur Project

```
bpjs-retribusi-api/
├── 📁 cmd/
│   └── api/main.go                 # 🚪 Entry point aplikasi
├── 📁 internal/                    # 🏠 Core business logic
│   ├── handlers/                   # 🎮 HTTP controllers
│   │   ├── auth/                   # 🔐 Authentication handlers
│   │   ├── peserta/                # 🏥 BPJS participant handlers
│   │   ├── retribusi/              # 💰 Retribusi handlers
│   │   └── healthcheck/            # 💚 Health check handlers
│   ├── middleware/                 # 🛡️ Auth & validation middleware
│   ├── models/                     # 📊 Data structures
│   ├── routes/                     # 🛣️ API routing
│   ├── services/                   # 💼 Business logic services
│   └── database/                   # 💾 Database connections
├── 📁 tools/                       # 🔧 Development tools
│   ├── general/                    # 🎯 General generators
│   └── bpjs/                       # 🏥 BPJS specific tools
├── 📁 docs/                        # 📚 Documentation
└── 📁 scripts/                     # 📜 Automation scripts
```


***

## ⚡ Quick Start

### 1️⃣ Setup Environment (2 menit)

```bash
# Clone repository
git clone <repository-url>
cd bpjs-retribusi-api

# Setup environment
cp example.env .env
```

### 2️⃣ Pilih Method Setup

**🐳 Docker (Recommended)**

```bash
make docker-run
```

**🔧 Manual Setup**

```bash
# Install dependencies
go mod download

# Start server
go run cmd/api/main.go
```

### 3️⃣ Verify Installation

| Service | URL | Status |
| :-- | :-- | :-- |
| **API** | http://localhost:8080/api/v1 | ✅ |
| **Swagger** | http://localhost:8080/swagger/index.html | 📖 |
| **Health Check** | http://localhost:8080/api/sistem/health | 💚 |


***

## 🔐 Autentikasi

### Login \& Mendapatkan Token

```bash
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "password"
  }'
```

**Response:**

```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600,
  "user": {
    "id": "123",
    "username": "admin",
    "role": "admin"
  }
}
```


### Menggunakan Token

```bash
curl -X GET http://localhost:8080/api/v1/products \
  -H "Authorization: Bearer <your-token>"
```


### Demo Accounts

| Username | Password | Role | Akses |
| :-- | :-- | :-- | :-- |
| `admin` | `password` | Admin | Semua endpoint |
| `user` | `password` | User | Read-only |


***

## 📊 API Endpoints

### 🌍 Public Endpoints

| Method | Endpoint | Deskripsi |
| :-- | :-- | :-- |
| `POST` | `/api/v1/auth/login` | Login pengguna |
| `POST` | `/api/v1/auth/register` | Registrasi pengguna baru |
| `GET` | `/api/sistem/health` | Status kesehatan API |
| `GET` | `/api/sistem/info` | Informasi sistem |

### 🔒 Protected Endpoints

#### BPJS Integration

| Method | Endpoint | Deskripsi |
| :-- | :-- | :-- |
| `GET` | `/api/v1/Peserta/nokartu/:nokartu` | Data peserta berdasarkan nomor kartu |
| `GET` | `/api/v1/Peserta/nik/:nik` | Data peserta berdasarkan NIK |

#### Retribusi Management

| Method | Endpoint | Deskripsi |
| :-- | :-- | :-- |
| `GET` | `/api/v1/retribusi` | List semua retribusi |
| `GET` | `/api/v1/retribusi/dynamic` | Query dengan filter dinamis |
| `GET` | `/api/v1/retribusi/search` | Pencarian retribusi |
| `GET` | `/api/v1/retribusi/id/:id` | Detail retribusi by ID |
| `POST` | `/api/v1/retribusi` | Buat retribusi baru |
| `PUT` | `/api/v1/retribusi/id/:id` | Update retribusi |
| `DELETE` | `/api/v1/retribusi/id/:id` | Hapus retribusi |

#### Dynamic Query Examples

**Filter berdasarkan jenis:**

```bash
GET /api/v1/retribusi/dynamic?filter[Jenis][_eq]=RETRIBUSI PELAYANAN KESEHATAN
```

**Kombinasi filter:**

```bash
GET /api/v1/retribusi/dynamic?filter[status][_eq]=active&filter[Tarif][_gt]=100000
```

**Pagination dan sorting:**

```bash
GET /api/v1/retribusi/dynamic?sort=-date_created&limit=10&offset=20
```

**Advanced search:**

```bash
GET /api/v1/retribusi/search?q=keyword&limit=20&offset=0
```


***

## 🛠️ Development

### Code Generation (30 detik)

**🎯 Generate CRUD Lengkap**

```bash
# Generate handler untuk entity baru
go run tools/general/generate-handler.go retribusi get post put delete

# Generate dengan fitur advanced
go run tools/general/generate-handler.go peserta get post put delete dynamic search stats
```

**🏥 Generate BPJS Handler**

```bash
# Single service
go run tools/bpjs/generate-bpjs-handler.go tools/bpjs/reference/peserta get

# Semua service dari config
go run tools/bpjs/generate-handler.go tools/bpjs/services-config-bpjs.yaml
```


### Development Commands

```bash
# 🔥 Development dengan hot reload
make watch

# 🧪 Testing
make test           # Unit tests
make itest          # Integration tests
make test-all       # Semua tests

# 📖 Update dokumentasi
make docs           # Generate Swagger docs

# 🔍 Code quality
make lint           # Linting
make format         # Format code
```


### Environment Configuration

**📁 .env File:**

```bash
# Database
BLUEPRINT_DB_HOST=localhost
BLUEPRINT_DB_PORT=5432
BLUEPRINT_DB_USERNAME=postgres
BLUEPRINT_DB_PASSWORD=postgres
BLUEPRINT_DB_DATABASE=api_service

# JWT
JWT_SECRET=your-super-secret-key-change-in-production

# External APIs
BPJS_BASE_URL=https://api.bpjs-kesehatan.go.id
SATUSEHAT_BASE_URL=https://api.satusehat.kemkes.go.id

# Application
APP_ENV=development
APP_PORT=8080
LOG_LEVEL=debug
```


***

## 🚀 Deployment

### 🐳 Docker Deployment

**Development:**

```bash
# Start semua services
make docker-run

# Stop services
make docker-down

# Rebuild dan restart
make docker-rebuild
```

**Production:**

```bash
# Build production image
docker build -t api-service:prod .

# Run production container
docker run -d \
  --name api-service \
  -p 8080:8080 \
  --env-file .env.prod \
  api-service:prod
```


### 🔧 Manual Deployment

```bash
# Build aplikasi
make build

# Run migrations
./scripts/migrate.sh up

# Start server
./bin/api-service
```


***

## 📚 Dokumentasi

### 📖 Interactive API Documentation

Kunjungi **Swagger UI** di: http://localhost:8080/swagger/index.html

**Cara menggunakan:**

1. 🔑 Login melalui `/auth/login` endpoint
2. 📋 Copy token dari response
3. 🔓 Klik tombol "Authorize" di Swagger
4. 📝 Masukkan: `Bearer <your-token>`
5. ✅ Test semua endpoint yang tersedia

### 🧪 Testing Examples

**JavaScript/Axios:**

```javascript
// Login dan set token
const auth = await axios.post('/api/v1/auth/login', {
  username: 'admin',
  password: 'password'
});

axios.defaults.headers.common['Authorization'] = 
  `Bearer ${auth.data.access_token}`;

// Fetch BPJS participant data
const peserta = await axios.get('/api/v1/Peserta/nokartu/1234567890123456');
console.log(peserta.data);

// Fetch retribusi data
const retribusi = await axios.get('/api/v1/retribusi');
console.log(retribusi.data);
```

**cURL Examples:**

```bash
# Login
TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"password"}' | jq -r '.access_token')

# Get BPJS participant data
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/api/v1/Peserta/nokartu/1234567890123456

# Get retribusi data
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/api/v1/retribusi
```


### 🔍 Health Monitoring

```bash
# Basic health check
curl http://localhost:8080/api/v1/health

# Detailed system info
curl http://localhost:8080/api/v1/health/detailed
```

**Response:**

```json
{
  "status": "healthy",
  "timestamp": "2025-09-10T05:39:00Z",
  "services": {
    "database": "connected",
    "bpjs_api": "accessible",
    "satusehat_api": "accessible"
  },
  "version": "1.0.0"
}
```


***

## 🚨 Troubleshooting

### Masalah Umum

**❌ Database Connection Error**

```bash
# Cek status PostgreSQL
make db-status

# Reset database
make db-reset

# Check logs
make logs-db
```

**❌ Generate Handler Gagal**

- ✅ Pastikan berada di root project
- ✅ Cek permission write di folder `internal/`
- ✅ Verifikasi file `internal/routes/v1/routes.go` exists

**❌ Token Invalid/Expired**

- 🔄 Login ulang untuk mendapatkan token baru
- ⏰ Token expire dalam 1 jam (configurable)
- 📝 Format harus: `Bearer <token>`

**❌ Import Error saat Generate**

- 🧹 Jalankan: `go mod tidy`
- 🔄 Restart development server
- 📝 Cek format import di generated files


### Debug Mode

```bash
# Enable debug logging
export LOG_LEVEL=debug

# Run dengan verbose output
make run-debug

# Monitor performance
make monitor
```


***

## 🎯 Next Steps

### 📋 Development Roadmap

- [ ] ✅ **Setup environment selesai**
- [ ] ✅ **Generate handler pertama**
- [ ] ✅ **Test dengan Swagger**
- [ ] 🔄 **Implementasi business logic**
- [ ] 🔄 **Tambahkan unit tests**
- [ ] 🔄 **Setup CI/CD pipeline**
- [ ] 🔄 **Deploy ke production**


### 🚀 Advanced Features

- **📊 Monitoring \& Observability**
- **🔒 Enhanced Security (Rate limiting, CORS)**
- **📈 Performance Optimization**
- **🌐 Multi-language Support**
- **📱 Mobile SDK Integration**

***

**⚡ Total setup time: 5 menit | 🔧 Generate CRUD: 30 detik | 🧪 Testing: Langsung via Swagger**

> **💡 Pro Tip:** Gunakan `make help` untuk melihat semua command yang tersedia

***