bao/portal-api

Fork 0

Files

T

pbao9 556b2c02e6 feat: Implement order and invoice management, enhance addon features, and remove the 'Type' module.

2026-02-11 17:02:07 +07:00

8.0 KiB

Raw Blame History

📋 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

🎯 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`

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

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

📊 Models Relationships

Cart (Updated)

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

CartAddon (New)

CartAddon
├── belongsTo: Cart
└── belongsTo: Addon

Order (No Change)

Order
├── belongsTo: Customer
├── belongsTo: Invoice
├── belongsTo: Discount
└── hasMany: OrderItems

OrderItem (No Change)

OrderItem
├── belongsTo: Order
├── belongsTo: Product
├── belongsTo: ProductPricings
├── belongsTo: Os
└── hasMany: OrderAddons

🚀 Deployment Steps

1. Database Migration

php artisan migrate

2. Clear Caches

php artisan config:clear
php artisan route:clear
php artisan cache:clear

3. Setup Queue Worker

# Development
php artisan queue:work

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

4. Test API

# 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

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

🐛 Known Issues & Limitations

None at the moment ✅

Nếu phát hiện bug, vui lòng:

Check logs: storage/logs/laravel.log
Check failed jobs: php artisan queue:failed
Report qua Telegram/Slack

📚 Documentation

Chi tiết xem:

API_SERVICE_REGISTRATION.md - Full API docs
SETUP_GUIDE.md - Setup instructions
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

8.0 KiB Raw Blame History