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