@tailor-platform/erp-kit 0.4.0 → 0.5.0

package/src/modules/purchase/docs/queries/CalculatePurchasePrice.md

@@ -0,0 +1,53 @@
+# CalculatePurchasePrice
+
+## Overview
+
+CalculatePurchasePrice resolves the best matching supplier purchase price rule for a draft purchase-order line and returns the suggested unit price together with the matched rule reference.
+
+## Business Rules
+
+- Inputs include `companyId`, `supplierId`, `itemId`, ordered quantity, purchase unit, transaction currency, and order date
+- Only active price lists and active price rules participate in matching
+- Rule precedence is deterministic across supplier, price-list priority, item scope, purchase unit, minimum quantity break, effective date, and explicit rule priority
+- When purchase unit differs from the rule comparison unit, quantity comparison uses shared unit conversion
+- Currency conversion is out of scope; rules match only when the requested currency equals the rule currency
+- Returns null suggestion when no active rule matches and manual pricing is expected
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive supplier, item, qty, unit, currency, date] --> B{Item and units valid?}
+    B -->|No| C[Return reference error]
+    B -->|Yes| D[Load active lists and active rules for supplier/company]
+    D --> E[Normalize quantity for rule comparison]
+    E --> F[Filter rules by item, UoM, currency, date, and min qty]
+    F --> G{Rule found?}
+    G -->|No| H[Return null suggestion]
+    G -->|Yes| I[Pick highest precedence rule]
+    I --> J[Return suggested unit price and matched rule reference]
+```
+
+## External Dependencies
+
+- [item-management::GetItem](../../../item-management/docs/queries/GetItem.md) - Validate item existence and active status
+- [primitives::ConvertQuantity](../../../primitives/docs/queries/ConvertQuantity.md) - Compare quantity breaks across compatible units of measure
+
+## Error Scenarios
+
+- **ITEM_NOT_FOUND**: Referenced item does not exist
+- **ITEM_NOT_ACTIVE**: Referenced item is inactive
+- **UNIT_NOT_FOUND**: Referenced purchase unit does not exist
+- **CURRENCY_NOT_FOUND**: Referenced currency does not exist
+- **INCOMPATIBLE_UNITS**: Quantity-break comparison requires units that do not share a conversion path
+- **NO_MATCHING_PRICE_RULE**: No active rule matches; caller receives null suggestion
+
+## Test Cases
+
+- returns the best matching rule for a valid supplier item context
+- picks the higher quantity-break rule when ordered quantity qualifies
+- ignores inactive price lists and inactive rules
+- returns null when no active rule matches
+- returns error when item does not exist
+- returns error when item is inactive
+- returns error when units are incompatible for quantity-break comparison

package/src/modules/purchase/docs/queries/GetGoodsReceipt.md

@@ -0,0 +1,36 @@
+# GetGoodsReceipt
+
+## Overview
+
+GetGoodsReceipt retrieves a goods receipt with its receipt lines, receipt date, posting status, and inbound handoff metadata.
+
+## Business Rules
+
+- Lookup key is goods-receipt id
+- Returns receipts in any status so draft, cancelled, and posted receipts remain reviewable
+- Response includes referenced purchase-order and purchase-order-line links needed for audit and 3-way matching
+- Returns null when the goods receipt does not exist
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive goodsReceiptId] --> B[Select GoodsReceipt and receipt lines by id]
+    B --> C{Receipt found?}
+    C -->|Yes| D[Return goods receipt with lines and handoff metadata]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **GOODS_RECEIPT_NOT_FOUND**: No goods receipt exists for the given id; caller receives null
+
+## Test Cases
+
+- returns goods receipt when found
+- returns receipt lines and handoff metadata with the receipt
+- returns null when goods receipt does not exist

package/src/modules/purchase/docs/queries/GetPurchaseBill.md

@@ -0,0 +1,41 @@
+# GetPurchaseBill
+
+## Overview
+
+GetPurchaseBill retrieves a supplier bill together with its matching outcome, payable schedule snapshot, tax snapshot, and line-level purchase references.
+
+## Business Rules
+
+- Accepts lookup by `{ id }` or by `{ companyId, supplierId, invoiceNumber }`
+- Returns bills in any status so blocked, matched, and cancelled evidence remains available for audit
+- Response includes matching mode, variance reason, and due-schedule lines when available
+- Returns null when no purchase bill matches the lookup
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive lookup input] --> B{Lookup by id or supplier invoice identity?}
+    B -->|id| C[Select PurchaseBill by id]
+    B -->|invoice identity| D[Select PurchaseBill by company + supplier + invoice number]
+    C --> E{Bill found?}
+    D --> E
+    E -->|Yes| F[Load bill lines, tax snapshot, and due schedule]
+    E -->|No| G[Return null]
+    F --> H[Return purchase bill]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PURCHASE_BILL_NOT_FOUND**: No purchase bill matches the given lookup; caller receives null
+
+## Test Cases
+
+- returns purchase bill when found by id
+- returns purchase bill when found by supplier invoice identity
+- returns matching outcome and due schedule with the bill
+- returns null when purchase bill is not found

package/src/modules/purchase/docs/queries/GetPurchaseOrder.md

@@ -0,0 +1,42 @@
+# GetPurchaseOrder
+
+## Overview
+
+GetPurchaseOrder retrieves a single purchase order with its lines, frozen commercial snapshots, and fulfillment progress.
+
+## Business Rules
+
+- Accepts lookup by `{ id }` or by `{ companyId, externalSupplierOrderReference }`
+- Returns purchase orders in any status so cancelled and closed documents remain auditable
+- Response includes line-level remaining quantity to receive and remaining quantity to bill
+- Response includes payment-term snapshot and matched price-rule references when present
+- Returns null when no purchase order matches the lookup
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive lookup input] --> B{Lookup by id or external reference?}
+    B -->|id| C[Select PurchaseOrder by id]
+    B -->|external reference| D[Select PurchaseOrder by company + external reference]
+    C --> E{Order found?}
+    D --> E
+    E -->|Yes| F[Load lines, snapshots, and fulfillment totals]
+    E -->|No| G[Return null]
+    F --> H[Return purchase order]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PURCHASE_ORDER_NOT_FOUND**: No purchase order matches the given lookup; caller receives null
+
+## Test Cases
+
+- returns purchase order when found by id
+- returns purchase order when found by company and external supplier order reference
+- returns lines and fulfillment totals with the order
+- returns null when purchase order is not found

package/src/modules/purchase/docs/queries/GetPurchasePaymentTerm.md

@@ -0,0 +1,36 @@
+# GetPurchasePaymentTerm
+
+## Overview
+
+GetPurchasePaymentTerm retrieves one purchase payment term and all of its schedule lines by identifier.
+
+## Business Rules
+
+- Lookup key is payment-term id
+- Returns payment terms in any status so historical references remain readable
+- Response includes all schedule lines needed to compute installments and discount windows
+- Returns null when the payment term does not exist
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive paymentTermId] --> B[Select PurchasePaymentTerm and schedule lines by id]
+    B --> C{Term found?}
+    C -->|Yes| D[Return payment term with lines]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PAYMENT_TERM_NOT_FOUND**: No purchase payment term exists for the given id; caller receives null
+
+## Test Cases
+
+- returns purchase payment term when found
+- returns schedule lines with the term
+- returns null when purchase payment term does not exist

package/src/modules/purchase/docs/queries/GetPurchasePriceList.md

@@ -0,0 +1,36 @@
+# GetPurchasePriceList
+
+## Overview
+
+GetPurchasePriceList retrieves a supplier purchase price list together with all of its purchase price rules.
+
+## Business Rules
+
+- Lookup key is price-list id
+- Returns price lists in any status so historical supplier contracts remain inspectable
+- Response includes embedded purchase price rules and their current statuses
+- Returns null when the price list does not exist
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive priceListId] --> B[Select PurchasePriceList and rules by id]
+    B --> C{List found?}
+    C -->|Yes| D[Return price list with rules]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PRICE_LIST_NOT_FOUND**: No purchase price list exists for the given id; caller receives null
+
+## Test Cases
+
+- returns purchase price list when found
+- returns embedded purchase price rules with the list
+- returns null when purchase price list does not exist

package/src/modules/purchase/docs/queries/GetSupplierProfile.md

@@ -0,0 +1,36 @@
+# GetSupplierProfile
+
+## Overview
+
+GetSupplierProfile retrieves the purchase-owned supplier procurement profile for one company and supplier, including the default purchase payment term if one is configured.
+
+## Business Rules
+
+- Input lookup is `companyId + supplierId`
+- Returns the supplier profile for any persisted state because the model is standard, not lifecycle-driven
+- Returns the embedded default payment term reference when configured
+- Returns null when no purchase profile exists for the supplier in the company
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive companyId + supplierId] --> B[Select SupplierProfile by company and supplier]
+    B --> C{Profile found?}
+    C -->|Yes| D[Return supplier profile]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **SUPPLIER_PROFILE_NOT_FOUND**: No supplier profile exists for the given company and supplier; caller receives null
+
+## Test Cases
+
+- returns supplier profile when found
+- returns default payment term reference when configured
+- returns null when supplier profile does not exist

package/src/modules/purchase/generated/enums.ts

@@ -0,0 +1,63 @@
+/**
+ * Goods-receipt lifecycle status
+ */
+export const GoodsReceiptStatus = {
+  "DRAFT": "DRAFT",
+  "POSTED": "POSTED",
+  "CANCELLED": "CANCELLED"
+} as const;
+export type GoodsReceiptStatus = (typeof GoodsReceiptStatus)[keyof typeof GoodsReceiptStatus];
+
+/**
+ * Purchase-bill lifecycle status
+ */
+export const PurchaseBillStatus = {
+  "DRAFT": "DRAFT",
+  "BLOCKED": "BLOCKED",
+  "MATCHED": "MATCHED",
+  "CANCELLED": "CANCELLED"
+} as const;
+export type PurchaseBillStatus = (typeof PurchaseBillStatus)[keyof typeof PurchaseBillStatus];
+
+/**
+ * Purchase-order lifecycle status
+ */
+export const PurchaseOrderStatus = {
+  "DRAFT": "DRAFT",
+  "SUBMITTED": "SUBMITTED",
+  "ORDERED": "ORDERED",
+  "PARTIALLY_RECEIVED": "PARTIALLY_RECEIVED",
+  "RECEIVED": "RECEIVED",
+  "PARTIALLY_BILLED": "PARTIALLY_BILLED",
+  "BILLED": "BILLED",
+  "CANCELLED": "CANCELLED",
+  "CLOSED": "CLOSED"
+} as const;
+export type PurchaseOrderStatus = (typeof PurchaseOrderStatus)[keyof typeof PurchaseOrderStatus];
+
+/**
+ * Lifecycle status: ACTIVE, INACTIVE
+ */
+export const PurchasePaymentTermStatus = {
+  "ACTIVE": "ACTIVE",
+  "INACTIVE": "INACTIVE"
+} as const;
+export type PurchasePaymentTermStatus = (typeof PurchasePaymentTermStatus)[keyof typeof PurchasePaymentTermStatus];
+
+/**
+ * Lifecycle status: ACTIVE, INACTIVE
+ */
+export const PurchasePriceListStatus = {
+  "ACTIVE": "ACTIVE",
+  "INACTIVE": "INACTIVE"
+} as const;
+export type PurchasePriceListStatus = (typeof PurchasePriceListStatus)[keyof typeof PurchasePriceListStatus];
+
+/**
+ * Lifecycle status: ACTIVE, INACTIVE
+ */
+export const PurchasePriceRuleStatus = {
+  "ACTIVE": "ACTIVE",
+  "INACTIVE": "INACTIVE"
+} as const;
+export type PurchasePriceRuleStatus = (typeof PurchasePriceRuleStatus)[keyof typeof PurchasePriceRuleStatus];

package/src/modules/purchase/generated/kysely-tailordb.ts

@@ -0,0 +1,186 @@
+import {
+  createGetDB,
+  type Generated,
+  type Timestamp,
+  type NamespaceDB,
+  type NamespaceInsertable,
+  type NamespaceSelectable,
+  type NamespaceTable,
+  type NamespaceTableName,
+  type NamespaceTransaction,
+  type NamespaceUpdateable,
+} from "@tailor-platform/sdk/kysely";
+
+export interface Namespace {
+  "main-db": {
+    GoodsReceipt: {
+      id: Generated<string>;
+      companyId: string;
+      supplierId: string;
+      purchaseOrderId: string;
+      receiptDate: Timestamp;
+      status: "DRAFT" | "POSTED" | "CANCELLED";
+      lines: string;
+      inventoryHandoff: string | null;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    }
+
+    PurchaseBill: {
+      id: Generated<string>;
+      companyId: string;
+      supplierId: string;
+      invoiceNumber: string;
+      invoiceDate: Timestamp;
+      status: "DRAFT" | "BLOCKED" | "MATCHED" | "CANCELLED";
+      lines: string;
+      paymentTermSnapshot: string | null;
+      supplierTaxIdentification: string | null;
+      matchingMode: string | null;
+      varianceReason: string | null;
+      releaseReason: string | null;
+      dueSchedule: string | null;
+      downstreamAccepted: boolean;
+      comparisonEvidence: string | null;
+      billReadyHandoff: string | null;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    }
+
+    PurchaseOrder: {
+      id: Generated<string>;
+      companyId: string;
+      supplierId: string;
+      documentReceivingSiteId: string | null;
+      paymentTermId: string | null;
+      status: "DRAFT" | "SUBMITTED" | "ORDERED" | "PARTIALLY_RECEIVED" | "RECEIVED" | "PARTIALLY_BILLED" | "BILLED" | "CANCELLED" | "CLOSED";
+      orderDate: Timestamp;
+      externalSupplierOrderReference: string | null;
+      lines: string;
+      paymentTermSnapshot: string | null;
+      rejectionReason: string | null;
+      closeReason: string | null;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    }
+
+    PurchasePaymentTerm: {
+      id: Generated<string>;
+      companyId: string;
+      name: string;
+      code: string | null;
+      status: "ACTIVE" | "INACTIVE";
+      scheduleLines: string;
+      notes: string | null;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    }
+
+    PurchasePriceList: {
+      id: Generated<string>;
+      companyId: string;
+      supplierId: string;
+      name: string;
+      code: string | null;
+      priority: number;
+      status: "ACTIVE" | "INACTIVE";
+      notes: string | null;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    }
+
+    PurchasePriceRule: {
+      id: Generated<string>;
+      priceListId: string;
+      itemId: string;
+      currencyId: string;
+      unitId: string;
+      minimumQuantity: number;
+      unitPrice: number;
+      effectiveFrom: Timestamp;
+      effectiveTo: Timestamp | null;
+      priority: number;
+      status: "ACTIVE" | "INACTIVE";
+      notes: string | null;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    }
+
+    SupplierProfile: {
+      id: Generated<string>;
+      companyId: string;
+      supplierId: string;
+      defaultPurchasePaymentTermId: string | null;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    }
+
+    BusinessPartner: {
+      id: Generated<string>;
+      companyId: string | null;
+      name: string | null;
+      status: string | null;
+    }
+
+    Company: {
+      id: Generated<string>;
+      status: string | null;
+    }
+
+    Currency: {
+      id: Generated<string>;
+      code: string | null;
+      isActive: boolean | null;
+    }
+
+    Item: {
+      id: Generated<string>;
+      unitId: string | null;
+      status: string | null;
+      name: string | null;
+      sku: string | null;
+    }
+
+    PartnerIdentification: {
+      id: Generated<string>;
+      partnerId: string | null;
+      type: string | null;
+      value: string | null;
+      validFrom: Timestamp | null;
+      validTo: Timestamp | null;
+    }
+
+    PartnerRole: {
+      id: Generated<string>;
+      partnerId: string | null;
+      role: string | null;
+    }
+
+    Site: {
+      id: Generated<string>;
+      companyId: string | null;
+      status: string | null;
+    }
+
+    Unit: {
+      id: Generated<string>;
+      categoryId: string | null;
+      symbol: string | null;
+      isActive: boolean | null;
+    }
+  }
+}
+
+export const getDB = createGetDB<Namespace>();
+
+export type DB<N extends keyof Namespace = keyof Namespace> = NamespaceDB<Namespace, N>;
+
+export type Transaction<K extends keyof Namespace | DB = keyof Namespace> =
+  NamespaceTransaction<Namespace, K>;
+
+type TableName = NamespaceTableName<Namespace>;
+export type Table<T extends TableName> = NamespaceTable<Namespace, T>;
+
+export type Insertable<T extends TableName> = NamespaceInsertable<Namespace, T>;
+export type Selectable<T extends TableName> = NamespaceSelectable<Namespace, T>;
+export type Updateable<T extends TableName> = NamespaceUpdateable<Namespace, T>;

package/src/modules/purchase/index.ts

@@ -0,0 +1,2 @@
+export { defineModule } from "./module";
+export { permissions, own, all } from "./lib/permissions.generated";

package/src/modules/purchase/lib/_db_deps.ts

@@ -0,0 +1,77 @@
+// Stub types for cross-module dependencies — used only for codegen.
+// At runtime, actual types are injected via defineModule() params.
+import {
+  db,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+
+export const company = db
+  .type("Company", {
+    status: db.string({ optional: true }),
+  })
+  .permission(unsafeAllowAllTypePermission)
+  .gqlPermission(unsafeAllowAllGqlPermission);
+
+export const site = db
+  .type("Site", {
+    companyId: db.uuid({ optional: true }),
+    status: db.string({ optional: true }),
+  })
+  .permission(unsafeAllowAllTypePermission)
+  .gqlPermission(unsafeAllowAllGqlPermission);
+
+export const businessPartner = db
+  .type("BusinessPartner", {
+    companyId: db.uuid({ optional: true }),
+    name: db.string({ optional: true }),
+    status: db.string({ optional: true }),
+  })
+  .permission(unsafeAllowAllTypePermission)
+  .gqlPermission(unsafeAllowAllGqlPermission);
+
+export const partnerRole = db
+  .type("PartnerRole", {
+    partnerId: db.uuid({ optional: true }),
+    role: db.string({ optional: true }),
+  })
+  .permission(unsafeAllowAllTypePermission)
+  .gqlPermission(unsafeAllowAllGqlPermission);
+
+export const partnerIdentification = db
+  .type("PartnerIdentification", {
+    partnerId: db.uuid({ optional: true }),
+    type: db.string({ optional: true }),
+    value: db.string({ optional: true }),
+    validFrom: db.date({ optional: true }),
+    validTo: db.date({ optional: true }),
+  })
+  .permission(unsafeAllowAllTypePermission)
+  .gqlPermission(unsafeAllowAllGqlPermission);
+
+export const item = db
+  .type("Item", {
+    unitId: db.uuid({ optional: true }),
+    status: db.string({ optional: true }),
+    name: db.string({ optional: true }),
+    sku: db.string({ optional: true }),
+  })
+  .permission(unsafeAllowAllTypePermission)
+  .gqlPermission(unsafeAllowAllGqlPermission);
+
+export const currency = db
+  .type("Currency", {
+    code: db.string({ optional: true }),
+    isActive: db.bool({ optional: true }),
+  })
+  .permission(unsafeAllowAllTypePermission)
+  .gqlPermission(unsafeAllowAllGqlPermission);
+
+export const unit = db
+  .type("Unit", {
+    categoryId: db.uuid({ optional: true }),
+    symbol: db.string({ optional: true }),
+    isActive: db.bool({ optional: true }),
+  })
+  .permission(unsafeAllowAllTypePermission)
+  .gqlPermission(unsafeAllowAllGqlPermission);