Zaku Backend API

Backend API untuk aplikasi Zaku, yaitu aplikasi tracking pemasukan dan pengeluaran. Project ini dibuat dengan Laravel dan menyediakan API untuk login, register, transaksi, dashboard cashflow, budget bulanan, dan pencatatan transaksi lewat chat.

README ini dibuat untuk dua tipe pembaca:

• Orang awam/non-IT: supaya paham project ini untuk apa dan cara menjalankannya secara minimal.
• IT/developer: supaya bisa setup, menjalankan, testing, dan integrasi API di local.

Gambaran Singkat

Project ini adalah backend, bukan aplikasi tampilan utama. Artinya project ini berjalan sebagai server API yang akan dipanggil oleh frontend/mobile app.

Contoh fungsi yang sudah tersedia:

• Register dan login user.
• Verifikasi email dengan kode.
• JWT Bearer token untuk akses endpoint yang butuh login.
• Transaksi: daftar transaksi, detail, hapus, statistik, kategori, tambah manual, dan tambah lewat chat.
• Dashboard ringkasan keuangan.
• Dokumentasi API otomatis lewat Scribe di /docs.

Teknologi

• PHP 8.1 atau lebih baru.
• Laravel 10.
• Composer.
• MySQL untuk penggunaan local normal.
• SQLite untuk testing.
• JWT Auth dengan tymon/jwt-auth.
• Scribe untuk dokumentasi API.
• Node.js dan NPM hanya diperlukan jika ingin menjalankan asset Vite.

Kebutuhan Sebelum Setup

Minimal yang perlu terpasang di komputer:

• PHP 8.1+.
• Composer.
• MySQL/MariaDB.
• Git.

Opsional:

• Node.js 18+ dan NPM, jika ingin menjalankan npm run dev.
• Postman/Insomnia, jika ingin mencoba API lebih nyaman.
• Mailpit atau SMTP lain, jika ingin menguji email sungguhan.

Untuk Windows, cara paling mudah biasanya memakai Laragon, XAMPP, atau instalasi PHP + Composer manual. Untuk macOS/Linux, bisa memakai PHP dari package manager, Homebrew, Docker, atau environment lain yang biasa dipakai tim.

Setup Local Paling Minimal

Ikuti langkah ini dari folder project:

cd backend

Jika posisi terminal sudah di folder ini, lanjut ke langkah berikutnya.

1. Install dependency PHP

composer install

Jika folder vendor sudah ada, perintah ini tetap aman dijalankan untuk memastikan dependency lengkap.

2. Buat file .env

cp .env.example .env

Di Windows PowerShell:

Copy-Item .env.example .env

3. Buat application key

php artisan key:generate

4. Buat JWT secret

php artisan jwt:secret

Pilih yes jika diminta overwrite JWT_SECRET.

5. Siapkan database MySQL

Buat database kosong bernama:

dompet_api

Contoh lewat MySQL CLI:

CREATE DATABASE dompet_api;

Lalu cek bagian database di .env:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=dompet_api
DB_USERNAME=root
DB_PASSWORD=

Sesuaikan DB_USERNAME dan DB_PASSWORD dengan komputer masing-masing.

6. Jalankan migrasi dan seeder

php artisan migrate --seed

Perintah ini membuat tabel database dan mengisi data awal, termasuk kategori transaksi dan akun demo.

7. Jalankan server local

php artisan serve

Jika berhasil, API berjalan di:

http://127.0.0.1:8000

Dokumentasi API bisa dibuka di:

http://127.0.0.1:8000/docs

OpenAPI spec tersedia di:

http://127.0.0.1:8000/docs.openapi

Akun Demo

Setelah menjalankan php artisan migrate --seed, akun demo tersedia:

Email: demo@zaku.test
Password: password

Gunakan akun ini untuk login dan mendapatkan JWT token.

Cara Mencoba API

Login

Request:

POST http://127.0.0.1:8000/api/v1/auth/login
Accept: application/json
Content-Type: application/json

Body:

{
  "email": "demo@zaku.test",
  "password": "password"
}

Response login akan berisi token. Simpan token itu untuk endpoint yang butuh login.

Mengakses Endpoint yang Butuh Login

Tambahkan header:

Authorization: Bearer TOKEN_DARI_LOGIN
Accept: application/json

Contoh ambil dashboard:

GET http://127.0.0.1:8000/api/v1/dashboard
Authorization: Bearer TOKEN_DARI_LOGIN
Accept: application/json

Endpoint Utama

Base URL local:

http://127.0.0.1:8000/api/v1

Endpoint public:

Method	Endpoint	Fungsi
POST	/auth/register	Register user baru
POST	/auth/login	Login dan ambil JWT token
POST	/auth/verify-email	Verifikasi email
POST	/auth/resend-verification	Kirim ulang kode verifikasi
	POST	/auth/forgot-password
	GET	/stats/public

Endpoint yang membutuhkan JWT token:

Method	Endpoint	Fungsi
GET	/auth/me	Ambil data user login
POST	/auth/refresh	Refresh token
POST	/auth/logout	Logout
POST	/auth/change-password	Ganti password
GET	/user/profile	Ambil profil dan statistik user
PUT	/user/profile	Update profil
PUT	/user/budget	Update budget bulanan
GET	/dashboard	Ambil dashboard keuangan
GET	/transactions	Ambil daftar transaksi
POST	/transactions	Catat pemasukan/pengeluaran manual
GET	/transactions/stats	Ambil statistik transaksi
GET	/transactions/categories	Ambil ringkasan kategori
GET	/transactions/{id}	Detail transaksi
DELETE	/transactions/{id}	Hapus transaksi
POST	/transactions/chat	Catat transaksi dari pesan chat parser local
	POST	/ai/chat
	GET	/changelogs

Dokumentasi lengkap dengan contoh request/response ada di /docs.

Konfigurasi .env Penting

Minimal untuk local:

APP_NAME="Zaku Backend API"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://127.0.0.1:8000
SCRIBE_BASE_URL=http://127.0.0.1:8000

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=dompet_api
DB_USERNAME=root
DB_PASSWORD=

JWT_SECRET=isi_dari_php_artisan_jwt_secret
JWT_ALGO=HS256

Untuk email local, default .env.example memakai Mailpit:

MAIL_MAILER=smtp
MAIL_HOST=mailpit
MAIL_PORT=1025

Jika tidak memakai Mailpit, untuk local bisa diganti menjadi:

MAIL_MAILER=log

Dengan MAIL_MAILER=log, isi email akan masuk ke file log Laravel, bukan dikirim ke inbox.

Fitur Chat dan AI

Ada dua endpoint chat:

• /api/v1/transactions/chat: parser local, tidak butuh API key AI.
• /api/v1/ai/chat: mencoba AI provider jika API key tersedia, lalu fallback ke parser local.

Konfigurasi opsional:

GROQ_API_KEY=
GROQ_MODEL=llama-3.1-8b-instant
GEMINI_API_KEY=
GEMINI_MODEL=gemini-2.0-flash

Untuk local minimal, bagian ini boleh dikosongkan.

AI parser juga menangani bahasa Indonesia informal: dapat/dapet/dpt = income. Keyword override post-processing memastikan akurasi terlepas dari output LLM.

Menjalankan Test

php artisan test

Testing memakai SQLite in-memory dari phpunit.xml, jadi tidak mengubah database MySQL local.

Changelog Seeder

Untuk mengisi data changelog:

php artisan db:seed --class=ChangelogSeeder

Perintah ini menambahkan data awal changelog ke database. Bisa dijalankan kapan saja jika ingin memperbarui data changelog.

Perintah yang Sering Dipakai Developer

composer install
php artisan key:generate
php artisan jwt:secret
php artisan migrate
php artisan migrate --seed
php artisan migrate:fresh --seed
php artisan serve
php artisan route:list --path=api
php artisan test
php artisan db:seed --class=ChangelogSeeder

Jika perlu asset frontend bawaan Laravel:

npm install
npm run dev

Untuk backend API saja, npm install tidak wajib.

Struktur Folder Penting

app/
  Http/Controllers/Api/    Controller API
  Http/Requests/           Validasi request
  Http/Resources/          Format response resource
  Models/                  Model database
  Services/                Logic bisnis dan parser transaksi
  Services/AiTransactionParserService.php  AI chat parser dengan Groq/Gemini
  Traits/ApiResponse.php   Format response API konsisten

database/
  migrations/              Struktur tabel database
  seeders/                 Data awal/demo

routes/
  api.php                  Semua route API utama

config/
  jwt.php                  Konfigurasi JWT
  scribe.php               Konfigurasi dokumentasi API

Format Response Umum

Sebagian besar endpoint memakai format:

{
  "status": "success",
  "message": "Pesan response",
  "data": {}
}

Jika error, response biasanya:

{
  "status": "error",
  "message": "Pesan error",
  "errors": {}
}

Troubleshooting

composer install gagal

Pastikan PHP dan Composer sudah terpasang:

php -v
composer -V

Pastikan extension PHP yang umum untuk Laravel aktif, seperti mbstring, openssl, pdo_mysql, tokenizer, xml, ctype, json, dan fileinfo.

php artisan migrate --seed gagal koneksi database

Cek MySQL sudah menyala dan konfigurasi .env benar:

DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=dompet_api
DB_USERNAME=root
DB_PASSWORD=

Jika mengganti .env, jalankan:

php artisan config:clear

Error JWT secret is not set

Jalankan:

php artisan jwt:secret
php artisan config:clear

Endpoint protected selalu Unauthorized

Pastikan header token benar:

Authorization: Bearer TOKEN_DARI_LOGIN
Accept: application/json

Token harus berasal dari endpoint /api/v1/auth/login.

Dokumentasi /docs tidak sesuai URL local

Cek .env:

SCRIBE_BASE_URL=http://127.0.0.1:8000

Lalu bersihkan config:

php artisan config:clear

Catatan untuk Deployment

Untuk production, minimal ubah:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://domain-api-anda.com
SCRIBE_BASE_URL=https://domain-api-anda.com

Gunakan database production, SMTP production, HTTPS, dan JWT_SECRET yang kuat. Jangan commit file .env ke repository.

Dokumentasi Tambahan

Beberapa dokumen project lain tersedia di repository:

• PRD-Backend.md: kebutuhan dan rancangan produk backend.
• TASK_LIST.md: daftar task project.
• CHANGELOG.md: catatan perubahan.
• GIT_WORKFLOW.md: standar git workflow.
• docs/: dokumentasi internal issue, implementation, dan pull request.