178 lines
8.6 KiB
Markdown
178 lines
8.6 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
|
||
|
|
│ │ ├── sets/ # Logo/gambar Expansion Set
|
||
|
|
│ │ └── elements/ # Ikon elemen kartu (Grass, Fire, Water, dst)
|
||
|
|
├── .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, JWT Secret, dan GOOGLE_CLIENT_ID di file .env
|
||
|
|
```
|
||
|
|
|
||
|
|
### 4. Buat Database PostgreSQL
|
||
|
|
```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
|
||
|
|
|
||
|
|
### 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 |
|
||
|
|
| GET | `/api/v1/auth/verify-email` | ❌ Public | Verifikasi email user via token |
|
||
|
|
| POST | `/api/v1/auth/forgot-password` | ❌ Public | Minta token 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`)
|
||
|
|
|
||
|
|
| Method | Endpoint | Auth | Deskripsi |
|
||
|
|
| ------ | ------------------------------- | :-------------------: | ----------------------------------------------------- |
|
||
|
|
| GET | `/api/v1/series` | ❌ Public | Get semua Series TCG |
|
||
|
|
| PUT | `/api/v1/series/:id` | 🔒 Admin/Superadmin | Update nama Series & upload file gambar (`.webp`) |
|
||
|
|
| 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`) |
|
||
|
|
| PUT | `/api/v1/sets/:id` | 🔒 Admin/Superadmin | Update Expansion Set & upload logo/gambar |
|
||
|
|
| GET | `/api/v1/series-set-masters/:id`| ❌ Public | Get detail 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/:id` | ❌ Public | Get detail kartu TCG berdasarkan ID |
|
||
|
|
| PUT | `/api/v1/cards/:id` | 🔒 Admin/Superadmin | Update 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.
|