@tailor-platform/erp-kit 0.4.0 → 0.5.0

package/src/modules/purchase/db/purchasePaymentTerm.ts

@@ -0,0 +1,46 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { company as companyStub } from "../lib/_db_deps";
+
+export const PURCHASE_PAYMENT_TERM_STATUSES: [string, string] = ["ACTIVE", "INACTIVE"];
+
+export interface CreatePurchasePaymentTermTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  companyType?: TailorAnyDBType;
+}
+
+export function createPurchasePaymentTermType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreatePurchasePaymentTermTypeParams<F>,
+) {
+  return db
+    .type("PurchasePaymentTerm", {
+      companyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.companyType ?? companyStub },
+          backward: "purchasePaymentTerms",
+        })
+        .description("Foreign key to Company"),
+      name: db.string().description("Payment-term display name"),
+      code: db.string({ optional: true }).description("Optional payment-term code"),
+      status: db
+        .enum(PURCHASE_PAYMENT_TERM_STATUSES)
+        .description("Lifecycle status: ACTIVE, INACTIVE"),
+      scheduleLines: db
+        .string()
+        .description("Serialized schedule-line definition for payable scheduling"),
+      notes: db.string({ optional: true }).description("Optional descriptive notes"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const purchasePaymentTerm = createPurchasePaymentTermType({});

package/src/modules/purchase/db/purchasePriceList.ts

@@ -0,0 +1,53 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { businessPartner as businessPartnerStub, company as companyStub } from "../lib/_db_deps";
+
+export const PURCHASE_PRICE_LIST_STATUSES: [string, string] = ["ACTIVE", "INACTIVE"];
+
+export interface CreatePurchasePriceListTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  companyType?: TailorAnyDBType;
+  supplierType?: TailorAnyDBType;
+}
+
+export function createPurchasePriceListType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreatePurchasePriceListTypeParams<F>,
+) {
+  return db
+    .type("PurchasePriceList", {
+      companyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.companyType ?? companyStub },
+          backward: "purchasePriceLists",
+        })
+        .description("Foreign key to Company"),
+      supplierId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.supplierType ?? businessPartnerStub },
+          backward: "purchasePriceLists",
+        })
+        .description("Foreign key to supplier BusinessPartner"),
+      name: db.string().description("Price-list display name"),
+      code: db.string({ optional: true }).description("Optional price-list code"),
+      priority: db.int().description("Deterministic list priority within supplier scope"),
+      status: db
+        .enum(PURCHASE_PRICE_LIST_STATUSES)
+        .description("Lifecycle status: ACTIVE, INACTIVE"),
+      notes: db.string({ optional: true }).description("Optional descriptive notes"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const purchasePriceList = createPurchasePriceListType({});

package/src/modules/purchase/db/purchasePriceRule.ts

@@ -0,0 +1,74 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { currency as currencyStub, item as itemStub, unit as unitStub } from "../lib/_db_deps";
+import { purchasePriceList } from "./purchasePriceList";
+
+export const PURCHASE_PRICE_RULE_STATUSES: [string, string] = ["ACTIVE", "INACTIVE"];
+
+export interface CreatePurchasePriceRuleTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  priceListType?: TailorAnyDBType;
+  itemType?: TailorAnyDBType;
+  currencyType?: TailorAnyDBType;
+  unitType?: TailorAnyDBType;
+}
+
+export function createPurchasePriceRuleType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreatePurchasePriceRuleTypeParams<F>,
+) {
+  return db
+    .type("PurchasePriceRule", {
+      priceListId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.priceListType ?? purchasePriceList },
+          backward: "purchasePriceRules",
+        })
+        .description("Foreign key to PurchasePriceList"),
+      itemId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.itemType ?? itemStub },
+          backward: "purchasePriceRules",
+        })
+        .description("Foreign key to Item"),
+      currencyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.currencyType ?? currencyStub },
+          backward: "purchasePriceRules",
+        })
+        .description("Foreign key to Currency"),
+      unitId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.unitType ?? unitStub },
+          backward: "purchasePriceRules",
+        })
+        .description("Foreign key to Unit"),
+      minimumQuantity: db.float().description("Minimum quantity break for this rule"),
+      unitPrice: db.float().description("Rule price per purchase unit"),
+      effectiveFrom: db.date().description("Rule effective start date"),
+      effectiveTo: db.date({ optional: true }).description("Optional effective end date"),
+      priority: db.int().description("Deterministic rule priority within the list"),
+      status: db
+        .enum(PURCHASE_PRICE_RULE_STATUSES)
+        .description("Lifecycle status: ACTIVE, INACTIVE"),
+      notes: db.string({ optional: true }).description("Optional descriptive notes"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const purchasePriceRule = createPurchasePriceRuleType({});

package/src/modules/purchase/db/supplierProfile.ts

@@ -0,0 +1,59 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { businessPartner as businessPartnerStub, company as companyStub } from "../lib/_db_deps";
+import { purchasePaymentTerm } from "./purchasePaymentTerm";
+
+export interface CreateSupplierProfileTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  companyType?: TailorAnyDBType;
+  supplierType?: TailorAnyDBType;
+  paymentTermType?: TailorAnyDBType;
+}
+
+export function createSupplierProfileType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateSupplierProfileTypeParams<F>,
+) {
+  return db
+    .type("SupplierProfile", {
+      companyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.companyType ?? companyStub },
+          backward: "supplierProfiles",
+        })
+        .description("Foreign key to Company"),
+      supplierId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.supplierType ?? businessPartnerStub },
+          backward: "supplierProfiles",
+        })
+        .description("Foreign key to supplier BusinessPartner"),
+      defaultPurchasePaymentTermId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: params.paymentTermType ?? purchasePaymentTerm },
+          backward: "supplierProfiles",
+        })
+        .description("Optional default PurchasePaymentTerm"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .indexes({
+      fields: ["companyId", "supplierId"],
+      unique: true,
+      name: "supplier_profile_company_supplier_unique_idx",
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const supplierProfile = createSupplierProfileType({});

package/src/modules/purchase/docs/commands/ActivatePurchasePaymentTerm.md

@@ -0,0 +1,39 @@
+# ActivatePurchasePaymentTerm
+
+## Overview
+
+ActivatePurchasePaymentTerm re-enables a previously deactivated payment term so it can default onto new purchase orders and supplier bills again.
+
+## Business Rules
+
+- Target payment term must exist
+- Activating an already active payment term returns success without changing state
+- The term's schedule definition must still be internally valid at activation time
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate request] --> B{Payment term exists?}
+    B -->|No| C[Return PAYMENT_TERM_NOT_FOUND]
+    B -->|Yes| D{Already active?}
+    D -->|Yes| E[Return success with no-op]
+    D -->|No| F[Set status to ACTIVE]
+    F --> G[Return activated term]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PAYMENT_TERM_NOT_FOUND**: Target payment term does not exist
+- **INVALID_TERM_CONFIGURATION**: Term definition is no longer valid for activation
+
+## Test Cases
+
+- activates an inactive payment term
+- returns success when the payment term is already active
+- returns error when payment term does not exist
+- returns error when the payment term schedule is invalid at activation time

package/src/modules/purchase/docs/commands/ActivatePurchasePriceList.md

@@ -0,0 +1,37 @@
+# ActivatePurchasePriceList
+
+## Overview
+
+ActivatePurchasePriceList re-enables a previously retired supplier price list so its active rules can participate in new purchase price resolution.
+
+## Business Rules
+
+- Target price list must exist
+- Activating an already active list returns success without changing state
+- Reactivated lists do not alter historical order snapshots
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate request] --> B{Price list exists?}
+    B -->|No| C[Return PRICE_LIST_NOT_FOUND]
+    B -->|Yes| D{Already active?}
+    D -->|Yes| E[Return success with no-op]
+    D -->|No| F[Set status to ACTIVE]
+    F --> G[Return activated list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PRICE_LIST_NOT_FOUND**: Target price list does not exist
+
+## Test Cases
+
+- activates an inactive price list
+- returns success when the list is already active
+- returns error when price list does not exist

package/src/modules/purchase/docs/commands/ActivatePurchasePriceRule.md

@@ -0,0 +1,47 @@
+# ActivatePurchasePriceRule
+
+## Overview
+
+ActivatePurchasePriceRule re-enables a supplier purchase price rule so it can participate in future price resolution again.
+
+## Business Rules
+
+- Target rule must exist
+- Activating an already active rule returns success without changing state
+- Reactivated rules still require valid reference data and a non-conflicting precedence context
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate request] --> B{Rule exists?}
+    B -->|No| C[Return PRICE_RULE_NOT_FOUND]
+    B -->|Yes| D{Already active?}
+    D -->|Yes| E[Return success with no-op]
+    D -->|No| F{Rule still valid for activation?}
+    F -->|No| G[Return validation error]
+    F -->|Yes| H[Set status to ACTIVE]
+    H --> I[Return activated rule]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PRICE_RULE_NOT_FOUND**: Target price rule does not exist
+- **DUPLICATE_RULE_PRECEDENCE**: Another active rule already owns the same precedence context
+- **INVALID_RULE_CONFIGURATION**: Rule references or dates are no longer valid for activation
+
+## Test Cases
+
+- activates an inactive price rule
+- returns success when the rule is already active
+- returns error when rule does not exist
+- returns error when activation would conflict with another active rule
+- returns error when rule configuration is invalid at activation time
+- returns error when the referenced item no longer exists
+- returns error when the referenced item is inactive
+- returns error when the referenced currency no longer exists
+- returns error when the referenced unit no longer exists

package/src/modules/purchase/docs/commands/ApprovePurchaseOrder.md

@@ -0,0 +1,55 @@
+# ApprovePurchaseOrder
+
+## Overview
+
+ApprovePurchaseOrder moves a submitted purchase order into `ORDERED` status, freezes the commercial agreement, and records the order as ready for supplier execution.
+
+## Business Rules
+
+- Target purchase order must exist
+- Only orders in `SUBMITTED` status can be approved
+- Supplier must still be active and classified as a supplier
+- Referenced items must still be active for operational execution
+- Approval freezes the ordered unit prices, matched price-rule references, and payment-term snapshot
+- Approving an order does not create stock movement or billing records
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive approve request] --> B{Purchase order exists?}
+    B -->|No| C[Return PURCHASE_ORDER_NOT_FOUND]
+    B -->|Yes| D{Status is SUBMITTED?}
+    D -->|No| E[Return PURCHASE_ORDER_NOT_SUBMITTED]
+    D -->|Yes| F{Supplier and items still active?}
+    F -->|No| G[Return execution reference error]
+    F -->|Yes| H[Freeze payment term and line price snapshots]
+    H --> I[Set status to ORDERED]
+    I --> J[Return approved order]
+```
+
+## External Dependencies
+
+- [business-partner::GetPartner](../../../business-partner/docs/queries/GetPartner.md) - Re-validate supplier status and role before ordering
+- [item-management::GetItem](../../../item-management/docs/queries/GetItem.md) - Re-validate item status before ordering
+
+## Error Scenarios
+
+- **PURCHASE_ORDER_NOT_FOUND**: Target purchase order does not exist
+- **PURCHASE_ORDER_NOT_SUBMITTED**: Purchase order is not in `SUBMITTED` status
+- **SUPPLIER_NOT_ACTIVE**: Supplier is inactive at approval time
+- **PARTNER_NOT_SUPPLIER**: Supplier no longer carries the `SUPPLIER` role
+- **ITEM_NOT_ACTIVE**: One or more referenced items are inactive
+- **MISSING_COMMERCIAL_SNAPSHOT**: Required payment-term or price snapshot data is missing
+
+## Test Cases
+
+- approves a valid submitted purchase order
+- freezes payment-term snapshot at approval time
+- freezes ordered line prices and matched rule references at approval time
+- returns error when purchase order does not exist
+- returns error when purchase order is not submitted
+- returns error when supplier is inactive
+- returns error when an item is inactive
+- returns error when supplier is no longer classified as a supplier
+- returns error when approval cannot reconstruct the commercial snapshot

package/src/modules/purchase/docs/commands/CancelGoodsReceipt.md

@@ -0,0 +1,39 @@
+# CancelGoodsReceipt
+
+## Overview
+
+CancelGoodsReceipt abandons a draft goods receipt before it affects purchase-order fulfillment or inventory execution.
+
+## Business Rules
+
+- Target goods receipt must exist
+- Only receipts in `DRAFT` status can be cancelled
+- Cancelling a draft receipt does not change purchase-order received quantity
+- Posted receipts cannot be cancelled; they require a future compensating correction workflow
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive cancel request] --> B{Goods receipt exists?}
+    B -->|No| C[Return GOODS_RECEIPT_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return GOODS_RECEIPT_NOT_DRAFT]
+    D -->|Yes| F[Set status to CANCELLED]
+    F --> G[Return cancelled receipt]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **GOODS_RECEIPT_NOT_FOUND**: Target goods receipt does not exist
+- **GOODS_RECEIPT_NOT_DRAFT**: Goods receipt is not in `DRAFT` status
+
+## Test Cases
+
+- cancels a draft goods receipt
+- returns error when goods receipt does not exist
+- returns error when goods receipt is already posted

package/src/modules/purchase/docs/commands/CancelPurchaseBill.md

@@ -0,0 +1,49 @@
+# CancelPurchaseBill
+
+## Overview
+
+CancelPurchaseBill voids a draft, blocked, or matched supplier bill while the bill is still owned by purchase and has not yet been accepted by downstream AP or accounting.
+
+## Business Rules
+
+- Target purchase bill must exist
+- Only bills in `DRAFT`, `BLOCKED`, or `MATCHED` can be cancelled
+- Cancellation is forbidden after downstream AP or accounting accepts the bill-ready handoff
+- Cancellation preserves invoice identity, line references, and variance evidence for future dispute or credit-note workflows
+- Cancelling a matched bill reverses the purchase-order billed quantity that was previously accumulated from that bill
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive cancel request] --> B{Purchase bill exists?}
+    B -->|No| C[Return PURCHASE_BILL_NOT_FOUND]
+    B -->|Yes| D{Status cancellable?}
+    D -->|No| E[Return PURCHASE_BILL_NOT_CANCELLABLE]
+    D -->|Yes| F{Downstream handoff already accepted?}
+    F -->|Yes| G[Return DOWNSTREAM_HANDOFF_ACCEPTED]
+    F -->|No| H[Preserve evidence and set CANCELLED]
+    H --> I[Adjust PO billed quantity if previously matched]
+    I --> J[Return cancelled bill]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PURCHASE_BILL_NOT_FOUND**: Target purchase bill does not exist
+- **PURCHASE_BILL_NOT_CANCELLABLE**: Purchase bill status does not allow cancellation
+- **DOWNSTREAM_HANDOFF_ACCEPTED**: Downstream AP or accounting already accepted the bill-ready handoff
+
+## Test Cases
+
+- cancels a draft purchase bill
+- cancels a blocked purchase bill
+- cancels a matched purchase bill before downstream acceptance
+- preserves variance evidence when a blocked bill is cancelled
+- reverses purchase-order billed quantity when a matched bill is cancelled
+- returns error when purchase bill does not exist
+- returns error when purchase bill status does not allow cancellation
+- returns error when downstream handoff has already been accepted

package/src/modules/purchase/docs/commands/CancelPurchaseOrder.md

@@ -0,0 +1,47 @@
+# CancelPurchaseOrder
+
+## Overview
+
+CancelPurchaseOrder stops a purchase order before fulfillment becomes irreversible and moves it into `CANCELLED` status.
+
+## Business Rules
+
+- Target purchase order must exist
+- Only orders in `DRAFT`, `SUBMITTED`, or `ORDERED` can be cancelled
+- Cancellation is forbidden once a posted goods receipt exists
+- Cancellation is forbidden once a matched supplier bill exists
+- Cancelling preserves the original order for audit and traceability
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive cancel request] --> B{Purchase order exists?}
+    B -->|No| C[Return PURCHASE_ORDER_NOT_FOUND]
+    B -->|Yes| D{Status cancellable?}
+    D -->|No| E[Return PURCHASE_ORDER_NOT_CANCELLABLE]
+    D -->|Yes| F{Posted receipt or matched bill exists?}
+    F -->|Yes| G[Return PURCHASE_ORDER_ALREADY_FULFILLED]
+    F -->|No| H[Set status to CANCELLED]
+    H --> I[Return cancelled order]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PURCHASE_ORDER_NOT_FOUND**: Target purchase order does not exist
+- **PURCHASE_ORDER_NOT_CANCELLABLE**: Purchase order status does not allow cancellation
+- **PURCHASE_ORDER_ALREADY_FULFILLED**: Posted receipts or matched bills already exist against the order
+
+## Test Cases
+
+- cancels a draft purchase order
+- cancels a submitted purchase order
+- cancels an ordered purchase order with no receipts or matched bills
+- returns error when purchase order does not exist
+- returns error when purchase order status does not allow cancellation
+- returns error when a posted receipt already exists
+- returns error when a matched bill already exists

package/src/modules/purchase/docs/commands/ClosePurchaseOrder.md

@@ -0,0 +1,49 @@
+# ClosePurchaseOrder
+
+## Overview
+
+ClosePurchaseOrder finalizes a partially fulfilled or fully fulfilled purchase order and prevents further receipt or billing activity on the remaining open quantity.
+
+## Business Rules
+
+- Target purchase order must exist
+- Only orders in `PARTIALLY_RECEIVED`, `RECEIVED`, `PARTIALLY_BILLED`, or `BILLED` can be closed
+- Remaining open quantity must already be fully received, fully billed, or explicitly written off with a close reason
+- Closing preserves the original ordered, received, and billed quantities for audit
+- Closed orders reject new goods receipts and new purchase bills
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive close request] --> B{Purchase order exists?}
+    B -->|No| C[Return PURCHASE_ORDER_NOT_FOUND]
+    B -->|Yes| D{Status closable?}
+    D -->|No| E[Return PURCHASE_ORDER_NOT_CLOSABLE]
+    D -->|Yes| F{Open quantity fully resolved or write-off reason provided?}
+    F -->|No| G[Return OPEN_QUANTITY_REMAINS]
+    F -->|Yes| H[Set status to CLOSED]
+    H --> I[Return closed order]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PURCHASE_ORDER_NOT_FOUND**: Target purchase order does not exist
+- **PURCHASE_ORDER_NOT_CLOSABLE**: Purchase order status does not allow closure
+- **OPEN_QUANTITY_REMAINS**: Remaining quantity is not fulfilled or explicitly written off
+- **CLOSE_REASON_REQUIRED**: Residual open quantity exists but no write-off reason was provided
+
+## Test Cases
+
+- closes a fully billed purchase order
+- closes a partially received order when remaining quantity is explicitly written off
+- allows closure without write-off when each line is fully received
+- returns error when purchase order does not exist
+- returns error when purchase order status does not allow closure
+- returns error when unresolved open quantity remains
+- returns error when residual quantity exists without a close reason
+- returns OPEN_QUANTITY_REMAINS before requiring a close reason when write-off is not requested

package/src/modules/purchase/docs/commands/CreateGoodsReceipt.md

@@ -0,0 +1,54 @@
+# CreateGoodsReceipt
+
+## Overview
+
+CreateGoodsReceipt creates a draft goods receipt against one purchase order with one or more targeted purchase-order lines.
+
+## Business Rules
+
+- Purchase order must exist and belong to the same company as the receipt
+- Purchase order must not be cancelled or closed
+- At least one receipt line is required
+- Each receipt line must reference a valid purchase-order line with open quantity
+- Each receipt line must record a received quantity greater than zero
+- Goods receipts are created in `DRAFT` status
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Purchase order exists and is receivable?}
+    B -->|No| C[Return purchase order error]
+    B -->|Yes| D{At least one line?}
+    D -->|No| E[Return EMPTY_RECEIPT_LINES]
+    D -->|Yes| F{Each line references open PO quantity and qty > 0?}
+    F -->|No| G[Return line validation error]
+    F -->|Yes| H[Insert goods receipt in DRAFT]
+    H --> I[Return created receipt]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PURCHASE_ORDER_NOT_FOUND**: Referenced purchase order does not exist
+- **PURCHASE_ORDER_NOT_RECEIVABLE**: Purchase order is cancelled, closed, or otherwise unavailable for receipt
+- **EMPTY_RECEIPT_LINES**: No goods-receipt lines were provided
+- **PURCHASE_ORDER_LINE_NOT_FOUND**: Referenced purchase-order line does not exist
+- **NO_OPEN_RECEIPT_QUANTITY**: Purchase-order line has no remaining open quantity to receive
+- **INVALID_RECEIVED_QUANTITY**: Received quantity is zero or negative
+- **COMPANY_SCOPE_MISMATCH**: Goods receipt company does not match the purchase order company
+
+## Test Cases
+
+- creates a draft goods receipt against an ordered purchase order
+- creates a draft goods receipt against a partially received purchase order
+- returns error when purchase order does not exist
+- returns error when purchase order is cancelled or closed
+- returns error when no receipt lines are provided
+- returns error when a purchase-order line does not exist
+- returns error when a receipt line has no open quantity
+- returns error when received quantity is zero or negative
+- returns error when goods receipt company does not match the purchase order company