Billing OS

Phase 3 biến module subscription thành hệ thống vận hành công nợ dịch vụ B2B. MCV có thể tạo hợp đồng, sinh lịch thanh toán, gửi reminder, tạo QR Pay, ghi nhận callback InfoCMS và xem dashboard công nợ.

Luồng Tổng Thể

sequenceDiagram
    participant Admin as MCV Admin
    participant App as Business OS
    participant Client as Customer
    participant InfoCMS as InfoCMS QR Pay

    Admin->>App: Create service contract
    App->>App: Generate billing cycles
    App->>Client: Email reminder automation
    Client->>App: Open subscription portal
    Client->>App: Create QR Pay for billing cycle
    App->>InfoCMS: Create QuickQR
    InfoCMS-->>Client: QR payment info
    InfoCMS->>App: Deposit callback
    App->>App: Mark cycle paid
    App->>Client: Payment received email
    App->>Admin: Admin ops notification

Thành Phần

Thành phần	Vai trò
service_contracts	Hợp đồng dịch vụ B2B, setup fee, recurring amount, term
service_billing_cycles	Từng kỳ thu, hạn thanh toán, trạng thái, reminder count
payments	QR Pay qua InfoCMS, provider reference, callback payload
Admin Billing OS	Dashboard công nợ, filter/search, QR, reminder, mark paid
Customer Subscription Portal	Khách hàng xem kỳ thu và tự tạo QR Pay
subscriptions:send-billing-reminders	Automation nhắc thanh toán theo mốc ngày

Ageing Và SLA

Bucket	Ý nghĩa
future	Chưa đến hạn
due_soon	Đến hạn trong 7 ngày
overdue_1_7	Quá hạn 1-7 ngày
overdue_8_15	Quá hạn 8-15 ngày
overdue_15_plus	Rủi ro SLA/công nợ cần xử lý
paid	Đã thu

Reminder Automation

Command chạy mỗi ngày:

php artisan subscriptions:send-billing-reminders

Các mốc email:

• upcoming_7: trước hạn 7 ngày.
• due_today: đúng ngày đến hạn.
• overdue_3: quá hạn 3 ngày.
• overdue_7: quá hạn 7 ngày.
• overdue_15: quá hạn 15 ngày, đồng thời gửi cảnh báo admin ops.

QR Pay Và Callback

• Khách hàng hoặc admin tạo QR cho một billing cycle.
• Payment dùng provider infocms_qr và lưu service_billing_cycle_id trong metadata.
• Khi InfoCMS callback thành công, hệ thống đánh dấu payment succeeded, billing cycle paid, lưu callback payload và gửi email xác nhận.
• Top-up ví và service billing dùng chung callback InfoCMS, phân biệt bằng payment_purpose.

English Summary

Billing OS manages B2B service contracts, generated billing cycles, ageing/SLA status, QR Pay, reminder automation and InfoCMS payment callbacks. Admins can operate receivables from one dashboard, while customers can self-serve payment from the subscription portal.