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.

📁 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

go mod tidy

3. Setup Environment Variables

cp .env.example .env
# Sesuaikan kredensial PostgreSQL, JWT Secret, dan GOOGLE_CLIENT_ID di file .env

4. Buat Database PostgreSQL

psql -U postgres -c "CREATE DATABASE cardverse;"

5. Jalankan Seeder Data Master (Opsional)

go run ./cmd/seed
# atau
make seed

6. Jalankan Server Development

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:

Authorization: Bearer <ACCESS_TOKEN>

🧪 Menjalankan Unit Test

Proyek ini dilengkapi dengan unit test menyeluruh (menggunakan mock repository tanpa memerlukan database asli saat testing):

# Jalankan semua unit test
go test ./...

# Jalankan test dengan detail & coverage
go test ./... -v -cover

# Shortcut Makefile
make test

README.md

Cardverse API