rachmadiyanti.annisa.3004/service-vclaim
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
service-vclaim/README.md
Meninjar Mulyono 5460259426 first commit
2025-09-24 20:47:09 +07:00

12 KiB
Raw Permalink Blame History

🚀 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

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)

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

# Setup environment
cp example.env .env

2️⃣ Pilih Method Setup

🐳 Docker (Recommended)

make docker-run

🔧 Manual Setup

# 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

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

Response:

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

Menggunakan Token

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:

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

Kombinasi filter:

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

Pagination dan sorting:

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

Advanced search:

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

🛠️ Development

Code Generation (30 detik)

🎯 Generate CRUD Lengkap

# 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

# 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

# 🔥 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:

# 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:

# Start semua services
make docker-run

# Stop services
make docker-down

# Rebuild dan restart
make docker-rebuild

Production:

# 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

# 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:

// 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:

# 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

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

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

Response:

{
  "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

# 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

# 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

Reference in New Issue View Git Blame Copy Permalink