# README

## Overview

This application is a generic **procurement & inventory management** ERP built on the
Tailor Platform using erp-kit modules. It covers the purchase-to-receipt lifecycle and
internal stock movement, with the supporting master data and access control an operations
team needs:

Key features:

- **Purchase Order lifecycle**: Create purchase orders in DRAFT, submit and approve them
  through a two-step confirmation into ORDERED, amend ORDERED orders, and close or cancel
  them. Follows `DRAFT → SUBMITTED → ORDERED → CLOSED` (with `CANCELLED` for abandoned drafts).
- **Inbound Shipment processing**: Record full or partial inbound shipments against a
  purchase order and post them to update inventory quantities and post the receipt's
  costing journal entry. "Create remaining inbound shipment" derives the outstanding
  quantity per PO line automatically.
- **Outbound Shipment processing**: Raise outbound shipments against a confirmed sales
  order and post them to reduce stock and advance the order's fulfillment status.
- **Inventory visibility**: A read-only stock-level list aggregated at Item × Site with
  item search and per-site filters, plus a per-storage-location drill-down.
- **Inventory cost tracking**: Standard costing — items are assigned a company-scoped
  valuation policy carrying posting accounts, standard costs are published as date-effective
  generations, and every valuation-affecting movement creates and posts a balanced journal
  entry in financial-accounting within the same transaction.
- **Financial accounting**: The financial-accounting module is wired alongside
  coa-management — fiscal years, accounting periods, and the journal entries produced by
  inventory costing are queryable (FiscalYear, AccountingPeriod, JournalEntry, JournalLine).
- **Transfer Orders**: Internal inventory transfers between two sites. Follows
  `DRAFT → OPEN → CLOSED`; close serves both settlement and abandonment (the native state
  machine has no separate cancel).
- **Product catalog & variants**: Products define variant axes (attributes such as Color,
  Size) that generate tradeable Items (SKUs) in item-management.
- **Master data**: Companies, Sites, Suppliers (Business Partners with role=SUPPLIER),
  Items, and Products.
- **User & Role management**: Role-based access control with per-role permission scopes.

It is built on the erp-kit modules: `primitives`, `organization`, `business-partner`,
`item-management`, `product-management`, `inventory`, `inbound-shipment`,
`outbound-shipment`, `purchase`, `sales`, `coa-management`, `financial-accounting`,
`account-payable`, and `user-management`. There are no local modules; resolvers are thin
wrappers over erp-kit native commands, apart from a few read-only aggregation queries (such
as the inventory stock-level list) that compute directly against the database.

## Industry Context

### Target Industry

Cross-industry procurement and inventory operations (distribution, manufacturing, retail
back-office).

### Domain Terminology

- **Purchase Order (PO)**: A document issued to a supplier authorizing the purchase of
  goods at agreed prices and quantities. Lifecycle: `DRAFT → SUBMITTED → ORDERED → CLOSED`.
- **Inbound Shipment (ISH)**: A goods-in document confirming physical receipt of goods
  against a purchase order. Can be full or partial. Stored as an `InboundShipment` header
  with `InboundShipmentLine` rows; posting it records the 入庫 stock increase.
- **Outbound Shipment (OSH)**: A goods-out document fulfilling a sales order. Stored as an
  `OutboundShipment` header with `OutboundShipmentLine` rows; posting it records the 出庫
  stock decrease.
- **Valuation Policy**: A company-scoped costing configuration (costing method
  STANDARD) carrying the company's posting accounts (inventory, accrual, invoice
  price variance, COGS, PPV, adjustment, standard cost adjustment, consumed price
  variance) for costing journal entries; one policy per company can be the default,
  auto-assigned to items on their first valuation-affecting movement.
- **Standard Cost**: A date-effective, append-only standard unit cost generation per item,
  published via `publishStandardCost`; publishing a new standard revalues on-hand stock
  against the standard cost adjustment account.
- **Supplier (Business Partner)**: An external entity from whom goods are purchased,
  modeled as a Business Partner with role=SUPPLIER.
- **Company**: A legal entity that issues purchase orders.
- **Site**: A physical location (warehouse, store) where goods are received and stored.
- **Storage Location**: A bin / sub-location within a Site where stock physically sits.
- **Product**: A commercial product definition with variant axes (attributes like Color,
  Size). Groups related Items and defines how variants are generated.
- **Product Attribute / Value**: A variant axis (e.g. Color) and its predefined values
  (e.g. Red, Blue) that drive variant generation.
- **Product Variant**: A specific combination of attribute values linked to a generated Item.
- **Item**: A purchasable product unit (SKU) tracked in inventory.
- **Transfer Order (TO)**: A document describing an internal inventory transfer between two
  Sites. Lifecycle: `DRAFT → OPEN → CLOSED`.
- **Stock Level**: An Item's quantities at a single storage location — `onHand`,
  `reserved`, `blocked`; the inventory-visibility list aggregates these up to Item × Site.
- **Available Quantity**: A derived value, `onHand − reserved − blocked` per row. Never stored.