194 lines
9.9 KiB
Markdown
194 lines
9.9 KiB
Markdown
# Cardverse API
|
|
|
|
Cardverse adalah backend API RESTful berkinerja tinggi untuk aplikasi trading card / Pokemon TCG, dibangun menggunakan **Go + Gin Framework**, PostgreSQL (GORM), JWT Authentication, Refresh Token Rotation, Google OAuth, serta manajemen aset media statis.
|
|
|
|
Disusun dengan arsitektur **per-module** (*modular monolith*) sehingga bersih, teruji (*testable*), dan mudah dikembangkan secara berkelanjutan.
|
|
|
|
> Aturan penulisan kode, konvensi penamaan, dan clean code best practice ada di [`CONVENTION.md`](./CONVENTION.md).
|
|
|
|
---
|
|
|
|
## 📁 Struktur Folder Project
|
|
|
|
```
|
|
cardverse/
|
|
├── cmd/
|
|
│ ├── api/
|
|
│ │ └── main.go # Entry point server HTTP API
|
|
│ └── seed/
|
|
│ └── main.go # Entry point seeder data master
|
|
├── config/
|
|
│ └── config.go # Memuat environment variables (.env)
|
|
├── internal/
|
|
│ ├── database/
|
|
│ │ ├── database.go # Koneksi DB PostgreSQL + AutoMigrate GORM
|
|
│ │ └── seeder.go # Seed data master (Series, Sets, Cards, Admin)
|
|
│ ├── middleware/
|
|
│ │ ├── auth.go # Auth middleware (JWT + RequireRoles)
|
|
│ │ ├── cors.go # CORS middleware
|
|
│ │ ├── logger.go # Request logger dengan auto-redact data sensitif
|
|
│ │ └── rate_limiter.go # Rate limiter per-IP (Token Bucket)
|
|
│ ├── modules/ # Modular domain features
|
|
│ │ ├── auth/ # Login, Register, Google OAuth, Refresh Token, Reset Password
|
|
│ │ ├── user/ # Profile, Avatar Upload, Admin User Management
|
|
│ │ ├── seriessetmaster/ # Data Master Series & Set Expansion
|
|
│ │ └── cardmaster/ # Data Master Kartu TCG (HP, Attacks, Battle, Element)
|
|
│ ├── router/
|
|
│ │ └── router.go # Pendaftaran route module & static file serving
|
|
│ └── pkg/ # Utility & Helper generik
|
|
│ ├── response/ # Format JSON response standar + pagination
|
|
│ ├── logger/ # Logger terpusat
|
|
│ ├── validator/ # Error translator validasi DTO per-field
|
|
│ └── utils/ # JWT, Hash Password, String Slug/Underscore, Image/File utils
|
|
├── public/ # Penyimpanan Aset Gambar & Media Statis
|
|
│ ├── images/
|
|
│ │ ├── avatars/ # Foto profil user
|
|
│ │ ├── series/ # Banner/gambar Series
|
|
│ │ ├── elements/ # Ikon elemen kartu (Grass, Fire, Water, dst)
|
|
│ │ ├── evolusi-mega/ # Gambar kartu seri Evolusi Mega
|
|
│ │ ├── matahari-bulan/ # Gambar kartu seri Matahari & Bulan
|
|
│ │ ├── pedang-perisai/ # Gambar kartu seri Pedang & Perisai
|
|
│ │ └── scarlet-violet/ # Gambar kartu seri Scarlet & Violet
|
|
├── .env.example
|
|
├── CONVENTION.md # Aturan penulisan kode & standar proyek
|
|
├── Makefile # Command shortcuts (dev, test, build, seed)
|
|
├── go.mod
|
|
└── README.md
|
|
```
|
|
|
|
---
|
|
|
|
## ⚡ Cara Menjalankan
|
|
|
|
### 1. Prasyarat
|
|
- Go 1.22+
|
|
- PostgreSQL
|
|
|
|
### 2. Install Dependency
|
|
```bash
|
|
go mod tidy
|
|
```
|
|
|
|
### 3. Setup Environment Variables
|
|
```bash
|
|
cp .env.example .env
|
|
# Sesuaikan kredensial PostgreSQL (DB_NAME=cardverse), JWT Secret, dan GOOGLE_CLIENT_ID di file .env
|
|
```
|
|
|
|
### 4. Buat Database PostgreSQL
|
|
Buat database PostgreSQL baru dengan nama **`cardverse`**:
|
|
```bash
|
|
psql -U postgres -c "CREATE DATABASE cardverse;"
|
|
```
|
|
|
|
### 5. Jalankan Seeder Data Master (Opsional)
|
|
```bash
|
|
go run ./cmd/seed
|
|
# atau
|
|
make seed
|
|
```
|
|
|
|
### 6. Jalankan Server Development
|
|
```bash
|
|
go run ./cmd/api
|
|
# atau dengan Hot-Reload (Air):
|
|
make dev
|
|
```
|
|
Server akan berjalan di `http://localhost:8080`.
|
|
|
|
---
|
|
|
|
## 🛠️ Daftar Endpoint API
|
|
|
|
### Server Health Check (`/health`)
|
|
|
|
| Method | Endpoint | Auth | Deskripsi |
|
|
| ------ | --------- | :-------: | --------------------------- |
|
|
| GET | `/health` | ❌ Public | Cek status kesehatan server |
|
|
|
|
### 1. Authentication Module (`/api/v1/auth`)
|
|
|
|
| Method | Endpoint | Auth | Deskripsi |
|
|
| ------ | ------------------------------- | :---------: | ----------------------------------------------------------- |
|
|
| POST | `/api/v1/auth/register` | ❌ Public | Registrasi akun baru (Kirim email konfirmasi) |
|
|
| POST | `/api/v1/auth/login` | ❌ Public | Login via email & password (mengembalikan Access & Refresh) |
|
|
| POST | `/api/v1/auth/google` | ❌ Public | Login / Auto-Register via Google OAuth (ID Token) |
|
|
| POST | `/api/v1/auth/refresh-token` | ❌ Public | Minta Access Token baru & rotate Refresh Token |
|
|
| POST | `/api/v1/auth/logout` | ❌ Public | Logout & mencabut Refresh Token |
|
|
| POST | `/api/v1/auth/verify-email` | ❌ Public | Verifikasi email user via token OTP |
|
|
| POST | `/api/v1/auth/forgot-password` | ❌ Public | Minta token/OTP reset password |
|
|
| POST | `/api/v1/auth/reset-password` | ❌ Public | Reset password akun |
|
|
|
|
### 2. User Module (`/api/v1/users`)
|
|
|
|
| Method | Endpoint | Auth | Deskripsi |
|
|
| ------ | --------------------------- | :-------------------: | ----------------------------------------------------- |
|
|
| GET | `/api/v1/users/me` | ✅ Logged In | Ambil profil user yang sedang login |
|
|
| PUT | `/api/v1/users/me` | ✅ Logged In | Update nama profil user |
|
|
| POST | `/api/v1/users/me/avatar` | ✅ Logged In | Upload file gambar avatar (`multipart/form-data`) |
|
|
| GET | `/api/v1/users` | 🔒 Admin/Superadmin | Get daftar semua user (Paginasi & Search) |
|
|
| POST | `/api/v1/users` | 🔒 Admin/Superadmin | Buat user baru |
|
|
| GET | `/api/v1/users/:id` | 🔒 Admin/Superadmin | Ambil detail user berdasarkan ID |
|
|
| PUT | `/api/v1/users/:id` | 🔒 Admin/Superadmin | Update data user |
|
|
| PUT | `/api/v1/users/:id/suspend` | 🔒 Admin/Superadmin | Suspensikan akun user |
|
|
| PUT | `/api/v1/users/:id/unsuspend`| 🔒 Admin/Superadmin | Cabut suspensi akun user |
|
|
| DELETE | `/api/v1/users/:id` | 🔒 Admin/Superadmin | Hapus user |
|
|
|
|
### 3. Series & Set Master Module (`/api/v1/series`, `/api/v1/sets`, `/api/v1/series-set-masters`)
|
|
|
|
| Method | Endpoint | Auth | Deskripsi |
|
|
| ------ | ------------------------------- | :-------------------: | ----------------------------------------------------- |
|
|
| GET | `/api/v1/series` | ❌ Public | Get semua Series TCG |
|
|
| POST | `/api/v1/series` | 🔒 Admin/Superadmin | Buat Series TCG baru |
|
|
| PUT | `/api/v1/series/:id` | 🔒 Admin/Superadmin | Update Series TCG & gambar |
|
|
| GET | `/api/v1/sets` | ❌ Public | Get semua Expansion Set (Filter by search/parent_id) |
|
|
| GET | `/api/v1/sets/code/:code` | ❌ Public | Get detail Set berdasarkan `set_code` (misal `M-P`) |
|
|
| POST | `/api/v1/sets` | 🔒 Admin/Superadmin | Buat Expansion Set baru |
|
|
| PUT | `/api/v1/sets/:id` | 🔒 Admin/Superadmin | Update Expansion Set & gambar |
|
|
| GET | `/api/v1/series-set-masters/:id`| ❌ Public | Get detail Series/Set Master berdasarkan ID |
|
|
| DELETE | `/api/v1/series-set-masters/:id`| 🔒 Admin/Superadmin | Hapus Series/Set Master berdasarkan ID |
|
|
|
|
### 4. Card Master Module (`/api/v1/cards`)
|
|
|
|
| Method | Endpoint | Auth | Deskripsi |
|
|
| ------ | ----------------------- | :-------------------: | ----------------------------------------------------- |
|
|
| GET | `/api/v1/cards` | ❌ Public | Get daftar kartu TCG (Paginasi, Filter & Search) |
|
|
| GET | `/api/v1/cards/elements`| ❌ Public | Get daftar tipe elemen kartu (Fire, Water, Grass, dll)|
|
|
| GET | `/api/v1/cards/:id` | ❌ Public | Get detail kartu TCG berdasarkan ID |
|
|
| POST | `/api/v1/cards` | 🔒 Admin/Superadmin | Buat data kartu master baru |
|
|
| PUT | `/api/v1/cards/:id` | 🔒 Admin/Superadmin | Update data kartu master |
|
|
| DELETE | `/api/v1/cards/:id` | 🔒 Admin/Superadmin | Hapus data kartu master |
|
|
|
|
---
|
|
|
|
## 🔒 Otentikasi & Header
|
|
|
|
Untuk endpoint yang memerlukan otentikasi (`Auth Required`), sertakan Access Token pada HTTP Header:
|
|
|
|
```http
|
|
Authorization: Bearer <ACCESS_TOKEN>
|
|
```
|
|
|
|
---
|
|
|
|
## 🧪 Menjalankan Unit Test
|
|
|
|
Proyek ini dilengkapi dengan unit test menyeluruh (menggunakan *mock repository* tanpa memerlukan database asli saat testing):
|
|
|
|
```bash
|
|
# Jalankan semua unit test
|
|
go test ./...
|
|
|
|
# Jalankan test dengan detail & coverage
|
|
go test ./... -v -cover
|
|
|
|
# Shortcut Makefile
|
|
make test
|
|
```
|
|
|
|
---
|
|
|
|
## 📄 Lisensi
|
|
|
|
© Cardverse Development Team. Hak Cipta Dilindungi Undang-Undang.
|