Skip to content

Create empty order

Description

The system UI presents a blank form to the User so that they can fill in the information of the header and add PoLines.

The user can:

  1. Edit the order header fields.
  2. save the Order keeping it as NEW
  3. approve the order, triggering validation and placing it in the APPROVED state. The Order becomes readonly reflecting the fact that it now represents a contract between
    the Customer and the Vendor. When more refined permissions are available in the system, editability may be restricted only for certain permissions/roles and not others.
  4. Add Order Lines to the order.

Requirement

  • Provide a backend operation to persist a blank order header with no lines, exposing the resulting OrderRecord to the caller.
  • Implementation entry points:
    • OrderHelper.addEmptyOrder(header: OrderHeader, ...) (operations/src/main/kotlin/cards/arda/operations/procurement/orders/service/OrderHelper.kt:421-436)
    • OrderHelper.addEmptyOrder(headerEid: UUID, orderNumber: String, ...) (OrderHelper.kt:442-451) for flows that only supply an identifier and order number.

Preconditions

  • Caller must provide an OrderMetadata payload and author identifier.
  • When supplying a fully formed OrderHeader, the caller is responsible for ensuring its fields (e.g., status, supplierName) comply with domain rules. No additional validation is performed beyond what the database layer enforces.
  • When only headerEid and orderNumber are supplied, the helper composes a header with defaults and does not validate uniqueness of the identifier beyond underlying database constraints.

Scenario Overview

  1. Compose (or accept) an OrderHeader, defaulting to OrderStatus.NEW, allowPartial = true, and deliverBy = now + 7 days when the helper generates the header (operations/src/main/kotlin/cards/arda/operations/procurement/orders/service/OrderHelper.kt:261-283).
  2. Persist the header through DataAuthorityService.add, obtaining an EntityRecord snapshot for the header (OrderHelper.kt:430-435).
  3. Evaluate OrderHelper.linesQuery to build an empty PageResult, producing an OrderRecord with zero lines (OrderHelper.kt:431-433).
  4. Invoke the supplied postProcess callback with the freshly created OrderRecord; any failure is propagated without additional changes (OrderHelper.kt:434-435).

PostConditions

  • A new order header version exists in the database with no lines attached.
  • The returned OrderRecord includes pagination metadata pointing to the header’s line universe so that clients can append lines later.
  • No automatic notifications or workflow transitions are triggered; callers must orchestrate subsequent steps (e.g., approval, Kanban updates).

Creation of Order Lines

None performed by this helper; the initial OrderRecord always contains an empty PageResult for lines.

Changes to Order Header

  • Default field values (status = NEW, allowPartial = true, deliverBy = orderDate + 1 week, etc.) are populated only when the helper composes the header.
  • goodsValue, supplierName, and other derived attributes remain whatever the caller supplied (typically null) because there are no lines to aggregate yet.

Changes to Order Header

Comments