--- id: SVC-COM-ORD-purchasing title: Purchasing Service Module product_area: commerce module: orders repository: services-commerce source_module: modules/purchasing revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b owns: - DOM-COM-ORD-006 does_not_own: - 'Inventory retains warehouse, item, movement, count, transfer and allocation records.' - Shipping retains stock handoff and its request for relief. - 'Accounting retains business units, products and journal posting.' operations: - operation_id: getPurchasingHealth intent: Expose purchasing runtime health and build information without customer records. access: public permission: 'none: public health route' realises: [] published_to_submissions: 'not published: runtime status is outside submission processing.' - operation_id: createVendor intent: Record supplier details with normalized email and address. access: console permission: commerce.purchasing.create realises: - CAP-COM-ORD-017 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: listVendors intent: Retrieve suppliers in name order with pagination. access: console permission: commerce.purchasing.read realises: - CAP-COM-ORD-017 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: getVendor intent: Retrieve the details of one supplier. access: console permission: commerce.purchasing.read realises: - CAP-COM-ORD-017 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: updateVendor intent: Replace supplier details with a version check. access: console permission: commerce.purchasing.update realises: - CAP-COM-ORD-017 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: deleteVendor intent: Remove a supplier only when acquisition records do not reference it. access: console permission: commerce.purchasing.delete realises: - CAP-COM-ORD-017 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: createPurchaseOrder intent: Draft and number a stock order with its requested lines. access: console permission: commerce.purchasing.create realises: - CAP-COM-ORD-017 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: listPurchaseOrders intent: 'Retrieve stock orders by recency with supplier, warehouse and status filters.' access: console permission: commerce.purchasing.read realises: - CAP-COM-ORD-017 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: getPurchaseOrder intent: Retrieve a stock order and its line quantities. access: console permission: commerce.purchasing.read realises: - CAP-COM-ORD-017 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: updatePurchaseOrder intent: 'Replace draft order contents at the read version, accepting returned read-only fields.' access: console permission: commerce.purchasing.update realises: - CAP-COM-ORD-017 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: issuePurchaseOrder intent: Move a draft into the issued stage eligible for receiving. access: console permission: commerce.purchasing.update realises: - CAP-COM-ORD-017 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: closePurchaseOrder intent: Conclude an eligible issued order and cancel its outstanding units. access: console permission: commerce.purchasing.update realises: - CAP-COM-ORD-017 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: cancelPurchaseOrder intent: End an unreceived draft or issued stock order. access: console permission: commerce.purchasing.update realises: - CAP-COM-ORD-017 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: cancelPurchaseOrderLineQuantity intent: Reduce the outstanding quantity of one line and recompute order progress. access: console permission: commerce.purchasing.update realises: - CAP-COM-ORD-017 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: recordInventoryReceipt intent: 'Record goods arrival once per key with stock, cost, posting and backorder effects.' access: console permission: commerce.purchasing.create realises: - CAP-COM-ORD-018 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: listInventoryReceipts intent: Retrieve goods receipts by recency with pagination. access: console permission: commerce.purchasing.read realises: - CAP-COM-ORD-018 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: getInventoryReceipt intent: Retrieve a receipt and its received lines. access: console permission: commerce.purchasing.read realises: - CAP-COM-ORD-018 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: listInventoryCostLayers intent: Retrieve acquisition layers in age order. access: console permission: commerce.inventory-costing.read realises: - CAP-COM-ORD-018 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: getInventoryCostLayer intent: Retrieve one acquisition-cost layer. access: console permission: commerce.inventory-costing.read realises: - CAP-COM-ORD-018 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: correctInventoryCostLayer intent: Revalue the unused portion into a correction layer and record its financial difference. access: console permission: commerce.inventory-costing.update realises: - CAP-COM-ORD-018 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: listCostRelief intent: 'Retrieve consumed and restored acquisition cost, optionally for one sale.' access: console permission: commerce.inventory-costing.read realises: - CAP-COM-ORD-018 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: getCostRelief intent: Retrieve one cost relief or restoration record. access: console permission: commerce.inventory-costing.read realises: - CAP-COM-ORD-018 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: readInventoryValuation intent: Compare remaining cost value with physical stock and expose the configured method. access: console permission: commerce.inventory-costing.read realises: - CAP-COM-ORD-018 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: getBusinessUnitSettings intent: 'Retrieve costing policy, defaulting unwritten settings to FIFO at version zero.' access: console permission: commerce.inventory-costing.read realises: - CAP-COM-ORD-018 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: putBusinessUnitSettings intent: Replace costing policy with a version check. access: console permission: commerce.inventory-costing.update realises: - CAP-COM-ORD-018 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: listInventoryPostings intent: 'Retrieve financial posting facts, including unposted facts for external intake.' access: console permission: commerce.inventory-costing.read realises: - CAP-COM-ORD-018 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: stampInventoryPostingsPosted intent: 'Attach Accounting posting references, replaying matches and refusing conflicts.' access: console permission: commerce.inventory-costing.update realises: - CAP-COM-ORD-018 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' - operation_id: getInventoryPosting intent: Retrieve one recorded financial posting fact. access: console permission: commerce.inventory-costing.read realises: - CAP-COM-ORD-018 published_to_submissions: 'not published: acquisition administration has no submitting workflow contract.' events: [] jobs: [] integrations: - system: Accounting direction: inbound contract: >- Posting intake retrieves pending acquisition facts and records their external posting association through purchasing routes. - system: Accounting products direction: outbound contract: Every cost write resolves the product business unit from Accounting. - system: Inventory and shipping (fulfilment module) direction: inbound contract: >- Inventory movements invoke cost relief, restoration, valuation and transfer operations within their own transactions. consistency: - rule: 'Receipt, stock, cost, quantities and waiting allocation share one keyed commit.' kind: transactional compensation: A failed receipt transaction leaves none of its effects. - rule: Cost writes participate in their source stock movement transaction. kind: transactional compensation: Uncovered quantities are recorded at zero cost and escalated rather than compensated. - rule: External intake can consume unposted facts and apply a unique posting reference. kind: eventual compensation: Repeated matching stamps retain the original posting association. evidence: - >- services-commerce at c8b66a98: modules/purchasing/aws/api/purchasing.routes.ts (route declarations), purchasing.schemas.ts, purchasing-api-mapper.ts; aws/purchasing.module.ts; services/**; db/*.table.ts; aws/commerce.service.ts (PurchasingPermissions, InventoryCostingPermissions). controls: [TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-LOG-004, TC-LOG-005, TC-AVL-002, TC-AVL-003, TC-MON-001, TC-MON-003, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-005, TC-VEN-001, TC-VEN-002, TC-VEN-003, TC-PRV-001, TC-PRV-002] --- # Purchasing Service Module ## What This Service Is For Purchasing supports supplier stock orders, goods receipt and acquisition-cost accounting. Its records explain stock value and cost of goods and provide facts for Accounting posting. ## Boundary The module owns suppliers, purchase orders, receipts, layers, relief, restoration, posting facts and costing settings. Inventory and shipping own physical movement and delivery. Their shared transaction calls couple movement and cost; moving purchasing's ownership remains an open question. ## Operations in Words Supplier and draft-order replacement require the read version. Issued orders support receipt, closure and limited cancellation. Keyed receiving creates stock and cost together. Cost reads and corrections expose acquisition value and pending posting facts, with a reference-checked posting stamp. Every HTTP operation is for console access and none is published to Submissions. ## Events and Jobs Purchasing declares no event stream or background job. The posting API supports an external Accounting intake without proving that intake exists. ## Consistency Guarantees Receipt effects and later movement costing commit together. Posting stamps retain one Accounting reference and reject conflicting repetitions. Missing cost coverage produces a recorded shortfall rather than invented acquisition value.