Software Archetypes

Na podstawie "Enterprise Patterns and MDA" Jima Arlowa i Ili Neustadt

Software Archetypes to otwarte źródło wiedzy o wzorcach danych, które stoją za prawie każdym systemem biznesowym: jak modelować osoby i organizacje, produkty i katalogi, zamówienia, płatności, magazyn i wysyłki. Każdy wzorzec zaczyna się od konkretnego problemu, prowadzi przez strukturę z diagramem klas UML, a następnie pokazuje schemat SQL, cykl życia jako maszynę stanów i niezmienniki, które muszą zachodzić w czasie działania.

Wzorce bazują na książce Enterprise Patterns and MDA Jima Arlowa i Ili Neustadt, zweryfikowanej dwiema dekadami budowania systemów produkcyjnych. Są napisane dla inżynierów backendowych i architektów, którzy potrzebują punktu wyjścia sprawdzonego w wielu branżach — nie podręcznikowej abstrakcji, ale działającego modelu danych, który można od razu wdrożyć w PostgreSQL, MySQL lub dowolnej bazie relacyjnej.

Wszystkie przykłady mają działające implementacje w PHP, Javie i TypeScript. Każdy wzorzec to około 10–15 minut czytania i samodzielnie zrozumiały model, który można zastosować osobno lub złożyć z innymi.

Przegląd

Każdy wzorzec jest przedstawiony wraz z:

• Opis problemu — Kiedy potrzebujesz tego wzorca
• Przegląd koncepcyjny — Główna idea
• Struktura — Diagramy klas Mermaid
• Zachowania — Pseudokod operacji
• Maszyny stanów — Diagramy cyklu życia
• Niezmienniki — Reguły biznesowe, które muszą być spełnione
• Schemat SQL — ANSI SQL do persystencji
• Zagadnienia projektowe — Kompromisy i alternatywy

Katalog wzorców

Archetyp Party (Kto)

Archetyp Product (Co)

Wzorce transakcyjne (Handel)

Relacje między wzorcami

Scenariusz integracji end-to-end

Ten przewodnik pokazuje, jak wszystkie wzorce łączą się w typowym przepływie e-commerce: Customer składa Order, płaci, towar jest rezerwowany, a Order jest wysyłane.

1. Konfiguracja Party

// Jan Kowalski is registered as a Person with a Customer role
jan = new Person(firstName: "Jan", lastName: "Kowalski")
jan.addIdentifier(PESEL, "85031512345")
jan.addAddress(homeAddress)

customerRole = new Customer(
    party: jan,
    customerNumber: "CUST-00001234",
    loyaltyTier: LoyaltyTier.Gold,
    creditLimit: Money(1000000, "PLN")
)

2. Złożenie Order

order = new Order(
    orderNumber: "ORD-2026-000042",
    customer: customerRole,
    currency: "PLN",
    billingAddress: jan.getPrimaryAddress()
)

order.addLine(thinkpad, quantity: 1, unitPrice: Money(649900, "PLN"))
order.addLine(mouse,    quantity: 2, unitPrice: Money(44900, "PLN"))
// order.grandTotal = 909633 (with 23% VAT)

order.confirm()
// emits OrderConfirmed → triggers inventory reservation

3. Rezerwacja Inventory

// Listener handles OrderConfirmed event
for line in order.lines:
    item = findInventoryItem(line.product, warehouse)
    item.reserve(line.quantity, order.orderNumber, "Order reservation")
    // emits StockReserved

// Warehouse state:
// ThinkPad: onHand=20, reserved=1, available=19
// Mouse:    onHand=50, reserved=2, available=48

4. Payment

payment = new Payment(
    reference: "PAY-2026-000089",
    order: order,
    amount: order.grandTotal,
    method: PaymentMethod.Card
)

payment.markProcessing()
// ... gateway webhook: payment.success ...
payment.complete("gw_txn_abc123")
// emits PaymentCompleted → triggers shipment creation

order.markPaid(payment)
// emits OrderPaid

5. Utworzenie Shipment i przepływ Inventory

shipment = Shipment.fromOrder(order, "SHP-2026-000018", warehouseAddress)
shipment.addItemFromOrderLine(order.lines[0], 1)  // ThinkPad
shipment.addItemFromOrderLine(order.lines[1], 2)  // Mouse

shipment.startPicking()     // warehouse staff collects items
shipment.markPacked()       // items boxed
shipment.assignCarrier(dhl, "1234567890")
shipment.markLabelPrinted()
shipment.handOverToCarrier()
// emits ShipmentShipped

6. Wydanie Inventory

// Listener handles ShipmentShipped event
for item in shipment.items:
    inv = findInventoryItem(item.product, warehouse)
    inv.shipReserved(item.quantity, order.orderNumber)
    // emits StockIssued

// Warehouse state:
// ThinkPad: onHand=19, reserved=0, available=19
// Mouse:    onHand=48, reserved=0, available=48

7. Dostawa

// Carrier webhook updates
shipment.markInTransit("Warszawa Hub")
shipment.markOutForDelivery()
shipment.markDelivered({ signature: "J. Kowalski" })
// emits ShipmentDelivered

order.markDelivered()
order.complete()
// emits OrderCompleted

Podsumowanie przepływu zdarzeń

Wspólne zasady projektowe

Identyfikatory i klucze

• Klucz główny: UUID v7 (sortowalny chronologicznie)
• Klucz biznesowy: Czytelny dla człowieka (ORD-2024-000001)
• Klucz zewnętrzny: Z innych systemów (identyfikator transakcji bramki płatniczej)

Pieniądze

// NEVER use floating point!
// Store in smallest currency unit (cents, grosze)

amount_cents: 19999  // = 199.99
currency: "PLN"

Czas

• Znaczniki czasu: UTC, niezmienne (createdAt)
• Daty: Data lokalna bez czasu (birthDate)
• Okres ważności: validFrom/validTo dla encji ograniczonych czasowo

Strategie dziedziczenia

Katalog zdarzeń domenowych

Każdy wzorzec emituje zdarzenia domenowe, gdy zachodzą istotne zmiany stanu. Zdarzenia te umożliwiają luźne powiązanie między wzorcami (np. OrderConfirmed wyzwala rezerwację magazynową).

Domena Party

Domena Product

Domena Handlowa

Domena Realizacji

Kluczowe łańcuchy zdarzeń

Renderowanie diagramów Mermaid

Te samouczki używają Mermaid do diagramów. Aby je wyświetlić:

1. GitHub — Renderuje automatycznie w plikach Markdown
2. VS Code — Zainstaluj rozszerzenie "Markdown Preview Mermaid Support"
3. Online — Użyj mermaid.live
4. CLI — Użyj mmdc (mermaid-cli)

Działające implementacje

Trzy kompletne implementacje dostępne w osobnym repozytorium: software-archetypes-examples

Każde demo tworzy ten sam scenariusz: Jan Kowalski (Person) składa Order w Acme (Organization), płaci kartą, towar jest rezerwowany i wysyłany przez DHL, a następnie dostarczany.

Słowniczek

Licencja

Licencja MIT. Koncepcje wzorców na podstawie "Enterprise Patterns and MDA" autorstwa Jima Arlowa i Ili Neustadt (Addison-Wesley, 2003).