Subscription / BillingSubscription / Billing

thuê bao đang hoạt độngactive subscriptions

1.2M

thuê bao đang hoạt độngactive subscriptions

lượt gia hạn mỗi ngày, dồn vào đầu thángrenewals a day, bunched at month start

~40K

lượt gia hạn mỗi ngày, dồn vào đầu thángrenewals a day, bunched at month start

lần trừ tiền bị từ chốiof charges declined

3–5%

lần trừ tiền bị từ chốiof charges declined

lần trừ tiền trùng cho một hoá đơndouble charges per invoice

0

lần trừ tiền trùng cho một hoá đơndouble charges per invoice

Renewal Scheduler định kỳ nhặt các thuê bao đến hạn bằng SKIP LOCKED và giao cho Billing Service tạo hoá đơn, gọi cổng thanh toán với idempotency key theo hoá đơn. Lần trừ tiền thất bại chuyển sang Dunning Worker. Chọn “Thẻ bị từ chối” để xem lịch thử lại và lúc thuê bao hết hạn.The renewal scheduler periodically claims due subscriptions with SKIP LOCKED and hands them to the billing service, which creates the invoice and calls the payment gateway with a per-invoice idempotency key. Failed charges move to the dunning worker. Choose “Card declined” to see the retry schedule and the point where the subscription expires.

1. 1

   Trạng thái thuê bao rốiTangled subscription states

   Dùng State pattern với các chuyển trạng thái hợp lệ: TRIALING → ACTIVE → PAST_DUE → ACTIVE khi trả được, hoặc EXPIRED khi hết ân hạn; ACTIVE → CANCELED khi huỷ có hiệu lực cuối kỳ. Mọi chuyển khác bị từ chối và mỗi lần chuyển được ghi lịch sử.Use the State pattern with explicit transitions: TRIALING → ACTIVE → PAST_DUE → back to ACTIVE when paid, or EXPIRED when the grace period ends; ACTIVE → CANCELED when a cancellation takes effect at period end. Any other transition is rejected and every transition is logged.

   State
2. 2

   Hai instance gia hạn cùng một thuê baoTwo instances renewing the same subscription

   Scheduler lấy việc bằng SELECT … FOR UPDATE SKIP LOCKED theo lô nhỏ, nên mỗi instance nhận các dòng khác nhau. Thêm unique(subscription_id, period_start) cho hoá đơn để chạy lại vẫn không sinh hoá đơn thứ hai.The scheduler claims work with SELECT … FOR UPDATE SKIP LOCKED in small batches, so each instance gets different rows. unique(subscription_id, period_start) on invoices means a rerun never creates a second invoice.

   Worker Pool
3. 3

   Trừ tiền hai lần khi timeoutDouble charges on timeouts

   Gọi cổng thanh toán với idempotency key gắn với hoá đơn và lần thử. Timeout thì gọi lại với cùng key; cổng trả kết quả cũ. Ghi payment_attempt trước khi gọi để đối soát được khi service chết giữa chừng.Call the gateway with an idempotency key tied to the invoice and the attempt. On a timeout, call again with the same key and the gateway replays the original result. Write a payment_attempt row before calling so a crash mid-call can be reconciled.

   Command
4. 4

   Thẻ bị từ chốiDeclined cards

   Dunning thử lại theo lịch ngày 1, 3, 7 thay vì liên tục, vì ngân hàng thường từ chối lặp lại trong cùng ngày. Trong thời gian ân hạn khách vẫn dùng được dịch vụ; hết lịch thì EXPIRED. Lỗi cứng như thẻ bị báo mất thì dừng ngay, không thử lại.Dunning retries on day 1, 3 and 7 rather than continuously, because banks tend to decline again on the same day. The customer keeps access during the grace period; once the schedule runs out the subscription expires. Hard declines such as a lost card stop immediately with no retry.

   Retry with Exponential Backoff
5. 5

   Nâng và hạ gói giữa kỳUpgrades and downgrades mid-cycle

   Nâng gói có hiệu lực ngay, tính phần chênh theo số ngày còn lại. Hạ gói lưu pending_plan_id và áp dụng khi gia hạn, tránh phải hoàn tiền. Mỗi chính sách giá là một Strategy: tính theo ngày, theo giây hoặc không tính tỷ lệ.Upgrades take effect now and charge the difference for the remaining days. Downgrades store pending_plan_id and apply at renewal, which avoids refunds. Each proration policy is a Strategy: per day, per second, or none.

   Strategy
6. 6

   Ngày cuối tháng và múi giờMonth ends and time zones

   Lưu ngày neo (billing_anchor) và tính kỳ thứ n từ neo, không cộng dồn từ kỳ trước: neo 31/1 cho ra 28/2 (29/2 năm nhuận), rồi 31/3. Cộng dồn sẽ trôi về ngày 28 mãi mãi. Lưu thời điểm ở UTC, tính ranh giới ngày theo múi giờ của khách.Store a billing_anchor and compute period n from it instead of adding a month to the previous period: an anchor of 31 Jan gives 28 Feb (29 in a leap year), then 31 Mar. Chaining from the previous period drifts to the 28th forever. Store instants in UTC and compute day boundaries in the customer's time zone.

   Template Method

Java: job gia hạn nhặt thuê bao đến hạn bằng SKIP LOCKED và trừ tiền theo hoá đơn. Go: tính kỳ từ ngày neo và tính tiền chênh khi nâng gói.Java: the renewal job claims due subscriptions with SKIP LOCKED and charges per invoice. Go: computes periods from the anchor date and the prorated amount for an upgrade.

@Component
@RequiredArgsConstructor
public class RenewalJob {
    private final SubscriptionRepository subs;
    private final InvoiceService invoices;
    private final PaymentGateway gateway;
    private final Clock clock;

    @Scheduled(fixedDelay = 60_000)
    @Transactional
    public void renewDue() {
        List<Subscription> due = subs.lockDue(clock.instant(), 20);1
        for (Subscription s : due) {
            Invoice inv = invoices.openFor(s, s.nextPeriod());2
            ChargeResult r = gateway.charge(
                    s.paymentMethodId(), inv.amountMinor(),
                    inv.idempotencyKey());       // "inv-7720-a1"3
            if (r.succeeded()) {
                inv.markPaid(r.chargeId());
                s.renew();                       // state: ACTIVE, next period
            } else if (r.isHardDecline()) {
                s.expire();                      // lost or stolen card
            } else {
                inv.scheduleRetry(DunningPlan.DAYS_1_3_7);
                s.markPastDue(clock.instant().plus(Duration.ofDays(7)));
            }
        }
    }
}

interface SubscriptionRepository extends JpaRepository<Subscription, Long> {
    @Query(value = """
            SELECT * FROM subscription
            WHERE status = 'ACTIVE' AND current_period_end <= :now
            ORDER BY current_period_end
            LIMIT :limit
            FOR UPDATE SKIP LOCKED""", nativeQuery = true)4
    List<Subscription> lockDue(@Param("now") Instant now, @Param("limit") int limit);
}

// PeriodStart returns the start of period n, counted from the anchor.
// Jan 31 → Feb 28 (29 in leap years) → Mar 31: never drifts to the 28th.
func PeriodStart(anchor time.Time, n int, loc *time.Location) time.Time {
	a := anchor.In(loc)
	first := time.Date(a.Year(), a.Month()+time.Month(n), 1,1
		a.Hour(), a.Minute(), a.Second(), 0, loc) // month overflow normalised
	lastDay := first.AddDate(0, 1, -1).Day()
	return time.Date(first.Year(), first.Month(), min(a.Day(), lastDay),2
		a.Hour(), a.Minute(), a.Second(), 0, loc)
}

// ProrateUpgrade returns the amount to charge now, in minor units.
func ProrateUpgrade(oldPrice, newPrice int64, now, start, end time.Time) int64 {
	if newPrice <= oldPrice || !now.Before(end) {
		return 0 // downgrades wait for the period end
	}
	total := int64(end.Sub(start) / time.Second)3
	left := int64(end.Sub(now) / time.Second)
	return (newPrice - oldPrice) * left / total
}

func (s *BillingService) Upgrade(ctx context.Context, subID int64, to Plan) error {
	return s.tx.Do(ctx, func(tx Tx) error {
		sub, err := tx.LockSubscription(ctx, subID) // FOR UPDATE
		if err != nil {
			return err
		}
		amount := ProrateUpgrade(sub.Plan.PriceMinor, to.PriceMinor,
			s.clock.Now(), sub.PeriodStart, sub.PeriodEnd)
		inv, err := tx.CreateInvoice(ctx, Invoice{
			SubscriptionID: sub.ID, Kind: KindProration,
			PeriodStart: sub.PeriodStart, AmountMinor: amount,
		})
		if err != nil {
			return err
		}
		if err := tx.SetPlan(ctx, sub.ID, to.ID); err != nil {
			return err
		}
		return s.outbox.Add(ctx, tx, ChargeInvoice{InvoiceID: inv.ID})4
	})
}

Mỗi pattern mở bài học tương ứng trong menu Pattern.Each one opens its lesson in the Patterns menu.