8.29-bob: Subscription va davriy to'lov (recurring billing)

  BIR MARTALIK 8.19-bob:              DAVRIY (subscription):
  Mijoz bir marta to'laydi          Mijoz MUNTAZAM to'laydi (har oy)
  Mahsulot/buyurtma                 Xizmat davomiyligi (premium, SaaS)
  Oddiy oqim                        Murakkab (trial, yangilash, bekor)
  Daromad — bir martalik            Daromad — takrorlanuvchi (MRR)

   Davriy — saqlangan to'lov usuli (har oy avtomatik — qayta so'ramasdan)
   MRR (Monthly Recurring Revenue) — SaaS asosiy ko'rsatkichi

  REJALAR (tier — narx/imkoniyat farqi):
  ┌────────────┬──────────┬─────────────────────────────────┐
  │ Free       │ 0 so'm   │ cheklangan (5 loyiha, reklama)   │
  │ Pro        │ 99k/oy   │ kengaytirilgan (cheksiz, support)│
  │ Enterprise │ kelishuv │ to'liq (SLA, alohida DB — 8.25)  │
  └────────────┴──────────┴─────────────────────────────────┘

  Har reja:
  - Narx (oylik/yillik — yillik arzonroq)
  - Imkoniyatlar (entitlement — nima mumkin — 2.9)
  - Cheklovlar (limit — 5 loyiha, 10GB)

   Reja = narx + imkoniyat to'plami (mijoz tanlaydi)

  TRIAL — bepul sinov muddati (mijozni jalb qilish):
  - Card-required: karta kerak (trial oxirida avtomatik to'lov)
  - Card-free: kartasiz (trial oxirida to'lov so'raladi — konversiya kam)

  Oqim:
  1. Ro'yxat  trial boshlanadi (14 kun — state: trialing)
  2. Trial davomida to'liq imkoniyat (mijoz sinaydi)
  3. Trial tugashidan oldin eslatma (email — 8.10)
  4. Trial oxiri  to'lov (active) yoki bekor (cancelled)

   Trial tugashi cron bilan kuzatiladi (8.18)

  SUBSCRIPTION HOLATLARI (state machine — 8.19: 2.6):

  trialing (sinov) ── active (faol, to'langan)
                  ╲         │
                   ╲        ├── past_due (to'lov o'tmadi — dunning 2.7)
                    ╲       │         ├── active (qayta to'landi)
                     ╲      │         └── cancelled (urinishlar tugadi)
                      ╲     ├── cancelled (mijoz bekor qildi — 2.6)
                       ╲    └── expired (muddat tugadi)
                        ╲ cancelled

   Holat  xizmat (active/trialing — kirish; cancelled/expired — bloklash 2.9)

  DAVRIY YECHISH — har oy avtomatik (qayta so'ramasdan):

  USUL 1 — To'lov tizimi boshqaradi (Stripe Subscriptions — tavsiya):
  - Stripe rejani biladi  har oy avtomatik yechadi  webhook yuboradi
  - Siz faqat webhook'ni ishlaysiz 8.20-bob — eng oson, ishonchli

  USUL 2 — O'zingiz boshqarasiz (mahalliy — Payme/Click):
  - Saqlangan karta token  cron 8.18-bob har oy yechish
  - Holat, qayta urinish — o'zingiz (murakkabroq)

   Iloji bo'lsa — to'lov tizimi boshqaradi (Stripe Billing)

  UPGRADE (Pro  Enterprise) — darrov (qo'shimcha imkoniyat):
  - Proration: qolgan kun uchun farq hisoblanadi (adolatli)
  - Darrov yangi imkoniyat 2.9-bob

  DOWNGRADE (Pro  Free) — keyingi davrdan (to'lagani amal qiladi):
  - Joriy davr oxirigacha Pro, keyin Free

  BEKOR QILISH (cancel):
  - Cancel at period end: muddat oxirigacha xizmat (to'lagani uchun) — tavsiya
  - Immediate: darrov (refund bilan — kamroq)

   Mijoz to'lagani uchun xizmat oladi (adolat) — darrov kesish tavsiya etilmaydi

  DUNNING — to'lov o'tmaganda qayta urinish (karta muddati, mablag' yo'q):

  1. To'lov o'tmadi  state: past_due 2.4-bob
  2. Mijozga eslatma (email — "kartangizni yangilang" — 8.10)
  3. Qayta urinish (3 kun, 5 kun, 7 kun — exponential — 8.20)
  4. Urinishlar tugadi  cancelled + xizmat bloklash (2.9)

   Darrov bekor qilmaslik kerak (vaqtinchalik muammo — karta, mablag')
   Dunning = mijozni saqlab qolish (revenue recovery)

// Subscription hodisalari to'lov tizimidan webhook (8.20)
@Post("billing/webhook")
@HttpCode(200)
async webhook(@Req() req: RawBodyRequest<Request>, @Headers("stripe-signature") sig: string) {
  const event = this.verify(req.rawBody, sig);        // imzo (8.20: 2.4)
  switch (event.type) {
    case "invoice.paid":                              // davriy to'lov o'tdi
      await this.subService.davrYangilandi(event.data.object); break;
    case "invoice.payment_failed":                    // to'lov o'tmadi  dunning (2.7)
      await this.subService.pastDue(event.data.object); break;
    case "customer.subscription.deleted":             // bekor
      await this.subService.bekorQilindi(event.data.object); break;
  }
  return { received: true };
}

  HODISA                              LOKAL DB O'ZGARISHI
  ─────────────────────────────────  ──────────────────────────────────
  checkout.session.completed          Checkout tugadi  subscription yaratildi
                                      (stripeSubId'ni bog'lash — 2.11)
  customer.subscription.created       Subscription boshlandi (trialing/active)
  customer.subscription.updated       Reja/holat o'zgardi (upgrade, past_due 
                                      active, cancel_at_period_end o'rnatildi)
  customer.subscription.deleted       Butunlay bekor  holat = cancelled
  invoice.paid                        Davriy to'lov o'tdi  davrOxiri yangilandi
  invoice.payment_failed              To'lov o'tmadi  past_due (dunning — 2.7)
  invoice.upcoming                    Keyingi to'lov yaqin (eslatma — 8.10)
  customer.subscription.trial_will_end  Trial 3 kun qoldi (eslatma — 2.3)

   HAR hodisa idempotent bo'lishi kerak (8.20: 2.5) — Stripe bir hodisani
     bir necha marta yuborishi mumkin (at-least-once yetkazish)
   customer.subscription.updated — eng ko'p ma'lumot beruvchi hodisa:
     holat, reja, davr, cancel flag — barchasi shu yerda keladi

// Reja  ruxsat/limit (subscription holatiga qarab xizmat)
@Injectable()
export class EntitlementGuard implements CanActivate {
  async canActivate(context: ExecutionContext): Promise<boolean> {
    const req = context.switchToHttp().getRequest();
    const sub = await this.subService.tenantSubscription(req.tenantId);   // (8.25)

    // Faol obuna kerak (active/trialing)
    if (!["active", "trialing"].includes(sub.holat)) {
      throw new ForbiddenException("Obunangiz faol emas. Iltimos, to'lovni yangilang");
    }
    // Reja imkoniyati (feature flag)
    const kerakliReja = this.reflector.get("plan", context.getHandler());
    if (kerakliReja && !this.rejaYetadimi(sub.reja, kerakliReja)) {
      throw new ForbiddenException(`Bu imkoniyat ${kerakliReja} rejada mavjud`);
    }
    return true;
  }
}
// @RequirePlan("pro") @Post("export") — faqat Pro reja

  CHECKOUT SESSION (subscription mode) — obunani boshlash:
  1. Backend: stripe.checkout.sessions.create({ mode: "subscription", ... })
      session.url qaytadi
  2. Frontend: mijozni session.url'ga yo'naltiring (Stripe sahifasi)
  3. Mijoz karta kiritadi, to'laydi (Stripe sahifasida — PCI Stripe'da)
  4. Muvaffaqiyat  success_url'ga qaytadi
  5. Webhook: checkout.session.completed  subscription bog'lanadi 2.8-bob

  CUSTOMER PORTAL — mijoz o'zi boshqaradi (self-service):
  - Reja o'zgartirish (upgrade/downgrade — 2.6)
  - Karta yangilash (dunning'da muhim — 2.7)
  - Invoice tarixini ko'rish/yuklab olish 2.15-bob
  - Obunani bekor qilish 2.6-bob
   stripe.billingPortal.sessions.create({ customer, return_url })
   portal.url'ga yo'naltiring (Stripe boshqaradi — siz UI yozmaysiz)

   Portal — dunning uchun eng muhim: mijoz muddati o'tgan kartani
     o'zi yangilaydi (past_due  active)

  SetupIntent — kartani kelajakdagi davriy to'lov uchun saqlash:
  1. Backend: stripe.setupIntents.create({ customer, usage: "off_session" })
      client_secret qaytadi
  2. Frontend: karta tasdiqlanadi (pul yechilmaydi — faqat saqlash)
  3. payment_method  customer'ning default usuli bo'ladi
  4. Keyin: har oy off-session avtomatik yechish (mijoz yo'q — 2.5)

   usage: "off_session" — davriy to'lov uchun majburiy
     (mijoz brauzerda bo'lmasa ham yechish mumkin bo'lishi kerak)
   3D Secure: ba'zi kartalar tasdiqlashda mijoz ishtirokini talab qiladi —
     off_session'da bu invoice.payment_failed'ga olib kelishi mumkin (2.7)

  COUPON / DISCOUNT (chegirma):
  - Coupon: chegirma qoidasi (10% yoki 50k so'm; bir marta yoki N oy)
  - Promotion code: mijoz kiritadigan kod (WELCOME10)  coupon'ga bog'lanadi
  - Subscription'ga qo'llash: discount avtomatik invoice'da aks etadi

  TAX (soliq — VAT/QQS):
  - Stripe Tax: joylashuvga qarab avtomatik soliq hisoblaydi
  - O'zbekiston QQS, EU VAT — har mamlakat stavkasi har xil
  - Invoice'da alohida qator (subtotal + tax = total — 2.15)

   Soliq — huquqiy talab (noto'g'ri hisoblash — jarima)
   B2B: mijoz soliq raqamini (VAT ID) kiritsa — reverse charge (EU)

  BILLING MODELLARI:
  - Flat 2.2-bob: qat'iy oylik narx (Pro = 99k/oy — soddaligi)
  - Metered: foydalanishga qarab (1000 API = 10k so'm — davr oxirida)
  - Hybrid: baza + oshib ketgan foydalanish (Pro 99k + 5k/1000 API ortiq)

  METERED oqim (Stripe):
  1. Price'ni metered qilib yarating (recurring.usage_type = "metered")
  2. Foydalanish sodir bo'lganda: usage record yuboring
     (stripe.billing.meterEvents.create — miqdorni qayd qiling)
  3. Davr oxirida Stripe jami foydalanishni hisoblab invoice yaratadi
  4. invoice.paid  davr yangilanadi (2.8)

   Idempotency 8.20-bob: usage record'ni ikki marta yubormang
     (identifier bilan — aks holda mijoz ortiqcha to'laydi)
   Lokal DB'da ham foydalanishni kuzating (quota — 2.9 bilan bog'liq)

  INVOICE HAYOTIY SIKLI (Stripe):
  draft  open (to'lov kutilmoqda)  paid (to'landi) / uncollectible (yig'ilmadi)

  - Stripe har davr uchun invoice avtomatik yaratadi (subscription'da)
  - invoice.paid webhook 2.8-bob  lokal DB'ga yozib qo'ying (buxgalteriya)
  - PDF: invoice.invoice_pdf (Stripe tayyor PDF beradi)
    yoki o'zingiz generatsiya qiling (8.21 — PDF/Excel)
  - Receipt: to'lov tasdig'i (email — Stripe yuboradi yoki o'zingiz — 8.10)

  HISOBOT (accounting):
  - Oylik daromad (MRR — 2.1), soliq yig'indisi 2.13-bob
  - Invoice ro'yxati eksport (Excel/CSV — 8.21) — buxgalteriya uchun
  - Reconciliation: lokal DB  Stripe (mos kelishini tekshirish — 8.19: 2.15)

  MAHALLIY DAVRIY TO'LOV — cheklovlar va yechim:

  MUAMMO: Payme/Click'da "subscription" tushunchasi Stripe kabi emas
    - Avtomatik davriy yechish (off-session) — cheklangan yoki yo'q
    - Trial, proration, dunning — o'zingiz qurishingiz kerak (2.5 Usul 2)

  YECHIM:
  - Karta token saqlash: agar tizim qo'llab-quvvatlasa (kartani bog'lash)
  - Cron 8.18-bob: har oy saqlangan token orqali yechishga urinish
  - Holat mashinasi, dunning, proration — o'zingiz (2.4, 2.6, 2.7)
  - Muqobil: har oy mijozga to'lov havolasini yuborish (yarim avtomatik)

   Off-session yechish (mijoz yo'qligida) — bu mintaqada asosiy qiyinchilik
   Huquqiy: kartani saqlash — mahalliy qonun va tizim shartlariga rioya

  TEST MODE:
  - Stripe test kalitlari (sk_test_..., pk_test_...) — haqiqiy pul yo'q
  - Test kartalari: 4242 4242 4242 4242 (muvaffaqiyat),
    4000 0000 0000 0341 (davriy to'lov o'tmaydi — dunning sinovi — 2.7)
  - Test clock: vaqtni oldinga suradi (bir oylik davrni sekundlarda sinash)

  WEBHOOK LOKAL SINOVI (CLI):
  - stripe listen --forward-to localhost:3000/billing/webhook
    (Stripe hodisalarni lokal serveringizga yo'naltiradi)
  - stripe trigger invoice.paid (hodisani qo'lda ishga tushirish)
  - Imzo tekshiruvi (8.20: 2.4) test secret bilan ishlaydi

   Test va production kalitlarini adashtirmang (env — 8.19)
   Har webhook handler'ni alohida sinang (invoice.paid, payment_failed, ...)

   Stripe Billing (davriy — to'lov tizimi boshqaradi — eng oson — 2.5)
   State machine (trialing/active/past_due/cancelled — 2.4)
   Trial (jalb qilish — cron kuzatuv — 2.3, 8.18)
   Proration (upgrade adolatli — 2.6); bekor — davr oxiri 2.6-bob
   Dunning (darrov bekor qilmaslik — qayta urinish — 2.7)
   Webhook (holat sinxron — imzo + idempotency — 8.20, 2.8)
   Entitlement (reja  imkoniyat/limit — guard — 2.9)
   Eslatmalar (trial tugashi, to'lov o'tmadi — email — 8.10)
   MRR/churn kuzatuv (biznes ko'rsatkich — 2.1)
   Stripe-hosted (Checkout + Portal — kam PCI xavf — 2.11)
   SetupIntent (off-session karta saqlash — davriy uchun — 2.12)
   Metered — idempotent usage record (ortiqcha to'lov yo'q — 2.14)
   Invoice DB'ga yozish + reconciliation (buxgalteriya — 2.15)
   Test mode + webhook CLI (haqiqiy pulsiz sinov — 2.17)

HOLATLAR 2.4-bob: trialing | active | past_due | cancelled | expired
REJA 2.2-bob: plan (free/pro/enterprise)  narx + imkoniyat + limit
DAVRIY 2.5-bob: Stripe Subscriptions (webhook) yoki cron + saqlangan token
WEBHOOK 2.8-bob: invoice.paid | invoice.payment_failed | subscription.updated/deleted | checkout.session.completed
ENTITLEMENT 2.9-bob: @RequirePlan + EntitlementGuard (holat + reja)
HOSTED 2.11-bob: checkout.sessions.create(mode:"subscription") | billingPortal.sessions.create
KARTA 2.12-bob: setupIntents.create(usage:"off_session") — davriy uchun
METERED 2.14-bob: billing.meterEvents.create(identifier) — foydalanishga qarab
TEST 2.17-bob: sk_test_... | stripe listen --forward-to | stripe trigger

@Entity()
export class Plan {
  @PrimaryColumn() id: string;                        // "free", "pro", "enterprise"
  @Column() nom: string;
  @Column("bigint") oylikNarx: number;                // tiyin (8.19: 2.5)
  @Column("jsonb") imkoniyatlar: Record<string, any>; // { maxLoyiha: 5, support: false }
  @Column({ nullable: true }) stripePriceId: string;  // Stripe (2.5)
}

@Entity()
export class Subscription {
  @PrimaryGeneratedColumn("uuid") id: string;
  @Column() tenantId: string;                         // (8.25)
  @Column() planId: string;
  @Column({ type: "enum", enum: ["trialing", "active", "past_due", "cancelled", "expired"] })
  holat: string;                                      // state machine (2.4)
  @Column({ nullable: true }) trialTugashi: Date;
  @Column() davrBoshi: Date;
  @Column() davrOxiri: Date;                          // keyingi to'lov sanasi
  @Column({ default: false }) davrOxiridaBekor: boolean;   // cancel at period end (2.6)
  @Column({ nullable: true }) stripeSubId: string;    // (2.5)
  @Column({ nullable: true }) stripeCustomerId: string;  // Portal, off-session (2.11)
  @Column({ nullable: true }) stripeItemId: string;   // reja o'zgartirish uchun (2.6)
}

@Injectable()
export class SubscriptionService {
  async trialBoshla(tenantId: string, planId = "pro"): Promise<Subscription> {
    const trialKun = 14;
    const trialTugashi = new Date(Date.now() + trialKun * 24 * 3600 * 1000);
    return this.repo.save({
      tenantId, planId, holat: "trialing",            // (2.4)
      trialTugashi, davrBoshi: new Date(), davrOxiri: trialTugashi,
    });
    //  tenant Pro imkoniyatlari bilan (trial — 2.9)
  }
}

@Cron(CronExpression.EVERY_DAY_AT_9AM)
async trialKuzat() {
  // 3 kun qolganlarga eslatma (8.10)
  const yaqinda = await this.repo.find({
    where: { holat: "trialing", trialTugashi: Between(new Date(), new Date(Date.now() + 3 * 86400000)) },
  });
  for (const sub of yaqinda) {
    await this.mail.trialEslatma(sub.tenantId);       // "trial 3 kundan keyin tugaydi"
  }

  // Tugaganlar  to'lov yoki bekor
  const tugagan = await this.repo.find({
    where: { holat: "trialing", trialTugashi: LessThan(new Date()) },
  });
  for (const sub of tugagan) {
    if (sub.stripeSubId) continue;                    // Stripe boshqaradi (2.5)
    // Karta yo'q  expired (yoki to'lov so'rash)
    await this.repo.update(sub.id, { holat: "expired" });
    await this.mail.trialTugadi(sub.tenantId);
  }
}

// Stripe Billing — davriy to'lovni Stripe boshqaradi (eng oson)
async obunaYarat(tenantId: string, planId: string, paymentMethodId: string) {
  const plan = await this.planRepo.findOneBy({ id: planId });
  const tenant = await this.tenantService.bitta(tenantId);

  // Stripe customer + subscription
  const customer = await this.stripe.customers.create({
    email: tenant.email,
    payment_method: paymentMethodId,
    invoice_settings: { default_payment_method: paymentMethodId },
  });
  const stripeSub = await this.stripe.subscriptions.create({
    customer: customer.id,
    items: [{ price: plan.stripePriceId }],           // reja narxi (2.2)
    trial_period_days: 14,                            // trial (2.3)
  });

  // Lokal DB (Stripe — manba; lokal — kesh/tezlik)
  return this.repo.save({
    tenantId, planId, holat: "trialing",
    stripeSubId: stripeSub.id, davrOxiri: new Date(stripeSub.current_period_end * 1000),
  });
  //  har oy Stripe avtomatik yechadi  webhook (Misol 6)
}

async rejaOzgartir(tenantId: string, yangiPlanId: string) {
  const sub = await this.tenantSubscription(tenantId);
  const yangiPlan = await this.planRepo.findOneBy({ id: yangiPlanId });
  const eskiPlan = await this.planRepo.findOneBy({ id: sub.planId });

  const upgrade = yangiPlan.oylikNarx > eskiPlan.oylikNarx;

  if (upgrade) {
    // Upgrade — DARROV + proration (Stripe avtomatik hisoblaydi)
    await this.stripe.subscriptions.update(sub.stripeSubId, {
      items: [{ id: sub.stripeItemId, price: yangiPlan.stripePriceId }],
      proration_behavior: "always_invoice",          // qolgan kun farqi (2.6)
    });
    await this.repo.update(sub.id, { planId: yangiPlanId });   // darrov yangi imkoniyat
  } else {
    // Downgrade — KEYINGI davrdan (to'lagani amal qiladi — 2.6)
    await this.stripe.subscriptions.update(sub.stripeSubId, {
      items: [{ id: sub.stripeItemId, price: yangiPlan.stripePriceId }],
      proration_behavior: "none",
      billing_cycle_anchor: "unchanged",
    });
    // Lokal: keyingi davrda o'zgaradi (webhook'da)
  }
}

@Post("billing/webhook")
@HttpCode(200)
async webhook(@Req() req: RawBodyRequest<Request>, @Headers("stripe-signature") sig: string) {
  const event = this.stripe.webhooks.constructEvent(  // imzo (8.20: 2.4)
    req.rawBody, sig, this.config.get("STRIPE_WEBHOOK_SECRET"),
  );
  // Idempotency (8.20: 2.5)
  if (!(await this.idempotency.birinchiMartami(event.id))) return { received: true };

  switch (event.type) {
    case "invoice.paid": {                            // davriy to'lov o'tdi
      const sub = event.data.object.subscription;
      await this.repo.update({ stripeSubId: sub }, {
        holat: "active", davrOxiri: new Date(event.data.object.period_end * 1000),
      });
      break;
    }
    case "invoice.payment_failed":                    // dunning (2.7)
      await this.repo.update({ stripeSubId: event.data.object.subscription }, { holat: "past_due" });
      await this.mail.tolovOtmadi(/* tenant */);      // eslatma (8.10)
      break;
    case "customer.subscription.deleted":             // bekor
      await this.repo.update({ stripeSubId: event.data.object.id }, { holat: "cancelled" });
      break;
  }
  return { received: true };
}

async bekorQil(tenantId: string, darrov = false) {
  const sub = await this.tenantSubscription(tenantId);
  if (darrov) {
    await this.stripe.subscriptions.cancel(sub.stripeSubId);   // darrov (refund bilan)
    await this.repo.update(sub.id, { holat: "cancelled" });
  } else {
    // Davr oxirida bekor (to'lagani uchun xizmat — 2.6, tavsiya)
    await this.stripe.subscriptions.update(sub.stripeSubId, { cancel_at_period_end: true });
    await this.repo.update(sub.id, { davrOxiridaBekor: true });
    //  muddat oxirigacha active (webhook'da cancelled bo'ladi)
  }
  await this.mail.bekorTasdiq(tenantId);             // "bekor qilindi, oxirigacha amal qiladi"
}

export const RequirePlan = (...rejalar: string[]) => SetMetadata("plans", rejalar);

@Injectable()
export class SubscriptionGuard implements CanActivate {
  constructor(private subService: SubscriptionService, private reflector: Reflector) {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    const req = context.switchToHttp().getRequest();
    const sub = await this.subService.tenantSubscription(req.tenantId);   // (8.25)

    // 1. Faol obuna (2.4)
    if (!["active", "trialing"].includes(sub.holat)) {
      throw new ForbiddenException({
        message: "Obunangiz faol emas",
        code: "SUBSCRIPTION_INACTIVE", upgradeUrl: "/billing",   // frontend upgrade taklif
      });
    }
    // 2. Reja imkoniyati
    const kerakli = this.reflector.get<string[]>("plans", context.getHandler());
    if (kerakli && !kerakli.includes(sub.planId)) {
      throw new ForbiddenException({ message: `Bu imkoniyat ${kerakli.join("/")} rejada`, code: "PLAN_REQUIRED" });
    }
    return true;
  }
}

// Ishlatish
@RequirePlan("pro", "enterprise")
@Post("reports/advanced")
@UseGuards(JwtAuthGuard, SubscriptionGuard)
hisobot() { /* faqat Pro+ */ }

// Reja limiti (Free: 5 loyiha; Pro: cheksiz)
async loyihaYaratishMumkinmi(tenantId: string): Promise<boolean> {
  const sub = await this.tenantSubscription(tenantId);
  const plan = await this.planRepo.findOneBy({ id: sub.planId });
  const maxLoyiha = plan.imkoniyatlar.maxLoyiha;     // -1 = cheksiz

  if (maxLoyiha === -1) return true;                 // cheksiz (Pro)
  const joriy = await this.loyihaRepo.count({ where: { tenantId } });
  if (joriy >= maxLoyiha) {
    throw new ForbiddenException({
      message: `Free reja ${maxLoyiha} loyiha bilan cheklangan. Pro'ga o'ting`,
      code: "LIMIT_REACHED",
    });
  }
  return true;
}

// SaaS biznes ko'rsatkichlari (dashboard)
async metrikalar() {
  const faol = await this.repo.find({ where: { holat: In(["active", "trialing"]) } });
  // MRR (Monthly Recurring Revenue — oylik takrorlanuvchi daromad)
  const mrr = faol.reduce((s, sub) => {
    const plan = this.planlar.get(sub.planId);
    return s + (sub.holat === "active" ? plan.oylikNarx : 0);
  }, 0);

  // Churn (bekor qilganlar — oxirgi oy)
  const bekorQilgan = await this.repo.count({
    where: { holat: "cancelled", cancelledAt: MoreThan(new Date(Date.now() - 30 * 86400000)) },
  });

  return {
    mrr: mrr / 100,                                   // so'm
    faolObuna: faol.length,
    churnRate: (bekorQilgan / faol.length) * 100,     // % (SaaS sog'lig'i)
  };
}

// Stripe-hosted checkout — mijoz Stripe sahifasida to'laydi (PCI Stripe'da)
async checkoutSessionYarat(tenantId: string, planId: string): Promise<string> {
  const plan = await this.planRepo.findOneBy({ id: planId });
  const tenant = await this.tenantService.bitta(tenantId);

  const session = await this.stripe.checkout.sessions.create({
    mode: "subscription",                             // obuna rejimi (2.11)
    customer_email: tenant.email,
    line_items: [{ price: plan.stripePriceId, quantity: 1 }],   // reja narxi (2.2)
    subscription_data: { trial_period_days: 14 },     // trial (2.3)
    success_url: `${this.config.get("APP_URL")}/billing/success?session={CHECKOUT_SESSION_ID}`,
    cancel_url: `${this.config.get("APP_URL")}/billing/cancel`,
    // tenant'ni webhook'da topish uchun (checkout.session.completed — 2.8)
    metadata: { tenantId },
    client_reference_id: tenantId,
  });
  return session.url;                                 // frontend bu URL'ga yo'naltiradi
  //  to'lovdan keyin checkout.session.completed webhook (Misol 13)
}

// Mijoz o'zi boshqaradi: reja, karta, invoice, bekor — UI yozmaysiz
async portalHavola(tenantId: string): Promise<string> {
  const sub = await this.tenantSubscription(tenantId);
  const portal = await this.stripe.billingPortal.sessions.create({
    customer: sub.stripeCustomerId,                   // Stripe customer (Misol 4)
    return_url: `${this.config.get("APP_URL")}/billing`,
  });
  return portal.url;                                  // Stripe boshqaradigan sahifa
  //  mijoz kartani yangilaydi (dunning past_due  active — 2.7),
  //   rejani o'zgartiradi, invoice yuklaydi, bekor qiladi (2.6)
}

// checkout.session.completed + subscription.updated qo'shildi (2.8 to'liq ro'yxat)
switch (event.type) {
  case "checkout.session.completed": {                // obuna boshlandi (Misol 11)
    const session = event.data.object;
    const stripeSub = await this.stripe.subscriptions.retrieve(session.subscription);
    await this.repo.save({
      tenantId: session.metadata.tenantId,            // Misol 11 metadata
      stripeSubId: stripeSub.id,
      stripeCustomerId: session.customer,
      holat: stripeSub.status,                         // "trialing" yoki "active"
      davrOxiri: new Date(stripeSub.current_period_end * 1000),
    });
    break;
  }
  case "customer.subscription.updated": {             // reja/holat o'zgardi (2.6, 2.7)
    const s = event.data.object;
    await this.repo.update({ stripeSubId: s.id }, {
      holat: s.status,                                 // active/past_due/trialing
      davrOxiridaBekor: s.cancel_at_period_end,        // bekor rejalashtirildi (2.6)
      davrOxiri: new Date(s.current_period_end * 1000),
      planId: s.items.data[0].price.metadata.planId,   // yangi reja (downgrade — 2.6)
    });
    break;
  }
  case "invoice.paid":                                // davriy to'lov o'tdi (yuqorida)
    /* ... Misol 6 ... */ break;
  case "invoice.payment_failed":                      // dunning (2.7)
    /* ... Misol 6 ... */ break;
}

// Foydalanish sodir bo'lganda: Stripe'ga qayd + lokal quota (2.9)
async foydalanishQaydEt(tenantId: string, miqdor: number, hodisaId: string) {
  const sub = await this.tenantSubscription(tenantId);

  // Stripe'ga qayd — idempotency identifier bilan (8.20 — ikki marta yubormaslik)
  await this.stripe.billing.meterEvents.create({
    event_name: "api_call",
    payload: { stripe_customer_id: sub.stripeCustomerId, value: String(miqdor) },
    identifier: hodisaId,                             // takrorlanmaslik uchun (2.14)
  });

  // Lokal kuzatuv — quota tekshiruvi uchun (2.9)
  await this.usageRepo.increment({ tenantId, davr: this.joriyDavr() }, "miqdor", miqdor);
  //  davr oxirida Stripe jami bo'yicha invoice yaratadi 2.15-bob  invoice.paid
}

 cron + token + holat o'zingiz (murakkab, xato — 2.5)
 Stripe Billing (webhook — Stripe boshqaradi)

 past_due  darrov cancel (vaqtinchalik muammo — 2.7)
 dunning (qayta urinish)

 bekor  darrov bloklash (to'lagani uchun — 2.6)
 davr oxirigacha xizmat

 to'liq oy qayta (adolatsiz — 2.6)
 proration (qolgan kun farqi)

 cancelled tenant ishlaydi (2.9)
 entitlement guard (holat + reja)

 karta raqamini o'z formangizda olish (PCI yuki, xavf — 2.11)
 Checkout Session / Portal (karta Stripe sahifasida — 2.11)

 boshqa hodisalar e'tiborsiz  DB drift (holat mos emas — 2.8)
 updated/deleted/checkout.completed ham (to'liq sinxron — Misol 13)

 takroriy usage  mijoz ortiqcha to'laydi (2.14)
 identifier bilan (takrorlanmaydi — 8.20)