Beginner

// => Money wraps the primitive to prevent misuse at compile and runtime.
// => Exporting only the type, not the fields, forces callers through New().
type Money struct {
  // => amountCents stores value in smallest currency unit — avoids float rounding.
  // => int64 handles amounts up to ~92 quadrillion cents without overflow.
  amountCents int64
  // => Currency holds ISO 4217 three-letter code ("USD", "THB").
  Currency string
}
 
// => NewMoney is the sole construction path — validation happens once here.
// => Returning (Money, error) follows Go's explicit error idiom.
func NewMoney(cents int64, currency string) (Money, error) {
  // => Three-character check enforces ISO 4217 format at the boundary.
  // => Invalid currency never enters the domain after this point.
  if len(currency) != 3 {
    return Money{}, fmt.Errorf("currency must be 3 chars, got %q", currency)
  }
  // => Negative amounts are rejected — procurement deals in positive values.
  if cents < 0 {
    return Money{}, fmt.Errorf("amount must be non-negative, got %d", cents)
  }
  return Money{amountCents: cents, Currency: currency}, nil
}
 
// => Add returns a NEW Money — value receiver enforces immutability convention.
// => Error if currencies differ: adding USD to THB is always a domain error.
func (m Money) Add(other Money) (Money, error) {
  // => Currency check at add time prevents silent cross-currency totals.
  if m.Currency != other.Currency {
    return Money{}, fmt.Errorf("currency mismatch: %s + %s", m.Currency, other.Currency)
  }
  // => amountCents addition is exact — no floating-point drift.
  return Money{amountCents: m.amountCents + other.amountCents, Currency: m.Currency}, nil
}
 
// => String() formats for human display: "USD 10.50" (cents ÷ 100).
func (m Money) String() string {
  // => Divide by 100 for display only — internal representation stays in cents.
  return fmt.Sprintf("%s %.2f", m.Currency, float64(m.amountCents)/100)
}

// => Named type over string — distinct type, not just an alias.
// => Go type aliases (type X = string) share the same type; named types do not.
type PurchaseOrderId string
 
// => NewPurchaseOrderId generates a new RFC-4122 v4 UUID.
// => Factory function is the only construction point — no raw string casts outside domain.
func NewPurchaseOrderId() PurchaseOrderId {
  // => uuid.New() from github.com/google/uuid — cryptographically random v4.
  // => .String() returns lowercase hyphenated form: "550e8400-e29b-41d4-a716-446655440000".
  return PurchaseOrderId(uuid.New().String())
}
 
// => String() satisfies fmt.Stringer — safe extraction for serialisation.
// => Callers must call .String() explicitly — no implicit unwrapping.
func (id PurchaseOrderId) String() string {
  return string(id)
}
 
// => SupplierId is a parallel newtype — same implementation, incompatible type.
// => func f(id PurchaseOrderId) won't accept SupplierId — compile error.
type SupplierId string
 
func NewSupplierId() SupplierId {
  // => Same uuid source — different type prevents ID swapping between aggregates.
  return SupplierId(uuid.New().String())
}
 
func (id SupplierId) String() string {
  return string(id)
}

// => Underlying int type gives compact in-memory representation.
// => Unexported iota values are zero-indexed — Draft == 0.
type POStatus int
 
const (
  // => iota auto-increments — Draft=0, Submitted=1, etc.
  // => Explicit first value documents that zero-value is Draft (safe default).
  Draft          POStatus = iota // 0
  Submitted                      // 1
  ApprovalPending                // 2
  Issued                         // 3
  Received                       // 4
  Paid                           // 5
  Cancelled                      // 6
  Disputed                       // 7
)
 
// => String() prevents "0" appearing in logs — human-readable status names.
// => Go lacks exhaustive match; a linter (exhaustive) should check switch completeness.
func (s POStatus) String() string {
  switch s {
  case Draft:
    return "Draft"
  case Submitted:
    return "Submitted"
  case ApprovalPending:
    return "ApprovalPending"
  case Issued:
    return "Issued"
  case Received:
    return "Received"
  case Paid:
    return "Paid"
  case Cancelled:
    return "Cancelled"
  case Disputed:
    return "Disputed"
  default:
    // => Default branch catches unknown values that could appear after deserialization.
    return fmt.Sprintf("POStatus(%d)", int(s))
  }
}

// => All fields unexported — callers cannot bypass validation by direct field assignment.
// => Accessors expose read-only view without allowing mutation.
type ApprovalLevel struct {
  tier              int
  requiredApprovers int
  // => budgetCapCents mirrors Money.amountCents — same unit, same precision.
  budgetCapCents    int64
}
 
// => NewApprovalLevel is the only valid construction path.
// => Validation at construction = impossible to have an invalid level inside the domain.
func NewApprovalLevel(tier, required int, capCents int64) (ApprovalLevel, error) {
  // => Tier 1-3 maps to department → VP → C-suite escalation path.
  if tier < 1 || tier > 3 {
    return ApprovalLevel{}, fmt.Errorf("tier must be 1-3, got %d", tier)
  }
  // => At least one approver required — zero would allow self-approval bypass.
  if required < 1 {
    return ApprovalLevel{}, fmt.Errorf("requiredApprovers must be >= 1, got %d", required)
  }
  // => Zero or negative cap is nonsensical for a budget ceiling.
  if capCents <= 0 {
    return ApprovalLevel{}, fmt.Errorf("budgetCapCents must be > 0, got %d", capCents)
  }
  return ApprovalLevel{tier: tier, requiredApprovers: required, budgetCapCents: capCents}, nil
}
 
// => Accessors provide read-only access — value object cannot mutate after construction.
func (a ApprovalLevel) Tier() int              { return a.tier }
func (a ApprovalLevel) RequiredApprovers() int { return a.requiredApprovers }
func (a ApprovalLevel) BudgetCapCents() int64  { return a.budgetCapCents }

// => Named string type — distinct from SupplierId and other string-based types.
type SupplierCode string
 
// => supplierCodePattern is compiled once at init time — not per call.
// => ^[A-Z]{2}-\d{6}$ means: two uppercase letters, hyphen, six digits, end.
var supplierCodePattern = regexp.MustCompile(`^[A-Z]{2}-\d{6}$`)
 
// => ParseSupplierCode validates at the boundary — rejects bad input here.
// => Returns (SupplierCode, error) following Go's explicit error convention.
func ParseSupplierCode(s string) (SupplierCode, error) {
  // => MatchString runs the pre-compiled regex — cheap after first call.
  if !supplierCodePattern.MatchString(s) {
    return "", fmt.Errorf("invalid supplier code format: %q (expected XX-######)", s)
  }
  // => Conversion is safe after validation — no further checks needed downstream.
  return SupplierCode(s), nil
}
 
// => String() enables fmt.Sprintf and logging without explicit casting.
func (c SupplierCode) String() string {
  return string(c)
}

// => Unit is a named string type — readable in logs and serialization.
// => String-based enum avoids magic numbers while keeping interoperability.
type Unit string
 
const (
  // => UnitEach for countable discrete items (pens, chairs, servers).
  UnitEach  Unit = "each"
  // => UnitKg for bulk materials sold by weight.
  UnitKg    Unit = "kg"
  // => UnitLitre for liquids sold by volume.
  UnitLitre Unit = "litre"
)
 
// => Quantity bundles amount and unit — inseparable in the domain.
type Quantity struct {
  // => float64 acceptable for quantity — unlike money, small rounding is tolerable.
  Amount float64
  Unit   Unit
}
 
// => NewQuantity validates amount > 0 — negative or zero quantities are nonsensical.
func NewQuantity(amount float64, unit Unit) (Quantity, error) {
  if amount <= 0 {
    return Quantity{}, fmt.Errorf("quantity amount must be > 0, got %f", amount)
  }
  return Quantity{Amount: amount, Unit: unit}, nil
}
 
// => Add rejects mixed units — adding kg to each is a domain error, not a programmer error.
func (q Quantity) Add(other Quantity) (Quantity, error) {
  // => Unit comparison catches semantic mismatches before arithmetic.
  if q.Unit != other.Unit {
    return Quantity{}, fmt.Errorf("unit mismatch: %s + %s", q.Unit, other.Unit)
  }
  return Quantity{Amount: q.Amount + other.Amount, Unit: q.Unit}, nil
}

// => LineItemId scopes the ID to line items — prevents swapping with other ID types.
type LineItemId string
 
// => LineItem is a value object: identity is by position in the PO, not by an entity ID.
// => The LineItemId field scopes uniqueness within the PO — not a global entity identity.
type LineItem struct {
  Id          LineItemId
  Description string
  Qty         Quantity
  UnitPrice   Money
}
 
// => NewLineItem validates inputs before construction — no invalid line items in domain.
func NewLineItem(desc string, qty Quantity, price Money) (LineItem, error) {
  // => Empty description is rejected — PO audits require identifiable line items.
  if strings.TrimSpace(desc) == "" {
    return LineItem{}, fmt.Errorf("line item description must not be empty")
  }
  // => Price currency must be set — zero money with empty currency is invalid.
  if price.Currency == "" {
    return LineItem{}, fmt.Errorf("line item unit price must have a currency")
  }
  return LineItem{
    // => uuid.New() generates a unique ID scoped to this line item.
    Id:          LineItemId(uuid.New().String()),
    Description: desc,
    Qty:         qty,
    UnitPrice:   price,
  }, nil
}
 
// => TotalPrice multiplies quantity by unit price — the key financial aggregate.
// => Returns (Money, error) because Multiply may return an error.
func (li LineItem) TotalPrice() (Money, error) {
  // => Multiply scales the unit price by the quantity amount.
  return li.UnitPrice.Multiply(li.Qty.Amount)
}

// => All fields exported — Address is a pure data container with no invariant methods.
// => CountryCode is the only validated field — other fields vary too much to validate generically.
type Address struct {
  Street      string
  City        string
  PostalCode  string
  // => CountryCode must be ISO 3166-1 alpha-2: "TH", "US", "GB", etc.
  CountryCode string
}
 
// => validCountryCodes is a sample set — in production, use a full ISO 3166 dataset.
var validCountryCodes = map[string]bool{
  "TH": true, "US": true, "GB": true, "SG": true, "MY": true,
}
 
// => NewAddress validates the country code — other fields trusted from the UI layer.
func NewAddress(street, city, postal, country string) (Address, error) {
  // => Two-character uppercase check is the first guard — before map lookup.
  if len(country) != 2 {
    return Address{}, fmt.Errorf("country code must be 2 chars, got %q", country)
  }
  // => Map lookup confirms the code is a known country.
  if !validCountryCodes[strings.ToUpper(country)] {
    return Address{}, fmt.Errorf("unknown country code: %q", country)
  }
  // => Street and city must not be empty — delivery cannot route to a blank address.
  if strings.TrimSpace(street) == "" || strings.TrimSpace(city) == "" {
    return Address{}, fmt.Errorf("street and city must not be empty")
  }
  return Address{Street: street, City: city, PostalCode: postal, CountryCode: strings.ToUpper(country)}, nil
}
 
// => Equal compares all fields — value object equality by structural comparison.
// => Go struct == works here because all fields are comparable strings.
func (a Address) Equal(other Address) bool {
  return a == other
}

// => time.Time fields — timezone-aware, suitable for cross-regional procurement.
type DateRange struct {
  Start time.Time
  End   time.Time
}
 
// => NewDateRange enforces start < end — an open or reversed range is invalid.
func NewDateRange(start, end time.Time) (DateRange, error) {
  // => After() not AfterOrEqual() — start and end cannot be the same instant.
  if !start.Before(end) {
    return DateRange{}, fmt.Errorf("start must be before end: %v >= %v", start, end)
  }
  return DateRange{Start: start, End: end}, nil
}
 
// => Contains checks whether a point in time falls within the range.
// => Used for: is today within the PO delivery window?
func (dr DateRange) Contains(t time.Time) bool {
  // => !t.Before(dr.Start) means t >= Start; t.Before(dr.End) means t < End.
  return !t.Before(dr.Start) && t.Before(dr.End)
}
 
// => Overlaps detects whether two ranges share any time — duplicate PO detection.
func (dr DateRange) Overlaps(other DateRange) bool {
  // => Two ranges overlap if neither ends before the other starts.
  return dr.Start.Before(other.End) && other.Start.Before(dr.End)
}
 
// => Duration returns the length of the range for SLA and reporting calculations.
func (dr DateRange) Duration() time.Duration {
  return dr.End.Sub(dr.Start)
}

// => Multiply scales money by a float factor — quantity × unit price.
// => Returns (Money, error) because negative factor is invalid.
func (m Money) Multiply(factor float64) (Money, error) {
  // => Negative factor would produce negative money — rejected.
  if factor < 0 {
    return Money{}, fmt.Errorf("multiply factor must be >= 0, got %f", factor)
  }
  // => Round to nearest cent after multiplication — prevents fractional cents.
  // => math.Round avoids truncation bias in accumulation scenarios.
  newCents := int64(math.Round(float64(m.amountCents) * factor))
  return Money{amountCents: newCents, Currency: m.Currency}, nil
}
 
// => Equal compares both amount and currency — two Money values are equal only if both match.
func (m Money) Equal(other Money) bool {
  return m.amountCents == other.amountCents && m.Currency == other.Currency
}
 
// => GreaterThan drives budget cap checks in the Approve transition.
// => Returns (bool, error) — comparing different currencies is an error.
func (m Money) GreaterThan(other Money) (bool, error) {
  if m.Currency != other.Currency {
    return false, fmt.Errorf("cannot compare %s and %s", m.Currency, other.Currency)
  }
  return m.amountCents > other.amountCents, nil
}
 
// => IsZero checks for a zero-value money amount — used in invoice validation.
func (m Money) IsZero() bool {
  return m.amountCents == 0
}

// => Money is a value object — Go's == works because all fields are comparable.
// => Two Money values with equal amountCents and Currency are identical.
m1, _ := NewMoney(1000, "THB")
m2, _ := NewMoney(1000, "THB")
// => m1 == m2 is true — no "object identity" in Go for structs passed by value.
fmt.Println(m1 == m2) // => Output: true
 
// => For value objects with slice fields, == does NOT work — use reflect.DeepEqual.
// => Prefer explicit Equal() methods for consistency across all value objects.
fmt.Println(m1.Equal(m2)) // => Output: true (via explicit method)
 
// => Supplier is an entity — equality is by ID, not by all fields.
// => Two Supplier values with same id but different Name are the SAME entity.
s1 := Supplier{id: "s-001", Name: "Acme"}
s2 := Supplier{id: "s-001", Name: "Acme Corp"}
// => s1 == s2 is FALSE in Go (Name differs) — do not use == for entities.
fmt.Println(s1 == s2) // => Output: false (wrong for entities!)
// => Use SameIdentity for entities — compares id only.
fmt.Println(s1.SameIdentity(&s2)) // => Output: true (correct entity comparison)

// => WithCurrency uses a VALUE receiver — Go copies the struct on call.
// => The original m is unchanged; a new Money is returned.
func (m Money) WithCurrency(c string) (Money, error) {
  // => Validate the new currency before constructing the new value.
  if len(c) != 3 {
    return Money{}, fmt.Errorf("currency must be 3 chars, got %q", c)
  }
  // => m is the copy — modifying it does not affect the caller's original.
  // => Return the modified copy as a new Money value.
  m.Currency = c
  return m, nil
}
 
// => Demonstration: original is unchanged after WithCurrency.
original, _ := NewMoney(500, "THB")
converted, _ := original.WithCurrency("USD")
// => original.Currency is still "THB" — value receiver copied it.
fmt.Println(original.Currency)  // => Output: THB
fmt.Println(converted.Currency) // => Output: USD

// => Unexported id field — identity is set at construction and never changed externally.
// => Exported Name, ContactEmail — mutable entity state that changes over lifecycle.
type Supplier struct {
  id           SupplierId
  Name         string
  Code         SupplierCode
  ContactEmail string
  Active       bool
  CreatedAt    time.Time
}
 
// => NewSupplier creates a new Supplier with a validated initial state.
// => Returns *Supplier (pointer) — entity mutations require pointer receiver methods.
func NewSupplier(id SupplierId, name string, code SupplierCode, email string) (*Supplier, error) {
  // => Name must be non-empty — a nameless supplier cannot be identified on documents.
  if strings.TrimSpace(name) == "" {
    return nil, fmt.Errorf("supplier name must not be empty")
  }
  return &Supplier{
    id:           id,
    Name:         name,
    Code:         code,
    ContactEmail: email,
    // => Active defaults to true — new suppliers are active unless explicitly deactivated.
    Active:    true,
    CreatedAt: time.Now(),
  }, nil
}
 
// => SameIdentity compares IDs only — not current Name or state.
// => Two Supplier pointers with the same id ARE the same entity.
func (s *Supplier) SameIdentity(other *Supplier) bool {
  return s.id == other.id
}
 
// => Deactivate uses a POINTER receiver — mutates the entity state in place.
// => Value receiver would mutate only the copy, leaving the original unchanged.
func (s *Supplier) Deactivate() {
  // => Active = false marks the supplier unavailable for new POs.
  s.Active = false
}
 
// => UpdateEmail is a domain operation — encapsulates the state change.
// => Pointer receiver ensures the change persists on the caller's instance.
func (s *Supplier) UpdateEmail(email string) error {
  if strings.TrimSpace(email) == "" {
    return fmt.Errorf("contact email must not be empty")
  }
  s.ContactEmail = email
  return nil
}
 
// => Id() exposes the private id for repository lookups — read-only accessor.
func (s *Supplier) Id() SupplierId {
  return s.id
}

// => Entity: Supplier has an id field — identity comparison by id only.
// => Pointer receivers throughout signal mutable lifecycle.
s1 := &Supplier{id: "s-001", Name: "Acme"}
s2 := &Supplier{id: "s-001", Name: "Acme Corp"}
// => SameIdentity returns true — same supplier, different name at different points in time.
fmt.Println(s1.SameIdentity(s2)) // => Output: true
 
// => Value object: Money has no id — equality by amountCents + Currency.
// => Value receivers throughout signal immutable snapshot semantics.
m1, _ := NewMoney(500, "THB")
m2, _ := NewMoney(500, "THB")
// => Go struct == works for comparable structs — no explicit Equal needed.
fmt.Println(m1 == m2) // => Output: true
 
// => Convention in Go: pointer receiver = entity, value receiver = value object.
// => This is a code-reading signal, not enforced by the compiler.
// => Pointer receiver enables mutation; value receiver guarantees copy semantics.

// => PurchaseOrder is the aggregate root — all mutations route through its methods.
// => id is unexported — set at construction, immutable thereafter.
type PurchaseOrder struct {
  id         PurchaseOrderId
  // => SupplierId is exported for read access — cross-aggregate reference by ID only.
  // => No *Supplier field — DDD prohibits cross-aggregate object references.
  SupplierId SupplierId
  // => Status starts as Draft — only valid initial state.
  Status     POStatus
  // => LineItems owned by PO — no external code mutates this slice directly.
  LineItems  []LineItem
  CreatedAt  time.Time
  // => UpdatedAt tracks the last mutation — set on every state-changing method.
  UpdatedAt  time.Time
}
 
// => NewPurchaseOrder creates a Draft PO — the only valid initial state.
// => No line items at construction — they are added via AddLineItem.
func NewPurchaseOrder(id PurchaseOrderId, supplierID SupplierId) *PurchaseOrder {
  now := time.Now()
  return &PurchaseOrder{
    id:         id,
    SupplierId: supplierID,
    // => Draft is the only valid starting status — no other entry point.
    Status:     Draft,
    LineItems:  []LineItem{},
    CreatedAt:  now,
    UpdatedAt:  now,
  }
}
 
// => Id() exposes the private id — needed by repositories and event publishers.
func (po *PurchaseOrder) Id() PurchaseOrderId {
  return po.id
}

// => GRNId scopes the identity to good receipt notes.
type GRNId string
 
// => ReceivedItem records what actually arrived for a given line item.
// => QtyReceived may differ from PO quantity — partial deliveries are common.
type ReceivedItem struct {
  // => LineItemId links back to the PO line item for three-way match.
  LineItemId  LineItemId
  QtyReceived Quantity
  ReceivedAt  time.Time
}
 
// => GoodReceiptNote references PO and Supplier by ID — no cross-aggregate pointers.
type GoodReceiptNote struct {
  id           GRNId
  // => POId links to the originating PO without importing the PO aggregate.
  POId         PurchaseOrderId
  SupplierId   SupplierId
  ReceivedItems []ReceivedItem
  ReceivedAt   time.Time
  // => Finalized = true means no more items can be added — receipt is closed.
  Finalized    bool
}
 
func NewGoodReceiptNote(id GRNId, poID PurchaseOrderId, supplierID SupplierId) *GoodReceiptNote {
  return &GoodReceiptNote{
    id:           id,
    POId:         poID,
    SupplierId:   supplierID,
    ReceivedItems: []ReceivedItem{},
    ReceivedAt:   time.Now(),
    Finalized:    false,
  }
}
 
// => AddReceivedItem rejects additions to a finalized GRN.
func (g *GoodReceiptNote) AddReceivedItem(item ReceivedItem) error {
  if g.Finalized {
    // => Finalized GRN is immutable — prevents post-close modifications.
    return fmt.Errorf("cannot add items to a finalized GRN")
  }
  g.ReceivedItems = append(g.ReceivedItems, item)
  return nil
}
 
// => Finalize closes the GRN — triggers three-way match in the application layer.
func (g *GoodReceiptNote) Finalize() error {
  if len(g.ReceivedItems) == 0 {
    return fmt.Errorf("cannot finalize a GRN with no received items")
  }
  g.Finalized = true
  return nil
}

// => InvoiceId scopes identity to invoices — separate from PO and GRN IDs.
type InvoiceId string
 
// => InvoiceStatus tracks payment lifecycle — separate from POStatus.
type InvoiceStatus int
 
const (
  InvoiceDraft     InvoiceStatus = iota // 0
  InvoiceSubmitted                      // 1
  InvoiceApproved                       // 2
  InvoicePaid                           // 3
  InvoiceRejected                       // 4
)
 
// => Invoice references PO by ID — no cross-aggregate object reference.
type Invoice struct {
  id          InvoiceId
  // => POId links invoice to originating PO for three-way match.
  POId        PurchaseOrderId
  SupplierId  SupplierId
  // => Amount is the total invoice value — subject to three-way match check.
  Amount      Money
  DueDate     time.Time
  Status      InvoiceStatus
  // => SubmittedAt is nil until Submit() is called — pointer for optional time.
  SubmittedAt *time.Time
}
 
func NewInvoice(id InvoiceId, poID PurchaseOrderId, supplierID SupplierId, amount Money, dueDate time.Time) (*Invoice, error) {
  // => Zero-amount invoice is rejected — nothing to pay.
  if amount.IsZero() {
    return nil, fmt.Errorf("invoice amount must not be zero")
  }
  return &Invoice{
    id:         id,
    POId:       poID,
    SupplierId: supplierID,
    Amount:     amount,
    DueDate:    dueDate,
    // => InvoiceDraft is the only valid initial status.
    Status:     InvoiceDraft,
  }, nil
}
 
// => Submit transitions the invoice from Draft to Submitted.
// => Records SubmittedAt timestamp for SLA tracking.
func (inv *Invoice) Submit() error {
  if inv.Status != InvoiceDraft {
    return fmt.Errorf("can only submit a Draft invoice, current status: %d", inv.Status)
  }
  now := time.Now()
  inv.SubmittedAt = &now
  inv.Status = InvoiceSubmitted
  return nil
}

// => AddLineItem enforces two invariants before mutation:
// => 1. Only Draft POs accept new line items.
// => 2. No duplicate line item IDs within a PO.
func (po *PurchaseOrder) AddLineItem(item LineItem) error {
  // => Status guard: Submitted, Issued, etc. cannot accept new items.
  if po.Status != Draft {
    return fmt.Errorf("can only add items to a Draft PO, current status: %s", po.Status)
  }
  // => Duplicate check: iterate existing items to find ID collision.
  for _, existing := range po.LineItems {
    if existing.Id == item.Id {
      // => Duplicate ID is a domain error — two line items cannot share an ID.
      return fmt.Errorf("line item with ID %s already exists in PO %s", item.Id, po.id)
    }
  }
  // => Both invariants satisfied — safe to append.
  po.LineItems = append(po.LineItems, item)
  // => UpdatedAt records the time of this mutation for audit trail.
  po.UpdatedAt = time.Now()
  return nil
}
 
// => RemoveLineItem also guarded — only Draft POs allow item removal.
func (po *PurchaseOrder) RemoveLineItem(id LineItemId) error {
  if po.Status != Draft {
    return fmt.Errorf("can only remove items from a Draft PO")
  }
  for i, item := range po.LineItems {
    if item.Id == id {
      // => Slice removal preserves order — item at index i is removed.
      po.LineItems = append(po.LineItems[:i], po.LineItems[i+1:]...)
      po.UpdatedAt = time.Now()
      return nil
    }
  }
  return fmt.Errorf("line item with ID %s not found in PO %s", id, po.id)
}

// => Submit enforces two preconditions before transitioning status.
// => Application service calls Submit() — no direct status assignment.
func (po *PurchaseOrder) Submit() error {
  // => Only Draft POs can be submitted — prevents double-submission.
  if po.Status != Draft {
    return fmt.Errorf("can only submit a Draft PO, current status: %s", po.Status)
  }
  // => Empty PO has no business value — reject before queueing for approval.
  if len(po.LineItems) == 0 {
    return fmt.Errorf("cannot submit a PO with no line items")
  }
  // => Both preconditions satisfied — transition to Submitted.
  po.Status = Submitted
  // => UpdatedAt records transition time for SLA tracking.
  po.UpdatedAt = time.Now()
  return nil
}

// => ApprovedBy is stored on the PO for audit trail — who approved, when.
// => Add approvedBy field to PurchaseOrder struct if not already present.
func (po *PurchaseOrder) Approve(approvedBy string, level ApprovalLevel) error {
  // => Only ApprovalPending POs can be approved.
  if po.Status != ApprovalPending {
    return fmt.Errorf("can only approve an ApprovalPending PO, current: %s", po.Status)
  }
  // => Compute total value — this is a domain operation on the aggregate.
  total, err := po.TotalValue()
  if err != nil {
    return fmt.Errorf("computing total value: %w", err)
  }
  // => Check total value against the approval level's budget cap.
  capMoney, err := NewMoney(level.BudgetCapCents(), total.Currency)
  if err != nil {
    return fmt.Errorf("constructing cap money: %w", err)
  }
  exceedsCAP, err := total.GreaterThan(capMoney)
  if err != nil {
    return fmt.Errorf("comparing values: %w", err)
  }
  if exceedsCAP {
    // => Total exceeds level cap — requires escalation to higher tier.
    return fmt.Errorf("PO total %s exceeds approval level cap %s", total, capMoney)
  }
  // => Budget cap satisfied — transition to Issued.
  po.Status = Issued
  po.UpdatedAt = time.Now()
  return nil
}

// => RejectionNote stores the reason and who rejected — audit requirements.
// => Add RejectionNote field to PurchaseOrder struct.
type RejectionNote struct {
  Reason     string
  RejectedBy string
  RejectedAt time.Time
}
 
// => Reject transitions ApprovalPending → Cancelled with a mandatory reason.
func (po *PurchaseOrder) Reject(reason, rejectedBy string) error {
  // => Only ApprovalPending POs can be rejected.
  if po.Status != ApprovalPending {
    return fmt.Errorf("can only reject an ApprovalPending PO, current: %s", po.Status)
  }
  // => Blank reason is itself invalid — audit trail requires meaningful rejection notes.
  if strings.TrimSpace(reason) == "" {
    return fmt.Errorf("rejection reason must not be empty")
  }
  // => Store rejection details before changing status — defensive ordering.
  po.RejectionNote = &RejectionNote{
    Reason:     reason,
    RejectedBy: rejectedBy,
    RejectedAt: time.Now(),
  }
  // => Cancelled is the terminal state for rejected POs.
  po.Status = Cancelled
  po.UpdatedAt = time.Now()
  return nil
}

// => TotalValue sums all line item totals — the aggregate's financial representation.
// => Returns (Money, error) because TotalPrice can fail on currency inconsistency.
func (po *PurchaseOrder) TotalValue() (Money, error) {
  // => Empty PO has zero total — valid for read but not for submission.
  if len(po.LineItems) == 0 {
    // => Zero money in an empty currency — caller must handle this edge case.
    return Money{amountCents: 0, Currency: ""}, nil
  }
  // => Start accumulation with the first item's total.
  total, err := po.LineItems[0].TotalPrice()
  if err != nil {
    return Money{}, fmt.Errorf("computing line item 0 total: %w", err)
  }
  // => Iterate remaining items — Add will error if currencies differ.
  for i, item := range po.LineItems[1:] {
    itemTotal, err := item.TotalPrice()
    if err != nil {
      return Money{}, fmt.Errorf("computing line item %d total: %w", i+1, err)
    }
    total, err = total.Add(itemTotal)
    if err != nil {
      // => Currency mismatch across line items is an aggregate data error.
      return Money{}, fmt.Errorf("summing line items: %w", err)
    }
  }
  return total, nil
}

// => DomainEvent interface — minimal contract for all domain events.
// => EventType() returns a string tag used for routing in the event bus.
type DomainEvent interface {
  EventType() string
  // => OccurredAt() is immutable — events are facts, not mutable state.
  OccurredAt() time.Time
}
 
// => POCreated records the fact that a PO was created — past tense naming.
// => Past tense (Created, not Create) signals this is a fact, not a command.
type POCreated struct {
  POId           PurchaseOrderId
  SupplierId     SupplierId
  // => OccurredAtTime stored as a field — not recomputed on each call.
  OccurredAtTime time.Time
}
 
// => EventType returns a stable string tag for event routing.
// => String constant prevents typos in bus routing logic.
func (e POCreated) EventType() string { return "po.created" }
 
// => OccurredAt satisfies the DomainEvent interface — returns the stored time.
func (e POCreated) OccurredAt() time.Time { return e.OccurredAtTime }
 
// => POApproved carries the approved total for downstream finance systems.
type POApproved struct {
  POId           PurchaseOrderId
  ApprovedBy     string
  TotalValue     Money
  OccurredAtTime time.Time
}
 
func (e POApproved) EventType() string  { return "po.approved" }
func (e POApproved) OccurredAt() time.Time { return e.OccurredAtTime }

// => uncommittedEvents collects events raised during the current transaction.
// => They are NOT published until the application service drains them after save.
// => Add this field to the PurchaseOrder struct definition.
//    uncommittedEvents []DomainEvent
 
// => Emit appends an event to the internal buffer.
// => Private method — only aggregate methods call Emit.
func (po *PurchaseOrder) emit(event DomainEvent) {
  po.uncommittedEvents = append(po.uncommittedEvents, event)
}
 
// => DomainEvents exposes the uncommitted events for the application service.
// => Returns a copy — caller cannot mutate the internal slice.
func (po *PurchaseOrder) DomainEvents() []DomainEvent {
  result := make([]DomainEvent, len(po.uncommittedEvents))
  copy(result, po.uncommittedEvents)
  return result
}
 
// => ClearEvents is called by the application service after successful publish.
// => If publish fails, events are NOT cleared — they will be retried.
func (po *PurchaseOrder) ClearEvents() {
  po.uncommittedEvents = nil
}
 
// => NewPurchaseOrder updated to emit POCreated on construction.
func NewPurchaseOrder(id PurchaseOrderId, supplierID SupplierId) *PurchaseOrder {
  now := time.Now()
  po := &PurchaseOrder{
    id:         id,
    SupplierId: supplierID,
    Status:     Draft,
    LineItems:  []LineItem{},
    CreatedAt:  now,
    UpdatedAt:  now,
  }
  // => Emit the creation event immediately — before returning to the caller.
  po.emit(POCreated{
    POId:           id,
    SupplierId:     supplierID,
    OccurredAtTime: now,
  })
  return po
}

// => EventHandler is a small interface — one method, one responsibility.
// => context.Context enables cancellation and deadline propagation.
type EventHandler interface {
  Handle(ctx context.Context, event DomainEvent) error
}
 
// => Notifier is a port — application code depends on this interface, not SMTP.
type Notifier interface {
  Send(ctx context.Context, to, subject, body string) error
}
 
// => SupplierRepository is a port — application code depends on this interface.
type SupplierRepository interface {
  FindById(ctx context.Context, id SupplierId) (*Supplier, error)
}
 
// => POCreatedNotifier handles the po.created event — sends supplier notification.
// => Dependencies are interfaces — testable with fakes, no concrete coupling.
type POCreatedNotifier struct {
  notifier     Notifier
  supplierRepo SupplierRepository
}
 
func NewPOCreatedNotifier(n Notifier, sr SupplierRepository) *POCreatedNotifier {
  return &POCreatedNotifier{notifier: n, supplierRepo: sr}
}
 
func (h *POCreatedNotifier) Handle(ctx context.Context, event DomainEvent) error {
  // => Type assert to concrete event — handler only processes its event type.
  created, ok := event.(POCreated)
  if !ok {
    // => Ignore events that are not POCreated — idempotent no-op.
    return nil
  }
  // => Look up the supplier to get their contact email.
  supplier, err := h.supplierRepo.FindById(ctx, created.SupplierId)
  if err != nil {
    return fmt.Errorf("finding supplier for notification: %w", err)
  }
  // => Send the notification via the Notifier port.
  return h.notifier.Send(ctx, supplier.ContactEmail,
    "New Purchase Order Created",
    fmt.Sprintf("PO %s has been created and awaits your confirmation.", created.POId))
}