@tailor-platform/erp-kit 0.4.0 → 0.5.0

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

@@ -0,0 +1,50 @@
+# SetSupplierDefaultPurchasePaymentTerm
+
+## Overview
+
+SetSupplierDefaultPurchasePaymentTerm creates or updates the purchase-owned supplier profile for a company and assigns the default payment term used when new draft purchase orders are created for that supplier.
+
+## Business Rules
+
+- Supplier must exist and carry the `SUPPLIER` role
+- Supplier profile is unique per `companyId + supplierId`
+- Assigned payment term must exist, belong to the same company, and be active for new draft defaulting
+- Passing the same default term as the current profile is idempotent
+- Clearing the default term is allowed and preserves the supplier profile record for future procurement settings
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive supplier + company + paymentTermId] --> B{Supplier exists and is a SUPPLIER?}
+    B -->|No| C[Return supplier error]
+    B -->|Yes| D{Payment term provided?}
+    D -->|Yes| E{Payment term exists, same company, active?}
+    D -->|No| G[Upsert supplier profile with cleared default]
+    E -->|No| F[Return payment term error]
+    E -->|Yes| G[Upsert supplier profile with default term]
+    G --> H[Return supplier profile]
+```
+
+## External Dependencies
+
+- [business-partner::GetPartner](../../../business-partner/docs/queries/GetPartner.md) - Validate the supplier reference and partner role
+
+## Error Scenarios
+
+- **SUPPLIER_NOT_FOUND**: Supplier partner does not exist
+- **PARTNER_NOT_SUPPLIER**: Referenced partner does not carry the `SUPPLIER` role
+- **PAYMENT_TERM_NOT_FOUND**: Referenced purchase payment term does not exist
+- **PAYMENT_TERM_INACTIVE**: Referenced purchase payment term is inactive and cannot be used as a default
+- **COMPANY_SCOPE_MISMATCH**: Supplier profile company does not match the payment term company
+
+## Test Cases
+
+- creates a supplier profile when none exists
+- updates the default payment term on an existing supplier profile
+- clears the default payment term when explicit null is provided
+- returns error when supplier does not exist
+- returns error when partner is not a supplier
+- returns error when payment term does not exist
+- returns error when payment term is inactive
+- returns error when payment term belongs to a different company

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

@@ -0,0 +1,51 @@
+# SubmitPurchaseOrder
+
+## Overview
+
+SubmitPurchaseOrder validates that a draft purchase order is commercially complete and moves it into `SUBMITTED` status for review or approval.
+
+## Business Rules
+
+- Target purchase order must exist
+- Only orders in `DRAFT` status can be submitted
+- Submitted orders must contain at least one line
+- Every physical line must have a receiving site
+- Supplier must still carry the `SUPPLIER` role at submission time
+- External supplier order reference must be unique within the company when provided
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive submit request] --> B{Purchase order exists and is DRAFT?}
+    B -->|No| C[Return not found or invalid status]
+    B -->|Yes| D{At least one valid line?}
+    D -->|No| E[Return line validation error]
+    D -->|Yes| F{Supplier and external reference valid?}
+    F -->|No| G[Return supplier or duplicate reference error]
+    F -->|Yes| H[Set status to SUBMITTED]
+    H --> I[Return submitted order]
+```
+
+## External Dependencies
+
+- [business-partner::GetPartner](../../../business-partner/docs/queries/GetPartner.md) - Re-validate supplier role and status
+
+## Error Scenarios
+
+- **PURCHASE_ORDER_NOT_FOUND**: Target purchase order does not exist
+- **PURCHASE_ORDER_NOT_DRAFT**: Purchase order is not in `DRAFT` status
+- **EMPTY_PURCHASE_ORDER_LINES**: Purchase order has no lines
+- **RECEIVING_SITE_REQUIRED**: A physical-receipt line has no receiving site
+- **PARTNER_NOT_SUPPLIER**: Supplier no longer carries the `SUPPLIER` role
+- **DUPLICATE_EXTERNAL_SUPPLIER_ORDER_REFERENCE**: Another order already uses the same external supplier order reference in the company
+
+## Test Cases
+
+- submits a valid draft purchase order
+- returns error when purchase order does not exist
+- returns error when purchase order is not in draft
+- returns error when purchase order has no lines
+- returns error when a physical line has no receiving site
+- returns error when supplier is no longer classified as a supplier
+- returns error when external supplier order reference is duplicated

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

@@ -0,0 +1,48 @@
+# UpdateGoodsReceipt
+
+## Overview
+
+UpdateGoodsReceipt changes draft receipt quantities, receipt dates, or targeted lines before the receipt is posted.
+
+## Business Rules
+
+- Target goods receipt must exist
+- Only receipts in `DRAFT` status can be updated
+- Updated lines must satisfy the same validation rules as create
+- Posted receipts are immutable and must be corrected by a future compensating workflow instead of update
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update 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{Updated lines valid?}
+    F -->|No| G[Return validation error]
+    F -->|Yes| H[Update draft receipt]
+    H --> I[Return updated 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
+- **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
+
+## Test Cases
+
+- updates quantities on a draft goods receipt
+- updates receipt date on a draft goods receipt
+- returns error when goods receipt does not exist
+- returns error when goods receipt is not draft
+- returns error when updated line data is invalid
+- returns error when an updated receipt quantity is not positive
+- returns error when an updated receipt line has no open quantity remaining

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

@@ -0,0 +1,51 @@
+# UpdatePurchaseBill
+
+## Overview
+
+UpdatePurchaseBill revises draft supplier bill content before procurement matching is finalized.
+
+## Business Rules
+
+- Target purchase bill must exist
+- Only bills in `DRAFT` status can be updated
+- Updated invoice number must still be unique within supplier and company
+- Updated lines must satisfy the same validation rules as create
+- Once a bill has been matched, blocked, or cancelled, its comparison evidence is immutable
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Purchase bill exists?}
+    B -->|No| C[Return PURCHASE_BILL_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return PURCHASE_BILL_NOT_DRAFT]
+    D -->|Yes| F{Invoice number unique and lines valid?}
+    F -->|No| G[Return validation error]
+    F -->|Yes| H[Update draft bill]
+    H --> I[Return updated bill]
+```
+
+## External Dependencies
+
+- [business-partner::ListPartnerIdentificationsByPartner](../../../business-partner/docs/queries/ListPartnerIdentificationsByPartner.md) - Refresh supplier tax identification snapshot when draft bill data changes
+
+## Error Scenarios
+
+- **PURCHASE_BILL_NOT_FOUND**: Target purchase bill does not exist
+- **PURCHASE_BILL_NOT_DRAFT**: Purchase bill is not in `DRAFT` status
+- **DUPLICATE_SUPPLIER_INVOICE_NUMBER**: Supplier invoice number already exists in the same company and supplier scope
+- **PURCHASE_ORDER_LINE_NOT_FOUND**: Referenced purchase-order line does not exist
+- **INVALID_BILLED_QUANTITY**: Billed quantity is zero or negative
+- **PURCHASE_ORDER_CANCELLED**: Referenced purchase order is cancelled
+
+## Test Cases
+
+- updates invoice metadata on a draft purchase bill
+- updates bill lines on a draft purchase bill
+- returns error when purchase bill does not exist
+- returns error when purchase bill is not draft
+- returns error when updated invoice number is duplicated
+- returns error when updated line data is invalid
+- returns error when updated billed quantity is zero or negative
+- returns error when updated bill references a cancelled purchase order

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

@@ -0,0 +1,59 @@
+# UpdatePurchaseOrder
+
+## Overview
+
+UpdatePurchaseOrder revises mutable commercial data on a draft purchase order, including lines, supplier-facing price overrides, payment term selection, and receiving context.
+
+## Business Rules
+
+- Target purchase order must exist
+- Only orders in `DRAFT` status can be updated
+- Updated lines must satisfy the same validation rules as create
+- Draft buyers may override a defaulted supplier price while retaining the matched-rule reference for audit
+- Updating a purchase order never changes already ordered, received, or billed documents
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Purchase order exists?}
+    B -->|No| C[Return PURCHASE_ORDER_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return PURCHASE_ORDER_NOT_DRAFT]
+    D -->|Yes| F{Updated lines and references valid?}
+    F -->|No| G[Return validation error]
+    F -->|Yes| H[Update draft order and lines]
+    H --> I[Return updated order]
+```
+
+## External Dependencies
+
+- [business-partner::GetPartner](../../../business-partner/docs/queries/GetPartner.md) - Re-validate supplier identity and role when supplier-facing data changes
+- [item-management::GetItem](../../../item-management/docs/queries/GetItem.md) - Re-validate item references on changed lines
+- [organization::GetSite](../../../organization/docs/queries/GetSite.md) - Re-validate receiving site references
+
+## Error Scenarios
+
+- **PURCHASE_ORDER_NOT_FOUND**: Target purchase order does not exist
+- **PURCHASE_ORDER_NOT_DRAFT**: Purchase order is not in `DRAFT` status
+- **ITEM_NOT_FOUND**: Referenced item does not exist
+- **ITEM_NOT_ACTIVE**: Referenced item is inactive
+- **INVALID_QUANTITY**: Ordered quantity is zero or negative
+- **INVALID_UNIT_PRICE**: Unit price is negative
+- **RECEIVING_SITE_NOT_FOUND**: Referenced receiving site does not exist
+- **RECEIVING_SITE_REQUIRED**: A physical-receipt line has no receiving site
+- **PAYMENT_TERM_INACTIVE**: Selected payment term is inactive for new draft use
+
+## Test Cases
+
+- updates supplier-facing data on a draft purchase order
+- updates line pricing while preserving matched price-rule reference
+- returns error when purchase order does not exist
+- returns error when purchase order is not in draft
+- returns error when updated line data is invalid
+- returns error when an updated line item is inactive
+- returns error when an updated line quantity is not positive
+- returns error when an updated line unit price is negative
+- returns error when an updated receiving site does not exist
+- returns error when a physical-receipt line has no receiving site
+- returns error when selected payment term is inactive

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

@@ -0,0 +1,51 @@
+# UpdatePurchasePaymentTerm
+
+## Overview
+
+UpdatePurchasePaymentTerm changes the live definition of a purchase payment term without rewriting any historical snapshots already copied onto purchase orders or purchase bills.
+
+## Business Rules
+
+- Target payment term must exist
+- Updated schedule lines must continue to satisfy all create-time validation rules
+- Existing purchase orders and purchase bills keep their original snapshots after the term is updated
+- Updating an inactive term is allowed so it can be corrected before future reactivation
+- Company ownership of the term cannot be changed
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Payment term exists?}
+    B -->|No| C[Return PAYMENT_TERM_NOT_FOUND]
+    B -->|Yes| D{Schedule and discount data valid?}
+    D -->|No| E[Return validation error]
+    D -->|Yes| F[Update payment term and schedule lines]
+    F --> G[Return updated term]
+```
+
+## External Dependencies
+
+- [organization::GetCompany](../../../organization/docs/queries/GetCompany.md) - Preserve and validate existing company scope
+
+## Error Scenarios
+
+- **PAYMENT_TERM_NOT_FOUND**: Target payment term does not exist
+- **EMPTY_SCHEDULE**: No payment term schedule lines were provided
+- **INVALID_INSTALLMENT_TOTAL**: Percentage-based installment lines do not total 100 percent
+- **INVALID_SCHEDULE_LINE**: A schedule line contains a negative amount or percentage
+- **INVALID_DISCOUNT_CONFIGURATION**: Discount metadata is incomplete or inconsistent with the final due date
+- **IMMUTABLE_COMPANY_SCOPE**: Update attempted to move the term into another company
+
+## Test Cases
+
+- updates name and schedule lines on an active payment term
+- updates an inactive payment term without reactivating it
+- preserves historical purchase-order snapshots after update
+- preserves historical purchase-bill snapshots after update
+- returns error when payment term does not exist
+- returns error when the updated schedule is empty
+- returns error when updated schedule is invalid
+- returns error when an updated schedule line is invalid
+- returns error when an updated discount configuration is invalid
+- returns error when company scope is changed

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

@@ -0,0 +1,43 @@
+# UpdatePurchasePriceList
+
+## Overview
+
+UpdatePurchasePriceList updates descriptive metadata, validity notes, or deterministic priority on an existing supplier price list without changing historical order snapshots.
+
+## Business Rules
+
+- Target price list must exist
+- Company and supplier ownership are immutable
+- Updating a price list never rewrites purchase orders that already snapshotted one of its rules
+- Priority changes must preserve deterministic ordering for rule selection
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Price list exists?}
+    B -->|No| C[Return PRICE_LIST_NOT_FOUND]
+    B -->|Yes| D{Ownership unchanged and priority valid?}
+    D -->|No| E[Return validation error]
+    D -->|Yes| F[Update price list]
+    F --> G[Return updated list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PRICE_LIST_NOT_FOUND**: Target price list does not exist
+- **IMMUTABLE_OWNER_CHANGE**: Update attempted to change the supplier or company owner
+- **INVALID_LIST_PRIORITY**: Updated priority conflicts with deterministic rule ordering
+
+## Test Cases
+
+- updates metadata on an active price list
+- updates metadata on an inactive price list
+- preserves historical purchase-order snapshots after update
+- returns error when price list does not exist
+- returns error when supplier or company ownership is changed
+- returns error when updated priority is invalid

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

@@ -0,0 +1,60 @@
+# UpdatePurchasePriceRule
+
+## Overview
+
+UpdatePurchasePriceRule changes the live pricing condition on an existing supplier price rule without modifying any purchase orders that already snapshotted that rule's price.
+
+## Business Rules
+
+- Target rule must exist
+- Updated references and value fields must satisfy the same validation rules as create
+- Updating an inactive rule is allowed so it can be corrected before reactivation
+- Updated precedence must remain unique within the supplier pricing context
+- Historical purchase orders preserve the original ordered price even when the source rule changes
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Rule exists?}
+    B -->|No| C[Return PRICE_RULE_NOT_FOUND]
+    B -->|Yes| D{References and values valid?}
+    D -->|No| E[Return validation error]
+    D -->|Yes| F{Unique precedence?}
+    F -->|No| G[Return DUPLICATE_RULE_PRECEDENCE]
+    F -->|Yes| H[Update rule]
+    H --> I[Return updated rule]
+```
+
+## External Dependencies
+
+- [item-management::GetItem](../../../item-management/docs/queries/GetItem.md) - Validate item existence and active status
+- [primitives::GetCurrency](../../../primitives/docs/queries/GetCurrency.md) - Validate transaction currency
+- [primitives::GetUnit](../../../primitives/docs/queries/GetUnit.md) - Validate purchase unit of measure
+
+## Error Scenarios
+
+- **PRICE_RULE_NOT_FOUND**: Target price rule does not exist
+- **ITEM_NOT_FOUND**: Referenced item does not exist
+- **ITEM_NOT_ACTIVE**: Referenced item is inactive
+- **CURRENCY_NOT_FOUND**: Referenced currency does not exist
+- **UNIT_NOT_FOUND**: Referenced purchase unit does not exist
+- **INVALID_UNIT_PRICE**: Unit price is zero or negative
+- **INVALID_MINIMUM_QUANTITY**: Minimum quantity is negative
+- **INVALID_EFFECTIVE_RANGE**: Effective end date is earlier than effective start date
+- **DUPLICATE_RULE_PRECEDENCE**: Another rule already owns the same precedence context
+
+## Test Cases
+
+- updates price and quantity break on an active rule
+- updates an inactive rule without reactivating it
+- preserves historical purchase-order snapshots after update
+- returns error when rule does not exist
+- returns error when updated references are invalid
+- returns error when the updated item does not exist
+- returns error when the updated item is inactive
+- returns error when the updated unit does not exist
+- returns error when the updated unit price is not positive
+- returns error when the updated minimum quantity is negative
+- returns error when the updated effective range is inverted
+- returns error when updated precedence duplicates another rule

package/src/modules/purchase/docs/features/goods-receipt-matching.md

@@ -0,0 +1,71 @@
+# Goods Receipt Matching
+
+## Overview
+
+Goods Receipt Matching records what quantity from a purchase order has actually been received from the supplier. A `GoodsReceipt` references one purchase order and one or more purchase order lines, captures received quantities and receipt dates, and updates each line's received progress. The receipt document is the procurement-side confirmation that supplier fulfillment occurred.
+
+This feature deliberately separates **commercial receipt confirmation** from **warehouse stock execution**. Purchase owns the receipt document and the matching rules against the purchase order; inventory remains the owner of the resulting stock movement, putaway, lot or serial recording, and on-hand updates. That split makes receipts usable both for stock items and for service or non-stock procurement scenarios. The named handoff contract from purchase to inventory is `InboundReceiptHandoff`, whose minimum payload is purchase order reference, purchase order line reference, goods receipt reference, received quantity, unit of measure, and receipt date.
+
+## Business Purpose
+
+- Confirm supplier fulfillment against the original purchase commitment
+- Support partial deliveries and backorders without losing order-level visibility
+- Enforce over-receipt and under-receipt tolerance rules on purchase order lines
+- Provide the receipt basis required for 3-way supplier bill matching
+- Trigger downstream inbound stock or service-acceptance processes without moving warehouse logic into purchase
+- Preserve an auditable history of what was received, when, and against which supplier commitment
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Purchase Order in ORDERED status] --> B[Create Goods Receipt]
+    B --> C[Select open order lines]
+    C --> D[Enter received quantities and dates]
+    D --> E{Within tolerance?}
+    E -->|No| F[Block or require override]
+    E -->|Yes| G[Post Goods Receipt]
+    G --> H[Update PO line received quantities]
+    G --> I[Emit inbound receipt handoff to inventory]
+    H --> J{All quantities received?}
+    J -->|No| K[PO remains PARTIALLY RECEIVED]
+    J -->|Yes| L[PO becomes RECEIVED]
+    G --> M[Receipt eligible for supplier bill matching]
+```
+
+## Scenario Patterns
+
+- **Full delivery**: The supplier delivers every ordered line in one shipment and a single posted goods receipt completes the receiving side of the order
+- **Partial shipment with backorder**: Only half the quantity arrives. The receipt posts successfully, open quantity remains on the PO, and another receipt can be recorded later
+- **Overdelivery within tolerance**: A supplier sends 102 units against an order for 100 where a 2 percent over-receipt tolerance is allowed, so the receipt is accepted
+- **Overdelivery beyond tolerance**: A supplier sends materially more than ordered, and the receipt is blocked or requires an explicit procurement exception
+- **Split line receiving**: One line on the order is fully received while another remains open, and the receipt captures both outcomes in the same document
+- **Service acceptance**: A non-stock service line is marked received or accepted without creating warehouse-level stock, but the receipt still unlocks downstream bill matching
+- **Receipt date tracking**: The supplier shipment arrives late, and the posted receipt captures the actual date for lead-time and supplier-performance analysis
+- **Receipt correction before posting**: A receiver notices a quantity entry mistake while the receipt is still draft and corrects it before it updates PO fulfillment
+- **Future receipt reversal**: A posted receipt is later found to be incorrect. A future reversal workflow will preserve the original posted receipt, emit a compensating correction, and keep the audit trail intact rather than mutating history
+
+## Test Cases
+
+- Creating a goods receipt against an `ORDERED` purchase order with open quantity should succeed
+- A goods receipt line must reference a valid purchase order line and a received quantity greater than zero
+- A cancelled or closed purchase order must not accept new goods receipts
+- Posting a goods receipt must increase the referenced purchase order line's cumulative received quantity
+- Partial receipts must leave the remaining open quantity available for future receipts
+- Receiving more than the ordered quantity plus configured tolerance should fail or require an explicit override
+- Receiving against an inactive item or inactive supplier should be prevented if the order is no longer valid for execution
+- A goods receipt posted for a stock item should emit or call the downstream inventory handoff contract exactly once
+- The `InboundReceiptHandoff` payload must include purchase order reference, purchase order line reference, goods receipt reference, received quantity, UoM, and receipt date at minimum
+- A goods receipt posted for a non-stock or service line must not require warehouse stock execution
+- Only posted goods receipts should count toward 3-way supplier bill matching
+- Receipt posting must be isolated by company and must not update purchase orders belonging to another company
+- If a receipt is reversed or corrected through a future workflow, the purchase order received quantity must remain auditable rather than silently overwritten
+- Purchase order status should move to a partial or full receipt state based on aggregate posted receipt quantities
+- Only authorized receiving or procurement users should be able to post goods receipts
+- A goods receipt should preserve the supplier, order, and line references needed for audit and traceability
+
+## Reference Links
+
+- [Odoo vendor bills and three-way matching](https://www.odoo.com/documentation/19.0/applications/inventory_and_mrp/purchase/manage_deals/manage.html#vendor-bills)
+- [Oracle Fusion Cloud Procurement documentation](https://docs.oracle.com/en/cloud/saas/procurement/index.html)
+- [SAP receipt confirmation documentation](https://help.sap.com/docs/SAP_S4HANA_CLOUD/65de2977205c403bbc107264b8eccf4b/552eb9c732c14df6a2926efce6d890ad.html)

package/src/modules/purchase/docs/features/purchase-order-lifecycle.md

@@ -0,0 +1,87 @@
+# Purchase Order Lifecycle
+
+## Overview
+
+Purchase Order Lifecycle governs how a supplier commitment is created, reviewed, placed, fulfilled, and closed. A `PurchaseOrder` records the commercial agreement with a supplier for one or more items, including ordered quantity, expected delivery, unit price, currency, payment-term reference, and receiving site. The order is the primary document that downstream receipts and supplier bills match against.
+
+The lifecycle tracks both document control and fulfillment progress. A purchase order begins in draft, may be submitted for approval, can be explicitly rejected back to draft with a reason, becomes ordered when released to the supplier, then moves through partial or full receipt and partial or full billing states as execution proceeds. This gives procurement teams a single source of truth for what is still open with each supplier.
+
+## Business Purpose
+
+- Create a formal, auditable supplier commitment before goods or services are received
+- Freeze negotiated commercial terms at the time an order is placed, even if future price lists change
+- Capture the company and receiving-site context needed for receipt routing and supplier traceability
+- Track open quantity, received quantity, billed quantity, and remaining commitment per line
+- Provide the reference document required for receipt matching and supplier bill matching
+- Support partial fulfillment without losing visibility into remaining supplier obligations
+- Prevent inactive suppliers, inactive items, or incomplete orders from entering downstream execution
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Create Purchase Order] --> B[DRAFT]
+    B --> C[Add supplier, lines, prices, terms]
+    C --> D{Submit?}
+    D -->|No| C
+    D -->|Yes| E[SUBMITTED]
+    E --> F{Approve?}
+    F -->|Reject| R[REJECTED]
+    R --> B
+    F -->|Approve and send| G[ORDERED]
+    G --> H{Receipt posted?}
+    H -->|Partial| I[PARTIALLY RECEIVED]
+    H -->|Full| J[RECEIVED]
+    I --> K{Supplier bill matched?}
+    J --> K
+    K -->|Partial| L[PARTIALLY BILLED]
+    K -->|Full| M[BILLED]
+    I --> N{Close remaining?}
+    J --> N
+    L --> N
+    M --> N
+    N -->|Close| O[CLOSED]
+    B --> P[CANCELLED]
+    E --> P
+    G --> P
+```
+
+## Scenario Patterns
+
+- **Standard stock purchase**: A buyer creates an order for replenishment items, applies supplier pricing and payment terms, submits it, and sends it to the supplier once approved
+- **Rejected for revision**: An approver rejects a submitted order because the receiving site or supplier quote is wrong, and the order returns to draft with the rejection reason preserved for audit
+- **Split delivery**: A supplier confirms the order but ships in two batches. The purchase order remains open after the first receipt and closes only when all ordered quantity is received or explicitly closed out
+- **Price override before release**: A buyer starts from an automatically suggested supplier price rule but overrides one line before approval due to a one-time negotiated exception
+- **Service or non-stock procurement**: A purchase order is created for a supplier-provided service or consumable item that may still require bill matching even if no warehouse stock is updated
+- **Order cancellation before fulfillment**: An order is cancelled after submission because demand disappears and no receipt or bill has yet been matched
+- **Close remaining balance**: A supplier underdelivers the final 2 units and the buyer chooses to close the remaining open quantity instead of keeping the order indefinitely open
+- **Multi-line mixed fulfillment**: Some lines on the same order are fully received while others remain open, and line-level progress rolls up to the document status
+- **Supplier change control**: A buyer duplicates and revises a draft order rather than changing the supplier on an already ordered document, preserving traceability
+
+## Test Cases
+
+- Creating a purchase order with a valid ACTIVE supplier, company, and at least one line should succeed
+- A purchase order line must require an ACTIVE item, quantity greater than zero, and a non-negative unit price
+- Purchase orders can only be created in `DRAFT` status
+- A `DRAFT` order can be revised freely, but `ORDERED` commercial fields must not change without an explicit revision workflow
+- Submitting a purchase order without any lines should fail
+- Submitting a purchase order without a receiving site when the line requires physical receipt should fail
+- Submitting a purchase order for a partner that does not carry the SUPPLIER role should fail
+- Approving or ordering a purchase order whose supplier is INACTIVE should fail
+- Rejecting a submitted purchase order should record the rejection reason and return the document to `DRAFT`
+- Cancelling a purchase order after a posted receipt or matched supplier bill exists should be prevented
+- Posting a partial receipt should update line received quantities and move the order to a partial receipt status
+- Matching a supplier bill should update line billed quantities independently of receipt quantities
+- Closing a purchase order should be allowed only when all remaining open quantities are fulfilled, cancelled, or explicitly written off
+- Purchase order totals and open balances must be isolated per company
+- The applied unit price on a purchase order line must remain unchanged even if the underlying supplier price rule is later edited
+- A purchase order must preserve its assigned payment term snapshot for downstream bill due-date calculation
+- Each purchase order line should expose remaining quantity to receive and remaining quantity to bill
+- Duplicate external supplier order references should be rejected or flagged according to company policy
+- Only authorized procurement users should be able to submit, approve, cancel, or close purchase orders
+
+## Reference Links
+
+- [Odoo Purchase documentation](https://www.odoo.com/documentation/19.0/applications/inventory_and_mrp/purchase.html)
+- [Oracle Fusion Cloud Procurement guide](https://docs.oracle.com/en/cloud/saas/procurement/index.html)
+- [SAP procurement overview](https://help.sap.com/docs/SAP_S4HANA_CLOUD)

package/src/modules/purchase/docs/features/purchase-payment-terms.md

@@ -0,0 +1,67 @@
+# Purchase Payment Terms
+
+## Overview
+
+Purchase Payment Terms defines how supplier invoices become due once commercial purchasing is complete. A `PurchasePaymentTerm` models rules such as net days, end-of-month due dates, installment splits, and early-payment discounts. These terms can default onto purchase orders from the supplier's purchasing profile and flow forward into `PurchaseBill` so that the bill carries the expected supplier settlement schedule when handed off to accounts payable.
+
+The feature is intentionally limited to supplier-facing payable terms within procurement. It does not execute payment runs or post accounting entries. Instead, it standardizes the contractual timing information that purchasing and accounts payable both need.
+
+## Business Purpose
+
+- Standardize supplier settlement expectations across purchase orders and supplier bills
+- Reduce manual bill-entry work by defaulting due-date schedules from negotiated payment terms
+- Support installment or staged payment structures for large or milestone-based purchases
+- Enable early-payment discount handling by making discount windows explicit and reusable
+- Provide a consistent handoff contract from procurement to downstream accounts-payable processing
+- Separate payment timing rules from supplier master data so terms can evolve independently per transaction or agreement
+- Preserve how discountable amount is interpreted by explicitly recording whether discount logic applies to gross or net invoice amount
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Define Purchase Payment Term] --> B[Configure schedule lines and discount rules]
+    B --> C[Activate term]
+    C --> D[Default term from supplier purchasing profile or assign manually to PO]
+    D --> E[Supplier Bill created from order or entered manually]
+    E --> F[Copy payment term snapshot to bill]
+    F --> G[Calculate due dates and installment amounts]
+    G --> H[Bill becomes ready for downstream AP processing]
+```
+
+## Scenario Patterns
+
+- **Net 30 standard term**: A supplier agreement states payment is due 30 days after the invoice date, and every bill using that term receives a single due date 30 days later
+- **2/10 net 30**: A supplier grants a discount if the bill is paid within 10 days, otherwise full payment is due in 30 days. The term captures both the discount window and final due date
+- **Supplier default term propagation**: A supplier is configured with a default purchase payment term, and each new draft PO starts with that term before the buyer decides whether to override it
+- **Installment schedule**: A capital purchase requires 30 percent upfront and 70 percent after delivery. The payment term expresses two due schedule lines rather than a single maturity date
+- **End-of-month settlement**: Bills dated throughout the month become due at month end plus a fixed number of days, matching supplier accounting policy
+- **Term override for one PO**: A buyer uses the supplier's usual net 45 term on most orders but overrides a specific order to net 15 because of a negotiated expedited arrangement
+- **Term retirement**: An old payment term is deactivated when the supplier contract is renegotiated, but historical orders and bills retain the prior snapshot
+- **Manual supplier bill entry**: A bill is entered directly against a PO and inherits its purchase payment term even if no automatic bill generation exists
+- **Discount visibility for AP**: The matched supplier bill exposes the discount cutoff date so downstream AP automation can decide whether to pay early
+
+## Test Cases
+
+- Creating a purchase payment term with at least one schedule line should succeed
+- The sum of installment percentages on a percentage-based payment term must equal 100 percent
+- A payment term schedule line must not allow a negative percentage or negative fixed amount
+- A discount date must occur on or before the final due date
+- A payment term that offers early-payment discount must record whether the discount base is `GROSS_AMOUNT` or `NET_AMOUNT`
+- Inactive payment terms must not be assignable to new purchase orders or new supplier bills
+- When a supplier purchasing profile provides a default payment term, a new draft purchase order should inherit it automatically unless the buyer overrides it
+- A purchase order should snapshot its assigned payment term so later edits do not alter existing downstream bills
+- A supplier bill due-date schedule must be computable from the bill date and the assigned payment term
+- End-of-month terms must produce a due date based on calendar month logic rather than a simple fixed-day offset
+- Installment terms should generate multiple due schedule lines on the supplier bill
+- Early-payment discount metadata must remain available after bill matching so downstream AP can consume it
+- A payment term can be overridden on a draft purchase order but changing it after matched billing should be prevented or explicitly controlled
+- Purchase payment terms must be isolated by company when procurement policies differ by legal entity
+- Deactivating a payment term that is already referenced historically must preserve existing order and bill snapshots
+- Only authorized procurement or finance users should be able to create, update, activate, or deactivate payment terms
+
+## Reference Links
+
+- [Odoo payment terms documentation](https://www.odoo.com/documentation/19.0/applications/finance/accounting/customer_invoices/payment_terms.html)
+- [Oracle Fusion Cloud Financials and procurement documentation](https://docs.oracle.com/en/cloud/saas/index.html)
+- [SAP S/4HANA Cloud documentation](https://help.sap.com/docs/SAP_S4HANA_CLOUD)