# TANRAIL ONE — Workflow & Transaction Specification

## 1. Overview
This document defines the critical state machines and workflow transitions for the core business entities within TANRAIL ONE. Guaranteeing state integrity is vital to prevent financial or operational errors.

## 2. Order Lifecycle Workflow
This applies to Core Sales, but may have variations in specific BUs (e.g., Restaurant).

### 2.1 States
- `Draft`: Being assembled, no financial or inventory impact.
- `Confirmed`: Customer agreed. Inventory may be reserved (allocated).
- `Fulfilling`: In progress (e.g., Kitchen cooking, Warehouse picking).
- `Fulfilled`: Delivered/Provided to customer. Inventory permanently deducted.
- `Invoiced`: Financial record created.
- `Paid`: Complete.
- `Cancelled`: Aborted. Must reverse inventory allocation.

### 2.2 Transitions & Effects
- `Draft` -> `Confirmed`: Trigger -> User action. Effect -> Verify stock levels.
- `Confirmed` -> `Fulfilled`: Trigger -> Operational action. Effect -> `StockMovement` created (decrease).
- `Fulfilled` -> `Invoiced`: Trigger -> System/User. Effect -> `Invoice` created in Finance module.

## 3. Inventory Workflow (Procurement to Consumption)

### 3.1 States (Purchase Order)
- `Requested`: Internal request for goods.
- `Approved`: Manager sign-off.
- `Ordered`: Sent to Supplier.
- `Partially Received`: Some items delivered.
- `Fully Received`: All items delivered.

### 3.2 Transaction Loop
```text
[PURCHASE ORDER] -> Approved -> Sent
       ↓
[RECEIPT] -> User logs incoming stock
       ↓
[STOCK TRANSACTION] -> System creates "Stock In" record
       ↓
[INVENTORY BALANCE] -> Balance increases for specific Branch/Location
       ↓
[EXPENSE / BILL] -> Accounts Payable created for Supplier
```

## 4. Financial Workflow (Invoices & Payments)

### 4.1 Invoice States
- `Draft`: Being drafted.
- `Issued`: Sent to customer. Expected in Accounts Receivable.
- `Partially Paid`: Customer made a partial payment.
- `Paid`: Fully settled.
- `Voided`: Cancelled due to error.

### 4.2 Reversal Handling
- **Rule:** Never DELETE an `Invoice` or `Payment` that has been `Issued` or applied.
- If an error occurs, the system must issue a **Credit Note** (reversing the financial impact) or an **Inventory Adjustment** (logging the correction).
- This ensures the Audit Trail remains intact.

## 5. Business-Specific Workflow Examples

### 5.1 Restaurant Table Workflow
- `Available` -> `Seated` (Trigger: Hostess action).
- `Seated` -> `Ordered` (Trigger: Waiter submits order to POS).
- `Ordered` -> `Billed` (Trigger: Waiter prints bill).
- `Billed` -> `Cleaning` (Trigger: Customer pays, leaves).
- `Cleaning` -> `Available` (Trigger: Busser confirms table ready).

### 5.2 Catering Event Workflow
- `Inquiry` -> Lead recorded.
- `Proposal` -> Menu and quote sent.
- `Contracted` -> Deposit paid, dates secured.
- `Preparation` -> Kitchen creates BOM/Prep lists.
- `Execution` -> Event occurs, delivery dispatched.
- `Completed` -> Final balance invoiced.