forked from rachmadiyanti.annisa.3004/service_antrean
first commit
This commit is contained in:
569
README.md
Normal file
569
README.md
Normal file
@@ -0,0 +1,569 @@
|
||||
|
||||
# 🚀 API Service - CURD Management System
|
||||
|
||||
> **Sistem manajemen retribusi modern dengan arsitektur bersih untuk pengelolaan data retribusi pemerintah**
|
||||
|
||||
## 📑 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
|
||||
|
||||
- **🔒 JWT Authentication** - Sistem autentikasi dengan Keycloak integration
|
||||
- **📋 Retribusi Management** - CRUD lengkap untuk data retribusi
|
||||
- **🔍 Dynamic Filtering** - Filter dan pencarian data retribusi secara dinamis
|
||||
- **📊 Advanced Search** - Pencarian dengan multiple fields dan operators
|
||||
- **🏥 BPJS Integration** - Integrasi dengan layanan kesehatan BPJS
|
||||
- **🩺 SATUSEHAT Integration** - Integrasi dengan platform kesehatan SATUSEHAT
|
||||
- **📖 API Documentation** - Swagger/OpenAPI yang interaktif
|
||||
|
||||
### Developer Experience
|
||||
|
||||
- **🔥 Hot Reload** - Development dengan auto-restart
|
||||
- **🐳 Docker Ready** - Deployment yang mudah
|
||||
- **⚡ Code Generator** - Tools untuk generate handler dan model
|
||||
- **🧪 Testing Suite** - Unit dan integration tests
|
||||
- **📊 Health Monitoring** - Monitoring kesehatan aplikasi
|
||||
- **🗄️ Multi Database** - Support PostgreSQL, MySQL, dan MongoDB
|
||||
|
||||
***
|
||||
|
||||
## 🏗️ Arsitektur
|
||||
|
||||
### Clean Architecture Layers
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Presentation Layer │ ← handlers/, routes/
|
||||
├─────────────────────────────────────┤
|
||||
│ Application Layer │ ← middleware/, services/
|
||||
├─────────────────────────────────────┤
|
||||
│ Domain Layer │ ← models/, validation/
|
||||
├─────────────────────────────────────┤
|
||||
│ Infrastructure Layer │ ← database/, external APIs
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Struktur Project
|
||||
|
||||
```
|
||||
api-service/
|
||||
├── 📁 cmd/
|
||||
│ ├── api/main.go # 🚪 Entry point aplikasi
|
||||
│ └── logging/main.go # 🔍 Logging service
|
||||
├── 📁 internal/ # 🏠 Core business logic
|
||||
│ ├── config/ # ⚙️ Configuration management
|
||||
│ ├── database/ # 🗄️ Database connections
|
||||
│ ├── handlers/ # 🎮 HTTP controllers
|
||||
│ │ ├── auth/ # 🔐 Authentication handlers
|
||||
│ │ ├── healthcheck/ # 💚 Health check handlers
|
||||
│ │ └── retribusi/ # 📋 Retribusi handlers
|
||||
│ ├── middleware/ # 🛡️ Auth & validation middleware
|
||||
│ ├── models/ # 📊 Data structures
|
||||
│ │ ├── auth/ # 👤 Auth models
|
||||
│ │ └── retribusi/ # 📋 Retribusi models
|
||||
│ ├── routes/ # 🛣️ API routing
|
||||
│ ├── services/ # 💼 Business logic services
|
||||
│ │ └── auth/ # 🔐 Auth services
|
||||
│ ├── utils/ # 🛠️ Utility functions
|
||||
│ │ ├── filters/ # 🔍 Dynamic filtering
|
||||
│ │ └── validation/ # ✅ Data validation
|
||||
│ └── server/ # 🌐 HTTP server setup
|
||||
├── 📁 docs/ # 📚 Documentation
|
||||
├── 📁 examples/ # 💡 Example files
|
||||
├── 📁 scripts/ # 📜 Automation scripts
|
||||
└── 📁 tools/ # 🔧 Development tools
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## ⚡ Quick Start
|
||||
|
||||
### 1️⃣ Setup Environment (2 menit)
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone <repository-url>
|
||||
cd api-service
|
||||
|
||||
# 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
|
||||
```
|
||||
|
||||
### Update Swagger Documentation
|
||||
|
||||
```bash
|
||||
swag init -g cmd/api/main.go -o docs/
|
||||
```
|
||||
|
||||
### 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/retribusi \
|
||||
-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
|
||||
|
||||
#### System Information
|
||||
|
||||
| Method | Endpoint | Deskripsi |
|
||||
| :-- | :-- | :-- |
|
||||
| `GET` | `/api/sistem/databases` | Informasi database connections |
|
||||
|
||||
#### Retribusi Management
|
||||
|
||||
| Method | Endpoint | Deskripsi |
|
||||
| :-- | :-- | :-- |
|
||||
| `GET` | `/api/v1/retribusi` | List semua retribusi dengan pagination |
|
||||
| `GET` | `/api/v1/retribusi/dynamic` | Query retribusi dengan filter dinamis |
|
||||
| `GET` | `/api/v1/retribusi/search` | Pencarian retribusi advanced |
|
||||
| `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 (soft delete) |
|
||||
|
||||
#### 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=rumah%20sakit&limit=20&offset=0
|
||||
```
|
||||
|
||||
### 🏥 External Integrations
|
||||
|
||||
#### BPJS Integration
|
||||
|
||||
| Method | Endpoint | Deskripsi |
|
||||
| :-- | :-- | :-- |
|
||||
| `GET` | `/api/v1/bpjs/peserta/:no` | Data peserta BPJS |
|
||||
| `GET` | `/api/v1/bpjs/rujukan/:no` | Data rujukan |
|
||||
|
||||
#### SATUSEHAT Integration
|
||||
|
||||
| Method | Endpoint | Deskripsi |
|
||||
| :-- | :-- | :-- |
|
||||
| `GET` | `/api/v1/satusehat/patient/:id` | Data pasien |
|
||||
| `POST` | `/api/v1/satusehat/encounter` | Buat encounter baru |
|
||||
|
||||
***
|
||||
|
||||
## 🛠️ Development
|
||||
|
||||
### Development Commands
|
||||
|
||||
```bash
|
||||
# 🔥 Development dengan hot reload
|
||||
make watch
|
||||
|
||||
# 🏃 Run server
|
||||
make run
|
||||
|
||||
# 🧪 Testing
|
||||
make test # Unit tests
|
||||
make itest # Integration tests
|
||||
|
||||
# 🐳 Docker operations
|
||||
make docker-run # Start all services
|
||||
make docker-down # Stop all services
|
||||
|
||||
# 🔍 Code quality
|
||||
make build # Build application
|
||||
make clean # Clean build artifacts
|
||||
```
|
||||
|
||||
### Environment Configuration
|
||||
|
||||
**📁 .env File:**
|
||||
|
||||
```bash
|
||||
# Server Configuration
|
||||
PORT=8080
|
||||
GIN_MODE=debug
|
||||
|
||||
# Database Configuration
|
||||
DB_CONNECTION=postgres
|
||||
DB_HOST=localhost
|
||||
DB_PORT=5432
|
||||
DB_USERNAME=postgres
|
||||
DB_PASSWORD=postgres
|
||||
DB_DATABASE=api_service
|
||||
|
||||
# PostgreSQL Satudata Database
|
||||
POSTGRES_SATUDATA_CONNECTION=postgres
|
||||
POSTGRES_SATUDATA_HOST=localhost
|
||||
POSTGRES_SATUDATA_PORT=5432
|
||||
POSTGRES_SATUDATA_USERNAME=postgres
|
||||
POSTGRES_SATUDATA_PASSWORD=postgres
|
||||
POSTGRES_SATUDATA_DATABASE=satu_db
|
||||
|
||||
# MongoDB Configuration
|
||||
MONGODB_MONGOHL7_CONNECTION=mongodb
|
||||
MONGODB_MONGOHL7_HOST=localhost
|
||||
MONGODB_MONGOHL7_PORT=27017
|
||||
MONGODB_MONGOHL7_USER=admin
|
||||
MONGODB_MONGOHL7_PASS=password
|
||||
|
||||
# MySQL Medical Database
|
||||
MYSQL_MEDICAL_CONNECTION=mysql
|
||||
MYSQL_MEDICAL_HOST=localhost
|
||||
MYSQL_MEDICAL_PORT=3306
|
||||
MYSQL_MEDICAL_USERNAME=user
|
||||
MYSQL_MEDICAL_PASSWORD=password
|
||||
MYSQL_MEDICAL_DATABASE=healtcare_database
|
||||
|
||||
# JWT Configuration
|
||||
JWT_SECRET=your-super-secret-key-change-in-production
|
||||
|
||||
# Keycloak Configuration
|
||||
KEYCLOAK_ISSUER=https://auth.rssa.top/realms/sandbox
|
||||
KEYCLOAK_AUDIENCE=nuxtsim-pendaftaran
|
||||
KEYCLOAK_JWKS_URL=https://auth.rssa.top/realms/sandbox/protocol/openid-connect/certs
|
||||
KEYCLOAK_ENABLED=true
|
||||
|
||||
# BPJS Configuration
|
||||
BPJS_BASEURL=https://apijkn.bpjs-kesehatan.go.id/vclaim-dev
|
||||
BPJS_CONSID=52667757
|
||||
BPJS_USERKEY=4cf1cbef811314fvdgrc008440bbe9ef9ba789e482
|
||||
BPJS_SECRETKEY=1bV36ASDQQ3512D
|
||||
|
||||
|
||||
```
|
||||
|
||||
### Code Generation
|
||||
|
||||
**Generate Handler untuk Retribusi:**
|
||||
|
||||
```bash
|
||||
# Generate handler dasar
|
||||
go run tools/general/generate-handler.go retribusi get post put delete
|
||||
|
||||
# Generate dengan fitur advanced
|
||||
go run tools/general/generate-handler.go retribusi get post put delete dynamic search stats
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## 🚀 Deployment
|
||||
|
||||
### 🐳 Docker Deployment
|
||||
|
||||
**Development:**
|
||||
|
||||
```bash
|
||||
# Start semua services
|
||||
make docker-run
|
||||
|
||||
# Stop services
|
||||
make docker-down
|
||||
```
|
||||
|
||||
**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
|
||||
|
||||
# Start server
|
||||
./main
|
||||
```
|
||||
|
||||
### 📋 Environment Variables untuk Production
|
||||
|
||||
```bash
|
||||
# Server Configuration
|
||||
APP_ENV=production
|
||||
PORT=8080
|
||||
GIN_MODE=release
|
||||
|
||||
# Database Configuration
|
||||
DB_CONNECTION=postgres
|
||||
DB_HOST=10.10.123.165
|
||||
DB_PORT=5432
|
||||
DB_USERNAME=stim
|
||||
DB_PASSWORD=stim*RS54
|
||||
DB_DATABASE=satu_db
|
||||
|
||||
# Security
|
||||
JWT_SECRET=your-production-secret-key
|
||||
KEYCLOAK_ENABLED=true
|
||||
|
||||
# External Services
|
||||
BPJS_BASEURL=https://apijkn.bpjs-kesehatan.go.id/vclaim-rest
|
||||
BRIDGING_SATUSEHAT_BASE_URL=https://api-satusehat.kemkes.go.id/fhir-r4/v1
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## 📚 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 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 retribusi data
|
||||
curl -H "Authorization: Bearer $TOKEN" \
|
||||
http://localhost:8080/api/v1/retribusi
|
||||
|
||||
# Dynamic filtering
|
||||
curl -H "Authorization: Bearer $TOKEN" \
|
||||
"http://localhost:8080/api/v1/retribusi/dynamic?filter[Jenis][_eq]=RETRIBUSI%20PELAYANAN%20KESEHATAN"
|
||||
```
|
||||
|
||||
### 🔍 Health Monitoring
|
||||
|
||||
```bash
|
||||
# Basic health check
|
||||
curl http://localhost:8080/api/sistem/health
|
||||
|
||||
# Database status
|
||||
curl http://localhost:8080/api/sistem/databases
|
||||
|
||||
# System info
|
||||
curl http://localhost:8080/api/sistem/info
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "healthy",
|
||||
"timestamp": "2025-01-10T05:39:00Z",
|
||||
"services": {
|
||||
"database": "connected",
|
||||
"keycloak": "accessible",
|
||||
"bpjs_api": "accessible",
|
||||
"satusehat_api": "accessible"
|
||||
},
|
||||
"version": "1.0.0"
|
||||
}
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## 🚨 Troubleshooting
|
||||
|
||||
### Masalah Umum
|
||||
|
||||
**❌ Database Connection Error**
|
||||
|
||||
```bash
|
||||
# Cek status database
|
||||
make docker-run
|
||||
|
||||
# Check logs
|
||||
docker logs api-service
|
||||
|
||||
# Verify environment variables
|
||||
cat .env | grep DB_
|
||||
```
|
||||
|
||||
**❌ Authentication Error**
|
||||
|
||||
- 🔄 Pastikan Keycloak service berjalan
|
||||
- ✅ Cek KEYCLOAK_ISSUER URL
|
||||
- 📝 Format token harus: `Bearer <token>`
|
||||
|
||||
**❌ Dynamic Filter Error**
|
||||
|
||||
- ✅ Pastikan field name sesuai dengan database
|
||||
- 🔍 Cek syntax filter: `filter[field][operator]=value`
|
||||
- 📝 Operator yang didukung: `_eq`, `_neq`, `_gt`, `_lt`, `_contains`
|
||||
|
||||
### Debug Mode
|
||||
|
||||
```bash
|
||||
# Enable debug logging
|
||||
export GIN_MODE=debug
|
||||
|
||||
# Run dengan verbose output
|
||||
make run
|
||||
|
||||
# Monitor dengan hot reload
|
||||
make watch
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## 🎯 Next Steps
|
||||
|
||||
### 📋 Development Roadmap
|
||||
|
||||
- [ ] ✅ **Setup environment selesai**
|
||||
- [ ] ✅ **Implementasi retribusi management**
|
||||
- [ ] ✅ **Setup authentication dengan Keycloak**
|
||||
- [ ] 🔄 **Integrasi BPJS dan SATUSEHAT**
|
||||
- [ ] 🔄 **Testing dan validation**
|
||||
- [ ] 🔄 **Setup monitoring dan logging**
|
||||
- [ ] 🔄 **Deploy ke production**
|
||||
|
||||
### 🚀 Advanced Features
|
||||
|
||||
- **📊 Real-time Dashboard**
|
||||
- **🔒 Enhanced Security (Rate limiting, CORS)**
|
||||
- **📈 Performance Monitoring**
|
||||
- **🌐 API Versioning**
|
||||
- **📱 Mobile SDK Integration**
|
||||
|
||||
***
|
||||
|
||||
**⚡ Total setup time: 5 menit | 🔧 Generate Handler: 30 detik | 🧪 Testing: Langsung via Swagger**
|
||||
|
||||
> **💡 Pro Tip:** Gunakan `make help` untuk melihat semua command yang tersedia
|
||||
|
||||
***
|
||||
|
||||
Reference in New Issue
Block a user