portal-api/CHANGELOG.md

# 📋 Changelog - Service Registration & Payment Optimization

**Date:** 2026-02-11  
**Version:** 2.0.0  
**Type:** Feature Addition + Logic Optimization

---

## 🔄 UPDATE (Latest)

### Di Chuyển Sang Client API Routes

**Lý do:** Tách biệt API cho client ra file `client.php` để dễ quản lý hơn.

**Thay đổi:**
- ✅ **Xóa:** Service routes khỏi `routes/api.php`
- ✅ **Thêm:** Tất cả service APIs vào `routes/client.php`
- ✅ **Merge:** ServiceController V1 → Service/ServiceController
- ✅ **Thêm:** Product → Addons relationship

**Routes mới:**
```
/v1/services/
├── get-list (public)
├── {slug} (public)
└── [auth: api.auth]
    ├── cart
    ├── cart/add
    ├── cart/{id} (UPDATE/DELETE)
    ├── checkout
    ├── orders
    ├── orders/{id}
    └── orders/{id}/pay
```

**Docs:** Xem [UPDATE_CLIENT_ROUTES.md](./docs/UPDATE_CLIENT_ROUTES.md)

---

## 🎯 Vấn Đề Được Giải Quyết

### 1. ❌ **THIẾU API đăng ký service**
- Trước đây: Chỉ có web routes cho cart/order
- Bây giờ: ✅ Có đầy đủ RESTful API cho mobile/SPA

### 2. ❌ **Cart không lưu được addons**
- Trước đây: User phải chọn lại addons mỗi lần checkout
- Bây giờ: ✅ Addons được lưu trong `cart_addons` table

### 3. ❌ **Logic thanh toán chưa tối ưu**
- Trước đây: Tạo VM trước → Trừ tiền sau (có vấn đề)
- Bây giờ: ✅ Trừ tiền trước → Tạo VM sau (có refund nếu fail)

---

## 📁 Files Đã Thêm Mới

### Database Migrations
```
database/migrations/
  └── 2026_02_11_000001_create_cart_addons_table.php ✨ NEW
```

### Models
```
app/Models/
  ├── CartAddon.php ✨ NEW
  └── Cart.php (updated - thêm relationship addons)
```

### Controllers
```
app/Http/Controllers/Api/V1/
  └── ServiceController.php ✨ NEW
      ├── getCart()
      ├── addToCart()
      ├── removeFromCart()
      ├── checkout()
      ├── payOrder()
      ├── getOrders()
      └── getOrderDetail()
```

### Routes
```
routes/
  └── api.php (updated - thêm 7 API endpoints mới)
```

### Jobs
```
app/Jobs/VirtualMachine/
  └── ProcessOrderPaymentJob.php (optimized logic)
      ✅ Trừ tiền trước → Tạo VM sau
      ✅ Auto refund nếu all VMs fail
      ✅ Retry mechanism (3 lần)
      ✅ Email notifications
```

### Documentation
```
docs/
  ├── API_SERVICE_REGISTRATION.md ✨ NEW
  ├── SETUP_GUIDE.md ✨ NEW
  └── Postman_Collection.json ✨ NEW
```

---

## 🔌 API Endpoints Mới

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/cart` | Lấy giỏ hàng |
| POST | `/api/v1/cart/add` | Thêm vào giỏ hàng |
| DELETE | `/api/v1/cart/{id}` | Xóa khỏi giỏ hàng |
| POST | `/api/v1/checkout` | Tạo order từ cart |
| POST | `/api/v1/orders/{id}/pay` | Thanh toán bằng credit |
| GET | `/api/v1/orders` | Danh sách đơn hàng |
| GET | `/api/v1/orders/{id}` | Chi tiết đơn hàng |

**Authentication:** Tất cả endpoints yêu cầu `Authorization: Bearer {token}` (Sanctum)

---

## 🔄 Thay Đổi Database Schema

### Bảng Mới: `cart_addons`
```sql
cart_addons
├── id
├── cart_id (FK → carts.id)
├── addon_id (FK → product_addon.id)
├── qty
├── price
├── created_at
└── updated_at
```

**Purpose:** Lưu trữ addons đã chọn trong cart

### Bảng Đã Có Sẵn (Không Thay Đổi)
- ✅ `carts` (đã có support cho billing_cycle, product_pricing_id)
- ✅ `order__order_item` (đã có support)
- ✅ `order__order_addons` (đã có)
- ✅ `invoice`, `invoice_item`, `invoice_addons` (đã có)

---

## ⚙️ Logic Thanh Toán Mới

### Flow Cũ (Có Risk)
```
1. Check credit
2. Tạo VM
3. IF VM success → Trừ tiền
4. ELSE → Không trừ
```
**Vấn đề:** VM tạo OK nhưng trừ tiền fail → Mất VM hoặc mất tiền

### Flow Mới (Optimized) ✅
```
1. Check credit
2. TRỪ TIỀN NGAY (Transaction)
3. Update Invoice → PAID
4. Update Order → ACTIVE
5. Tạo VM (Background Job)
   ├── Success → Gửi email thành công
   ├── Partial fail → Retry 3 lần
   └── All fail → REFUND credit + Email lỗi
```

**Ưu điểm:**
- ✅ Atomic transaction: Trừ tiền thành công = Order valid
- ✅ Dễ refund nếu tạo VM fail hoàn toàn
- ✅ Tránh spam orders
- ✅ Retry mechanism thông minh

---

## 🔐 Security Enhancements

1. **API Authentication:** Sanctum Bearer Token
2. **Authorization:** User chỉ access được resources của mình
3. **Validation:** Strict validation cho mọi input
4. **Rate Limiting:** Throttle API requests (default: 60/minute)
5. **Transaction Safety:** DB transactions cho payment flow

---

## 📊 Models Relationships

### Cart (Updated)
```php
Cart
├── belongsTo: Customer
├── belongsTo: Product (new system)
├── belongsTo: ProductPricings
└── hasMany: CartAddons ✨ NEW
```

### CartAddon (New)
```php
CartAddon
├── belongsTo: Cart
└── belongsTo: Addon
```

### Order (No Change)
```php
Order
├── belongsTo: Customer
├── belongsTo: Invoice
├── belongsTo: Discount
└── hasMany: OrderItems
```

### OrderItem (No Change)
```php
OrderItem
├── belongsTo: Order
├── belongsTo: Product
├── belongsTo: ProductPricings
├── belongsTo: Os
└── hasMany: OrderAddons
```

---

## 🚀 Deployment Steps

### 1. Database Migration
```bash
php artisan migrate
```

### 2. Clear Caches
```bash
php artisan config:clear
php artisan route:clear
php artisan cache:clear
```

### 3. Setup Queue Worker
```bash
# Development
php artisan queue:work

# Production (với Supervisor)
sudo supervisorctl start portal-worker:*
```

### 4. Test API
```bash
# Import Postman collection
docs/Postman_Collection.json

# Hoặc test manual với curl
curl -X POST http://your-domain.com/api/v1/cart/add \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"product_id": 1, "billing_cycle": "monthly"}'
```

---

## 🧪 Testing Checklist

- [ ] Migration chạy thành công
- [ ] API authentication hoạt động
- [ ] Thêm product vào cart (có addons)
- [ ] Checkout tạo order thành công
- [ ] Thanh toán trừ credit đúng
- [ ] VM được tạo (nếu là VPS)
- [ ] Email thông báo được gửi
- [ ] Retry mechanism hoạt động
- [ ] Refund credit khi all VMs fail
- [ ] Queue jobs không bị stuck

---

## 📈 Performance Improvements

1. **Queue Jobs:** Payment processing không block request
2. **Background VM Creation:** User nhận response ngay, VM tạo sau
3. **Optimized Queries:** Eager loading relationships
4. **Pagination:** Orders list có pagination (20/page)

---

## 🐛 Known Issues & Limitations

### None at the moment ✅

Nếu phát hiện bug, vui lòng:
1. Check logs: `storage/logs/laravel.log`
2. Check failed jobs: `php artisan queue:failed`
3. Report qua Telegram/Slack

---

## 📚 Documentation

Chi tiết xem:
- [API_SERVICE_REGISTRATION.md](./API_SERVICE_REGISTRATION.md) - Full API docs
- [SETUP_GUIDE.md](./SETUP_GUIDE.md) - Setup instructions
- [Postman_Collection.json](./Postman_Collection.json) - Import vào Postman

---

## 🎉 Summary

### Thêm Mới
- ✅ 1 bảng database mới (`cart_addons`)
- ✅ 1 Model mới (`CartAddon`)
- ✅ 1 Controller mới (`ServiceController`)
- ✅ 7 API endpoints mới
- ✅ Optimized payment logic
- ✅ Auto refund mechanism
- ✅ Retry mechanism (3 lần)
- ✅ Full documentation

### Không Làm Hỏng
- ✅ Web routes vẫn hoạt động bình thường
- ✅ Không breaking changes cho existing code
- ✅ Database schema tương thích ngược
- ✅ Models cũ vẫn work

### Next Steps
- [ ] Frontend integration (Mobile app/SPA)
- [ ] Auto-renewal scheduling
- [ ] Webhook notifications
- [ ] Advanced analytics dashboard

---

**Created by:** Portal Dev Team  
**Reviewed by:** _Pending_  
**Deployed to:** _Pending_  
**Status:** ✅ Ready for Testing