Clean Architecture, Layered va Hexagonal arxitektura — NestJS'da (9.3-bob)

  ARXITEKTURASIZ (hammasi aralash):
  Controller → DB so'rov to'g'ridan; biznes mantiq controller'da;
  framework hamma joyda → DB almashtirsa, hamma buziladi; test qiyin

  ARXITEKTURA BILAN (qatlamlar):
  Controller → Use Case → Domain ← Repository (interfeys)
                                    ↑ implementatsiya (DB)
  → biznes mantiq markazda, mustaqil; DB/framework almashtiriladigan; test oson

  ┌─────────────────────────────┐
  │  Presentation (Controller)  │  ← HTTP, GraphQL, CLI 8.1-bob
  ├─────────────────────────────┤
  │  Business/Service           │  ← biznes mantiq 8.1-bob
  ├─────────────────────────────┤
  │  Data Access (Repository)   │  ← DB so'rov 8.3-bob
  ├─────────────────────────────┤
  │  Database                   │
  └─────────────────────────────┘
  Yuqori → past chaqiradi (controller → service → repo → DB)

  Layered'da odatda:
  Service → Repository (konkret) → DB
  → biznes mantiq DB'ga bog'liq (DB o'zgarsa, service ta'sirlanadi)

  YECHIM (DIP — 9.1: 2.9):
  Service → Repository INTERFEYSI ← Repository implementatsiyasi → DB
  → biznes mantiq interfeysga tayanadi (DB detali pastda, almashtiriladigan)
  → Bu — Hexagonal/Clean'ning asosiy g'oyasi

  ┌──────────────────────────────────────────┐
  │           ADAPTERS (tashqi)               │
  │   ┌────────────────────────────────┐     │
  │   │   PORTS (interfeyslar)         │     │
  │   │   ┌──────────────────────┐     │     │
  │   │   │   CORE (biznes mantiq) │   │     │
  │   │   │   hech narsaga bog'liq emas│ │     │
  │   │   └──────────────────────┘     │     │
  │   └────────────────────────────────┘     │
  └──────────────────────────────────────────┘
  Tashqi (DB, API, UI) → port (interfeys) → core
  Core → port (interfeys) → adapter (implementatsiya)

  PORT turlari:
  - Driving port (inbound): tashqi → core (use-case interfeysi — API chaqiradi)
  - Driven port (outbound): core → tashqi (repository interfeysi — DB'ga)

  ADAPTER turlari:
  - Driving adapter: controller (HTTP), CLI, bot 8.12-bob — core'ni chaqiradi
  - Driven adapter: TypeORM repo 8.3-bob, email service 8.10-bob — port'ni amalga oshiradi

  → Core port'larni belgilaydi; adapter'lar ularni amalga oshiradi (almashtiriladigan)

  ┌────────────────────────────────────────────┐
  │  Frameworks & Drivers (DB, web, tashqi)    │  ← eng tashqi (detal)
  │  ┌──────────────────────────────────────┐  │
  │  │  Interface Adapters (controller, repo)│ │
  │  │  ┌────────────────────────────────┐  │  │
  │  │  │  Use Cases (ilova mantig'i)    │  │  │
  │  │  │  ┌──────────────────────────┐  │  │  │
  │  │  │  │  Entities (biznes qoida) │  │  │  │  ← eng ichki (yadro)
  │  │  │  └──────────────────────────┘  │  │  │
  │  │  └────────────────────────────────┘  │  │
  │  └──────────────────────────────────────┘  │
  └────────────────────────────────────────────┘

  Onion — konsentrik halqalar (piyoz qatlamlari):

  ┌──────────────────────────────────────────────┐
  │  Infrastructure + UI + Tests (eng tashqi)     │  ← DB, framework, test
  │  ┌────────────────────────────────────────┐   │
  │  │  Application Services (use-case)        │   │
  │  │  ┌──────────────────────────────────┐   │   │
  │  │  │  Domain Services                 │   │   │
  │  │  │  ┌────────────────────────────┐  │   │   │
  │  │  │  │  Domain Model (entity)     │  │   │   │  ← markaz (yadro)
  │  │  │  └────────────────────────────┘  │   │   │
  │  │  └──────────────────────────────────┘   │   │
  │  └────────────────────────────────────────┘   │
  └──────────────────────────────────────────────┘
  Bog'liqlik markazga qaraydi (tashqi → ichki)
  Interfeyslar (repository port) — ichki halqada; impl — tashqida

  ❗ DEPENDENCY RULE — bog'liqlik FAQAT ichkariga yo'naladi:
  tashqi qatlam → ichki qatlam (HECH QACHON aksincha emas)

  Entities — hech narsani bilmaydi (DB, framework, use-case)
  Use Cases — faqat Entities'ni biladi (DB emas)
  Adapters — Use Cases + Entities'ni biladi
  Frameworks — hammasini biladi (lekin hech kim uni bilmaydi)

  → Ichki qatlam tashqini BILMAYDI (DIP — interfeys orqali)

// Entity — sof biznes qoida (DB, framework BILMAYDI)
class Order {
  constructor(
    public readonly id: string,
    private items: OrderItem[],
    private status: OrderStatus,
  ) {}

  // Biznes qoida (entity ichida — behavior-oriented)
  jamiSumma(): number {
    return this.items.reduce((s, i) => s + i.narx * i.miqdor, 0);
  }
  bekorQilish(): void {
    if (this.status === "yetkazildi") {
      throw new Error("Yetkazilgan buyurtma bekor qilinmaydi");   // biznes qoida
    }
    this.status = "bekor";
  }
}
// ❗ Bu klassda DB, NestJS, HTTP yo'q — sof biznes mantiq

// Use Case — bitta amaliy stsenariy (biznes oqimi)
class CreateOrderUseCase {
  constructor(
    private orderRepo: OrderRepository,               // PORT (interfeys — 2.5)
    private paymentGateway: PaymentGateway,           // PORT
    private eventBus: EventBus,                        // PORT
  ) {}

  async bajar(input: CreateOrderInput): Promise<Order> {
    const order = new Order(/* ... */);               // entity (2.8)
    if (!(await this.paymentGateway.tolov(order.jamiSumma()))) {
      throw new Error("To'lov amalga oshmadi");
    }
    await this.orderRepo.saqla(order);                // port orqali (DB detalini bilmaydi)
    this.eventBus.elon("buyurtma_yaratildi", order);  // event (9.7)
    return order;
  }
}

  Uncle Bob use-case'ni uch bo'lakka ajratadi:

  Controller ──▶ [Input Port]  ──▶  Interactor  ──▶  [Output Port] ──▶ Presenter
   (adapter)     (interfeys)      (use-case impl)     (interfeys)      (adapter)
                                        │
                                        ▼
                              Repository port (driven)

  - Input port  — use-case KIRISH interfeysi (controller shuni chaqiradi)
  - Interactor  — input port'ning implementatsiyasi (haqiqiy biznes oqimi)
  - Output port — use-case CHIQISH interfeysi (natijani presenter'ga uzatadi)
  - Presenter   — output port impl (natijani UI/HTTP formatiga o'giradi)

  → Controller natijani O'ZI formatlamaydi; use-case output port orqali beradi
  → Bu — use-case'ni HTTP javob shaklidan ham ajratadi (to'liq izolyatsiya)

// application/ports/create-order.input-port.ts — use-case KIRISHI
export interface CreateOrderInputPort {
  bajar(input: CreateOrderInput): Promise<void>;
}

// application/ports/create-order.output-port.ts — use-case CHIQISHI
export interface CreateOrderOutputPort {
  muvaffaqiyat(order: Order): void;
  tolovXatosi(sabab: string): void;
}

// application/create-order.interactor.ts — INTERACTOR (input port impl)
export class CreateOrderInteractor implements CreateOrderInputPort {
  constructor(
    private orderRepo: OrderRepository,          // driven port
    private payment: PaymentGateway,             // driven port
    private output: CreateOrderOutputPort,       // output port (presenter'ga)
  ) {}

  async bajar(input: CreateOrderInput): Promise<void> {
    const order = Order.yarat(input.userId, input.items);
    if (!(await this.payment.tolov(order.jamiSumma(), input.userId))) {
      return this.output.tolovXatosi("To'lov amalga oshmadi");   // natija — output port orqali
    }
    await this.orderRepo.saqla(order);
    this.output.muvaffaqiyat(order);              // controller emas, presenter formatlaydi
  }
}

// Adapter — tashqi dunyoni use-case'ga ulaydi
// Driving adapter (controller — HTTP → use-case)
@Controller("orders")
class OrderController {
  constructor(private createOrder: CreateOrderUseCase) {}
  @Post()
  async yarat(@Body() dto: CreateOrderDto) {
    return this.createOrder.bajar(dto);               // use-case'ni chaqiradi
  }
}
// Driven adapter (repository — port implementatsiyasi → DB)
class TypeOrmOrderRepository implements OrderRepository {   // PORT'ni amalga oshiradi
  async saqla(order: Order): Promise<void> {
    // domen entity → ORM entity → DB (8.3)
  }
}

  Eng tashqi qatlam — "detal" (almashtiriladigan):
  - DB (PostgreSQL, MongoDB — 6)
  - Web framework (NestJS, Express — 8, 5.6)
  - Tashqi API (Click, Eskiz SMS — 5.18)
  - ORM (TypeORM, Prisma — 6.11-6.13)

  ❗ Uncle Bob: "DB — detal, framework — detal"
  → biznes mantiq ularga bog'liq bo'lmasligi kerak (almashtiriladigan)

  Bir "buyurtma" — uch xil ko'rinishda (qatlamiga qarab):

  1) DOMAIN ENTITY  (domain/)         — biznes qoidali obyekt
     - metodlar bor (bekorQil, jamiSumma), inkapsulyatsiya
     - DB, HTTP, framework BILMAYDI
     - "identifikatsiya"ga ega (id bo'yicha tenglik)

  2) DTO  (presentation/)             — ma'lumot tashuvchi (transfer)
     - faqat maydonlar (metod yo'q), plain obyekt
     - HTTP so'rov/javob shakli (validatsiya dekoratorlari — 8.5)
     - "qiymat"ga ega (maydonlar bo'yicha tenglik)

  3) ORM ENTITY  (infrastructure/)    — DB jadval xaritasi
     - @Entity/@Column 8.3-bob — TypeORM/Prisma bog'liq
     - DB sxemasi shakli (nullable, index, relation)

  → Uchtasini ARALASHTIRISH — eng keng tarqalgan Clean xatosi

  ❌ Framework baqiradigan struktura (nima QILADIGANI noaniq):
  src/
  ├── controllers/    ← "bu NestJS loyihasi" deb baqiradi
  ├── services/
  ├── entities/
  └── modules/        ← lekin loyiha NIMA HAQIDA? — bilinmaydi

  ✅ Domen baqiradigan struktura (nima HAQIDA ekani ravshan):
  src/
  ├── orders/         ← "bu — BUYURTMA tizimi" deb baqiradi
  ├── payments/
  ├── delivery/
  └── inventory/
      → papka nomlari BIZNES sohasini aytadi, framework'ni emas

  NestJS modul 8.1-bob → Hexagonal'ga tabiiy mos:
  modul/
  ├── domain/              ← CORE (entity, port interfeyslar)
  │   ├── order.entity.ts        (sof biznes — 2.8)
  │   └── order.repository.ts    (PORT interfeys — 2.5)
  ├── application/         ← USE CASES
  │   └── create-order.use-case.ts   2.9-bob
  ├── infrastructure/      ← ADAPTERS (driven)
  │   └── typeorm-order.repository.ts   (port impl — 2.10)
  └── presentation/        ← ADAPTERS (driving)
      └── order.controller.ts    2.10-bob

  Module: { provide: OrderRepository, useClass: TypeOrmOrderRepository }  (DIP — 8.2)

  ❗ HAR LOYIHAGA TO'LIQ CLEAN KERAK EMAS (over-engineering):

  Kichik CRUD / prototip:    oddiy layered (controller/service/repo — 8.1) yetadi
  O'rta loyiha:              layered + repository interfeys (DIP — 2.3)
  Katta/uzoq/murakkab biznes: Clean/Hexagonal (to'liq qatlamlar)
  Murakkab domen:            + DDD 9.4-bob

  Qoida: murakkablik biznes murakkabligiga mos bo'lsin (YAGNI — 9.1: 2.12)

  Clean Architecture — SKELET (qatlamlar, bog'liqlik yo'nalishi)
  DDD               — MAZMUN (domen qatlamini nima to'ldiradi)

  Clean qatlam        │  DDD to'ldiruvchisi 9.4-bob
  ────────────────────┼──────────────────────────────────
  Entities            │  Entity, Value Object, Aggregate
  (domen model)       │  (ubiquitous language bilan nomlangan)
  Use Cases           │  Application Service, Domain Event
  Interface Adapters  │  Repository (impl), Anti-Corruption Layer
  Frameworks/Drivers  │  Infrastructure (DB, message bus)

  Modul chegarasi 2.12-bob ≈ DDD Bounded Context (9.4)

  FOYDA:
  ✓ Texnologiyadan mustaqil (DB/framework almashtiriladigan)
  ✓ Test oson (biznes mantiq izolyatsiya — DB'siz — 8.11)
  ✓ Biznes mantiq aniq (entity/use-case'da)
  ✓ Uzoq yashash (o'zgarishga chidamli)

  NARX:
  ✗ Ko'proq kod (qatlamlar, interfeys, mapping)
  ✗ Boilerplate (domen ↔ ORM ↔ DTO o'tkazish)
  ✗ O'rganish egri chizig'i (jamoa tushunishi kerak)

  ✓ Biznes mantiq markazda, texnologiya chekkada (2.4, 2.6)
  ✓ Dependency Rule (bog'liqlik ichkariga — 2.7)
  ✓ Entity — sof biznes (DB/framework'siz — 2.8)
  ✓ Use Case — bir stsenariy, port'larga tayanadi 2.9-bob
  ✓ Port (interfeys) + Adapter (impl — almashtiriladigan — 2.5)
  ✓ Repository interfeys (DB izolyatsiya — DIP — 9.2: 2.13)
  ✓ NestJS modul → qatlamlar (DI port→adapter — 2.12)
  ✓ Pragmatik (biznes murakkabligiga mos — YAGNI — 2.13)

QATLAMLAR (ichkidan tashqiga):
Entity (biznes qoida) → Use Case (oqim) → Adapter (controller/repo) → Framework (DB)

DEPENDENCY RULE: bog'liqlik FAQAT ichkariga 2.7-bob

NestJS tuzilma 2.12-bob:
domain/ (entity + port interfeys) → application/ (use-case)
→ infrastructure/ (DB adapter) + presentation/ (controller)

DI: { provide: PortInterface, useClass: ConcreteAdapter }   // DIP (8.2)

// domain/order.entity.ts — SOF biznes (DB/framework yo'q)
export class Order {
  private constructor(
    public readonly id: string,
    private readonly userId: string,
    private items: OrderItem[],
    private status: OrderStatus = "yangi",
  ) {}

  static yarat(userId: string, items: OrderItem[]): Order {
    if (items.length === 0) throw new Error("Buyurtma bo'sh bo'lmaydi");   // biznes qoida
    return new Order(crypto.randomUUID(), userId, items);
  }

  jamiSumma(): number {
    return this.items.reduce((s, i) => s + i.narx * i.miqdor, 0);
  }
  bekorQil(): void {
    if (this.status === "yetkazildi") throw new Error("Yetkazilgan bekor qilinmaydi");
    this.status = "bekor";
  }
  get holat() { return this.status; }
}

// domain/order.repository.ts — PORT (interfeys — core belgilaydi)
export interface OrderRepository {
  saqla(order: Order): Promise<void>;
  topById(id: string): Promise<Order | null>;
  topByUser(userId: string): Promise<Order[]>;
}

// domain/payment.gateway.ts — PORT
export interface PaymentGateway {
  tolov(summa: number, userId: string): Promise<boolean>;
}

// application/create-order.use-case.ts
import { Injectable, Inject } from "@nestjs/common";

@Injectable()
export class CreateOrderUseCase {
  constructor(
    @Inject("OrderRepository") private orderRepo: OrderRepository,    // PORT (2.5)
    @Inject("PaymentGateway") private payment: PaymentGateway,        // PORT
    @Inject("EventBus") private eventBus: EventBus,                   // PORT
  ) {}

  async bajar(input: { userId: string; items: OrderItem[] }): Promise<Order> {
    const order = Order.yarat(input.userId, input.items);            // entity (biznes qoida)

    const tolovOk = await this.payment.tolov(order.jamiSumma(), input.userId);
    if (!tolovOk) throw new Error("To'lov amalga oshmadi");

    await this.orderRepo.saqla(order);                               // port (DB detalini bilmaydi)
    await this.eventBus.elon("buyurtma_yaratildi", { orderId: order.id });
    return order;
  }
}
// ❗ Bu use-case TypeORM/NestJS HTTP'ni BILMAYDI (faqat port'lar)

// infrastructure/typeorm-order.repository.ts — driven adapter
@Injectable()
export class TypeOrmOrderRepository implements OrderRepository {     // PORT impl
  constructor(
    @InjectRepository(OrderOrmEntity) private repo: Repository<OrderOrmEntity>,   // (8.3)
  ) {}

  async saqla(order: Order): Promise<void> {
    const ormEntity = this.domainToOrm(order);                      // domen → ORM (mapping)
    await this.repo.save(ormEntity);
  }
  async topById(id: string): Promise<Order | null> {
    const row = await this.repo.findOneBy({ id });
    return row ? this.ormToDomain(row) : null;                      // ORM → domen
  }
  async topByUser(userId: string): Promise<Order[]> {
    const rows = await this.repo.findBy({ userId });
    return rows.map((r) => this.ormToDomain(r));
  }

  private domainToOrm(order: Order): OrderOrmEntity { /* mapping */ return {} as any; }
  private ormToDomain(row: OrderOrmEntity): Order { /* mapping */ return {} as any; }
}
// → TypeORM'ni Prisma'ga almashtirsa: yangi PrismaOrderRepository (use-case tegmaydi!)

// presentation/order.controller.ts — driving adapter
@Controller("orders")
export class OrderController {
  constructor(private createOrder: CreateOrderUseCase) {}           // use-case (2.9)

  @Post()
  @UseGuards(JwtAuthGuard)                                          // (8.9)
  async yarat(@Body() dto: CreateOrderDto, @CurrentUser() user: any) {
    const order = await this.createOrder.bajar({                    // use-case'ni chaqiradi
      userId: user.id,
      items: dto.items,
    });
    return { id: order.id, summa: order.jamiSumma(), holat: order.holat };   // domen → HTTP
  }
}
// → REST'ni GraphQL'ga almashtirsa: yangi resolver (use-case tegmaydi!)

// orders.module.ts — qatlamlarni bog'lash (DIP — 8.2)
@Module({
  imports: [TypeOrmModule.forFeature([OrderOrmEntity])],
  controllers: [OrderController],                                   // presentation
  providers: [
    CreateOrderUseCase,                                             // application
    GetOrdersUseCase,
    // PORT → ADAPTER bog'lash (DIP — almashtiriladigan)
    { provide: "OrderRepository", useClass: TypeOrmOrderRepository },   // domain port → infra
    { provide: "PaymentGateway", useClass: ClickPaymentAdapter },
    { provide: "EventBus", useClass: NestEventBus },
  ],
})
export class OrdersModule {}
// → DB almashtirsa: useClass: PrismaOrderRepository (boshqa hech narsa o'zgarmaydi)

  src/orders/
  ├── domain/                          ← CORE (hech narsaga bog'liq emas)
  │   ├── order.entity.ts                  (biznes qoida — Misol 1)
  │   ├── order-item.value-object.ts       (9.4 — value object)
  │   ├── order.repository.ts              (PORT interfeys — Misol 1)
  │   └── payment.gateway.ts               (PORT interfeys)
  ├── application/                     ← USE CASES
  │   ├── create-order.use-case.ts         (Misol 2)
  │   └── cancel-order.use-case.ts
  ├── infrastructure/                  ← DRIVEN ADAPTERS
  │   ├── typeorm-order.repository.ts      (Misol 3)
  │   ├── order.orm-entity.ts              (ORM — DB detali)
  │   └── click-payment.adapter.ts
  ├── presentation/                    ← DRIVING ADAPTERS
  │   ├── order.controller.ts              (Misol 4)
  │   └── dto/
  └── orders.module.ts                 (DI — Misol 5)

// Kichik loyiha — oddiy layered (Clean ortiqcha)
@Controller("products")
class ProductController {                                           // presentation
  constructor(private service: ProductService) {}
  @Get() hammasi() { return this.service.hammasi(); }
}

@Injectable()
class ProductService {                                             // business
  constructor(@InjectRepository(Product) private repo: Repository<Product>) {}   // (8.3)
  hammasi() { return this.repo.find(); }                          // to'g'ridan repo
}
// → Kichik CRUD uchun bu YETADI (Clean over-engineering bo'lardi — 2.13)

// Use-case test — DB'siz (port mock — 8.11)
describe("CreateOrderUseCase", () => {
  it("to'lov muvaffaqiyatsiz → xato", async () => {
    const mockRepo: OrderRepository = { saqla: jest.fn(), topById: jest.fn(), topByUser: jest.fn() };
    const mockPayment: PaymentGateway = { tolov: jest.fn().mockResolvedValue(false) };   // to'lov yo'q
    const mockBus: EventBus = { elon: jest.fn() } as any;

    const useCase = new CreateOrderUseCase(mockRepo, mockPayment, mockBus);
    await expect(useCase.bajar({ userId: "1", items: [{ narx: 100, miqdor: 1 } as any] }))
      .rejects.toThrow("To'lov amalga oshmadi");
    expect(mockRepo.saqla).not.toHaveBeenCalled();                // saqlanmadi
  });
});
// ❗ DB, NestJS, HTTP yo'q — sof biznes mantiq test (tez, oson — Clean foydasi)

// Clean'da uch xil model (chegaralar uchun)
// 1. Domain entity (biznes — Misol 1)
class Order { /* biznes qoida */ }

// 2. ORM entity (DB — infrastructure)
@Entity("orders")
class OrderOrmEntity {
  @PrimaryColumn() id: string;
  @Column() userId: string;
  @Column("jsonb") items: any;
  @Column() status: string;
}

// 3. DTO (HTTP — presentation — 8.5)
class CreateOrderDto {
  @IsArray() items: OrderItemDto[];
}
class OrderResponseDto {
  id: string; summa: number; holat: string;
}
// ❗ Mapping kerak (domen↔ORM↔DTO) — bu Clean'ning narxi (boilerplate — 2.14)
// → kichik loyihada bir model yetadi (over-engineering'dan saqlaning)

  Qaysi arxitektura? (qaror daraxti):

  Loyiha kichik (CRUD, prototip, MVP)?
  └─ HA → Oddiy Layered (controller/service/repo — 8.1, Misol 7)

  O'rta (biznes mantiq bor, DB almashishi mumkin)?
  └─ HA → Layered + Repository interfeys (DIP — 2.3)

  Katta (murakkab biznes, uzoq yashaydi, jamoa)?
  └─ HA → Clean/Hexagonal (to'liq qatlamlar — Misol 6)

  Domen juda murakkab (ko'p qoida, kontekst)?
  └─ HA → Clean + DDD 9.4-bob

  ❗ Shubhada — oddiyroq tanla (keyin refactor oson; YAGNI — 9.1: 2.12)

❌ controller'da biznes qoida + DB (aralash — 2.1)
✅ entity (qoida) + use-case (oqim) + adapter (2.6)

❌ use-case'da TypeORM (bog'liq — 2.7)
✅ repository PORT (interfeys — 2.5)

❌ domen entity = ORM entity (framework bog'liq — 2.8)
✅ domen entity (sof) + ORM entity (alohida — Misol 9)

❌ CRUD'ga 4 qatlam + mapping (over-engineering — 2.13)
✅ oddiy layered (Misol 7)

❌ entity use-case'ni import qiladi (tashqiga bog'liq — 2.7)
✅ bog'liqlik faqat ichkariga