Zent API

REST API cho nền tảng thương mại điện tử, xây dựng trên Laravel 12 với kiến trúc Domain-Oriented.

Yêu cầu

• PHP 8.4+
• PostgreSQL 14+
• Redis (Docker hoặc local)
• Composer
• Node.js (chỉ cần nếu build frontend/admin)

Cài đặt

1. Clone và cài dependencies

git clone https://github.com/flourine95/zent-api
cd zent-api
composer install

2. Cấu hình môi trường

cp .env.example .env
php artisan key:generate

Mở .env và cấu hình các giá trị sau:

Database (PostgreSQL):

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=zent_api
DB_USERNAME=postgres
DB_PASSWORD=your_password

Redis:

REDIS_CLIENT=predis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=null

Queue & Cache:

QUEUE_CONNECTION=database
CACHE_STORE=database

Mail (dùng log để test local):

MAIL_MAILER=log
MAIL_FROM_ADDRESS="hello@example.com"
MAIL_FROM_NAME="Zent"

Shipping providers (optional):

GHTK_API_TOKEN=your_token
GHN_TOKEN=your_token
GHN_SHOP_ID=your_shop_id

3. Khởi động Redis và PostgreSQL

Tạo network dùng chung trước:

docker network create zent-network

PostgreSQL:

docker run -d --name zent-postgres --network zent-network \
  -p 5432:5432 \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=zent_api \
  --restart unless-stopped \
  postgres:alpine

Redis:

docker run -d --name zent-redis --network zent-network \
  -p 6379:6379 \
  --restart unless-stopped \
  redis:alpine redis-server --appendonly yes

Lần sau nếu container bị stop:

docker start zent-postgres zent-redis

4. Migrate và seed database

php artisan migrate --seed

Hoặc reset hoàn toàn:

php artisan migrate:fresh --seed

Seed tạo sẵn các tài khoản mặc định:

Email	Password	Role
admin@example.com	password	admin
customer@example.com	password	customer

Chạy dự án

Cần mở 3 terminal chạy song song:

Terminal 1 — API server:

php artisan serve

Terminal 2 — Queue worker (xử lý order persistence, email, notifications):

php artisan queue:work --tries=3

Terminal 3 — Scheduler (auto-cancel đơn hết hạn, release reservations):

php artisan schedule:work

API base URL: http://localhost:8000/api/v1

Kiến trúc

Dự án dùng Domain-Oriented Architecture với 3 layer:

app/App/            → HTTP layer (Controllers, FormRequests)
app/Domain/         → Business logic (Actions, DTOs, Exceptions, Repository Interfaces)
app/Infrastructure/ → Database & external services (Eloquent Models, Repositories, Jobs)

Chi tiết kỹ thuật và các quyết định thiết kế xem tại docs/roadmap.md.

Các lệnh hữu ích

# Xem tất cả routes
php artisan route:list

# Chạy tests
php artisan test --compact

# Format code
vendor/bin/pint

# Xem failed jobs
php artisan queue:failed

# Retry failed jobs
php artisan queue:retry all