Clean Architecture — Senior chuqurlik & kurs yakuni

// ISP — kichik, fokuslangan interfeyslar (bitta ulkan emas)
interface OrderReader { findById(id: string): Promise<Order | null>; }
interface OrderWriter { save(order: Order): Promise<void>; }
// use case faqat KERAKLISIGA bog'lanadi -> keraksiz metodlarga bog'liq emas

// OCP — yangi to'lov usuli QO'SHISH uchun mavjud kodni O'ZGARTIRMAYSAN
interface PaymentMethod { pay(amount: Money): Promise<void>; }
class CardPayment  implements PaymentMethod { /* ... */ }
class ClickPayment implements PaymentMethod { /* ... */ }   // yangi -> qo'shildi, eski buzilmadi

Entity va Value Object

• Entity: o‘ziga xoslikka (identity) ega, vaqt bilan o‘zgaradi. Ikki buyurtma barcha maydonlari bir xil bo‘lsa ham — ID’si boshqa bo‘lsa, boshqa (Order, User).
• Value Object: o‘ziga xoslik yo‘q, qiymat bo‘yicha teng, o‘zgarmas (Money, Address, DateRange). 100 so‘m — har doim 100 so‘m.

// VALUE OBJECT — o'ziga xoslik yo'q, qiymat bo'yicha teng, O'ZGARMAS (immutable)
export class Money {
  constructor(readonly amount: number, readonly currency: string) {
    if (amount < 0) throw new Error("Manfiy summa bo'lmaydi");   // invariant konstruktorda
    Object.freeze(this);
  }
  add(o: Money): Money {                          // MUTATSIYA yo'q -> yangi obyekt
    if (this.currency !== o.currency) throw new Error("Valyuta mos emas");
    return new Money(this.amount + o.amount, this.currency);
  }
}

Aggregate — izchillik chegarasi

Aggregate — birga o‘zgaradigan entity/VO’lar to‘plami, bitta root bilan. Tashqi kod faqat rootga murojaat qiladi; invariantlar (qoidalar) root ichida saqlanadi:

// AGGREGATE — izchillik chegarasi; ROOT orqali kirasan, invariantlar ICHKARIDA saqlanadi
export class Order {                              // <-- Aggregate Root
  private items: OrderItem[] = [];
  private constructor(readonly id: OrderId, private status: OrderStatus) {}

  addItem(product: ProductId, qty: number) {      // faqat root orqali o'zgaradi
    if (this.status !== "draft") throw new Error("Faqat draft'ga qo'shiladi"); // invariant
    this.items.push(new OrderItem(product, qty));
  }
  // boshqa aggregate'ga OBYEKT bilan emas, ID bilan murojaat: customerId, productId
}

Bounded Context — model chegarasi

Bir xil so‘z turli kontekstda turli narsani bildiradi. "Order" Sotuv kontekstda — savat, narx, chegirma; Yetkazib berish kontekstda — manzil, og‘irlik, kuryer. Ularni bitta ulkan modelga tiqishtirmaslik kerak — har kontekst o‘z modeliga ega:

Domain Events — kontekstlarni bog‘lash

Domain event — domenda yuz bergan muhim voqea (OrderConfirmed). U aggregate va kontekstlarni bo‘shashtiradi: Sotuv "tasdiqlandi" eventini chiqaradi, Yetkazish uni tinglaydi — bir-birini to‘g‘ridan-to‘g‘ri bilmaydi:

// DOMAIN EVENT — domenda muhim narsa yuz berdi (aggregate ichida qayd qilinadi)
class Order {
  confirm() {
    if (this.status !== "draft") throw new Error("Faqat draft tasdiqlanadi");
    this.status = "confirmed";
    this.record(new OrderConfirmed(this.id, this.total));   // event ro'yxatga olindi
  }
}
// use case commit qilganda -> event'lar publish qilinadi (3, 10-mavzu bilan ulanadi)

// ANEMIC (anti-pattern) — entity shunchaki ma'lumot; mantiq servisda (protsedural)
class Order { status: string; }                                    // faqat data
class OrderService {
  cancel(o: Order) {
    if (o.status === "confirmed") throw new Error("...");           // qoida TASHQARIDA
    o.status = "cancelled";
  }
}

// RICH — entity O'Z qoidalarini o'zi biladi (haqiqiy OO, clean arch maqsadi)
class Order {
  cancel() {
    if (this.status === "confirmed") throw new Error("...");        // qoida ICHKARIDA
    this.status = "cancelled";
  }
}

// MAPPER — qatlamlar orasida tarjima (domen sof qoladi, Prisma/DTO'ga bog'lanmaydi)
class OrderMapper {
  // DB row -> domen (rehydrate)
  static toDomain(row: PrismaOrder): Order {
    return Order.rehydrate(row.id, row.status, row.items);
  }
  // domen -> DB shakli (persistence)
  static toPersistence(o: Order): Prisma.OrderUpdateInput {
    return { status: o.status };
  }
  // domen -> API javob (DTO)  -> ichki modelni tashqariga oshkor qilmaydi
  static toDto(o: Order): OrderDto {
    return { id: o.id, status: o.status, total: o.total.amount };
  }
}

Nega uch model? Prisma model DB sxemasiga bog‘langan; DTO API shakliga; ikkalasi ham o‘zgarishi mumkin. Domen ularga bog‘lansa — DB yoki API o‘zgarganda domen ham buziladi. Mapper domenni himoya qiladi.

Domen bo‘yicha, texnik qatlam bo‘yicha emas

Ko‘p loyiha papkalarni controllers/, services/, models/ deb ajratadi — bu frameworkni baqiradi. Yaxshiroq: domen bo‘yicha (orders/, payments/) — loyihaga qarab "bu buyurtma tizimi" ekanini darhol bilasan:

src/
  orders/                 # <-- domen "baqiradi", framework emas
    domain/         # Order (entity), Money (VO), OrderRepository (port)
    application/    # CancelOrderUseCase, ConfirmOrderUseCase
    infrastructure/ # PrismaOrderRepository, OrderController
  payments/
    domain/  application/  infrastructure/
  shipping/
    domain/  application/  infrastructure/

Use case chegaralari

Har use case — bitta ilova amali, aniq kirish va chiqish chegarasi bilan. Kirish (request model), chiqish (response model), bitta execute(). Bu use case’larni fokuslangan va mustaqil tutadi:

• Bitta use case = bitta amal (CancelOrder, ConfirmOrder — alohida, "OrderService" ichida hammasi emas).
• Aniq input/output — use case HTTP/DB shaklini bilmaydi, o‘z request/response modeliga ega.
• Controller — HTTP’ni use case input’iga tarjima qiladi, boshqa hech narsa.

// DOMAIN — sof unit test (tez, mock YO'Q, qoidani to'g'ridan-to'g'ri sinaydi)
const order = Order.create();
order.confirm();
expect(() => order.cancel()).toThrow("Tasdiqlangan buyurtma bekor bo'lmaydi");

// USE CASE — mock port (in-memory repository), orkestratsiyani tekshiradi
const repo = new InMemoryOrderRepository([draftOrder]);
await new CancelOrderUseCase(repo).execute(draftOrder.id);
expect((await repo.findById(draftOrder.id)).status).toBe("cancelled");

// ADAPTER — integratsiya test (HAQIQIY DB, testcontainers) — mapping to'g'riligini

Qachon qoidalarni buzish mumkin

• Oddiy CRUD: qoida deyarli yo‘q ilovada to‘liq qatlam/mapping — ortiqcha. Prismani use case’ga to‘g‘ridan-to‘g‘ri ishlatish maqbul.
• Prototip / MVP: tezlik muhimroq; keyin domen murakkablashsa — qatlamla.
• Kichik jamoa/skript: bilvositalik narxi foydasidan oshsa — soddaroq tuzilma.