# Document Lifecycle And Status

## Status Values

Document status is stored as an integer column on each transaction table. The meaning is consistent across most document types but not guaranteed to be identical everywhere — always read the manager before assuming.

### Sales and Purchase Invoices (`td_invoice`, all `doc_type` values)

| Status | Meaning |
|---|---|
| `0` | Draft |
| `1` | Issued / Active |
| `2` | Paid / Settled (fully allocated) |
| `4` | Void |

`doc_type` values on `td_invoice`: `invoice`, `credit_note`, `purchase_invoice`, `supplier_credit_note`.

Voiding is handled by a shared status endpoint. When a document is voided, `InvoiceManager` calls `GlManager::delete()` to remove any posted GL entry. Void is blocked if settlement documents (receipts or payments) are still allocated to the invoice — those must be voided first.

### Receipts and Payments (`td_receipt`, `td_payment`)

| Status | Meaning |
|---|---|
| `1` | Active / posted business document |
| `4` | Void |

Void calls `GlManager::delete()` through `ReceiptManager` and `PaymentManager` respectively. Posting window is enforced on both save and void.

### Receipt Billing Notes and Payment Billing Notes (`td_receipt_billing`, `td_payment_billing`)

Billing notes group one or more invoices into a single collection document sent to a customer (receipt billing) or supplier (payment billing). Each line in `td_receipt_billing_item` / `td_payment_billing_item` references a `td_invoice.id` and carries an allocated amount.

| Status | Meaning |
|---|---|
| `1` | Open — no receipts / payments posted against it yet |
| `2` | Fully received / paid — allocated receipts or payments equal the billing total |
| `3` | Partially received / paid — some but not all receipts or payments have been posted |
| `4` | Void |

Status is never set manually — `ReceiptBillingManager::refreshBillingStatus()` and `PaymentBillingManager::refreshBillingStatus()` derive and write the correct value after each receipt or payment change.

Void is blocked if any posted receipt (`td_receipt.status = 1`) or payment (`td_payment.status = 1`) is allocated to the billing note — those must be voided first. Voiding a billing note does **not** void the invoices it references. Invoices cannot be voided while an active billing note (`status` ∈ `{1, 2, 3}`) references them.

### Quotations (`td_quotation`)

| Status | Meaning |
|---|---|
| `-1` | Cancelled |
| `0` | Draft |
| `1` | Sent |
| `2` | Accepted |
| `3` | Rejected |
| `5` | Converted |

Status transitions are enforced by `QuotationManager::updateStatus()`:

- `0 → 1` (send), `1 → 2` (accept), `1 → 3` (reject)
- `1 / 2 / 3 → 0` (reopen) — blocked if any item already has `converted_qty > 0`
- `0 / 1 → -1` (cancel)

`status = 5` is never set via `updateStatus()`. It is written automatically by `QuotationManager::incrementConvertedQty()` once all line items are fully converted to a sales order. `OrderManager::linkQuotationToOrder()` calls this after a successful order creation. When the linked order is later cancelled or soft-deleted, `OrderManager` reverts the quotation back to `status = 2` (Accepted).

### Sales Orders (`td_order`)

| Status | Meaning |
|---|---|
| `-2` | Pending warehouse selection or source completion |
| `-1` | Cancelled |
| `0` | Draft |
| `1` | Confirmed |

Confirmation can create stock-out rows. Cancellation reverses stock-out rows where required and is blocked when active invoices or returns exist.

### Purchase Orders (`td_purchase_order`)

| Status | Meaning |
|---|---|
| `-2` | Pending warehouse selection or source completion |
| `-1` | Cancelled |
| `0` | Draft |
| `1` | Confirmed |

`td_purchase_order.status` only ever holds the values above. **Partially received** and **fully received** are not stored statuses — they are derived on the fly by `PurchaseOrderManager::deriveReceiptStatus()` into a virtual `receipt_status` field returned alongside the PO row. This derived value reflects the ratio of approved stock-in rows to ordered quantities and is never written back to `td_purchase_order.status`.

Receiving creates stock-in rows. Close and cancel rules apply based on receiving progress and approved stock-in rows.

### Purchase Requests (`td_purchase_request`)

| Status | Meaning |
|---|---|
| `-1` | Cancelled |
| `0` | Draft |
| `1` | Submitted |
| `2` | Approved / reopened after conversion rollback |
| `3` | Rejected |
| `5` | Converted |

Converted requests have a linked purchase order.

### Returns and Supplier Returns (`td_return`, `td_supplier_return`)

| Status | Meaning |
|---|---|
| `-1` | Cancelled |
| `0` | Draft |
| `1` | Confirmed |

Confirmation creates stock-in (sales return) or stock-out (supplier return) rows. Conversion creates a credit note or supplier credit note document via `InvoiceManager`.

### Stock Entries (`td_stock_<warehouse_id>`)

Draft stock entries await approval. Approved entries update warehouse balances. Approved entries cannot be deleted without reversal; editing and deletion are also blocked outside the posting window.

## Void And Soft Delete Strategy

The current strategy (as of 2026-05-19):

- **Draft or unposted documents** may be soft-deleted or cancelled freely.
- **Posted or issued documents** use a void workflow. The source document is preserved in audit history. Void removes the linked GL entry through `GlManager::delete()` and enforces the posting window.
- **Master data** is soft-deleted by setting `status = 0`. Deletion is blocked when active documents reference the record.

Void convention uses `status = 4` for `td_invoice` document types (covers `invoice`, `credit_note`, `purchase_invoice`, `supplier_credit_note`). Credit notes are considered inactive at `status = 4`, not `status = -1`.

### Soft-delete tombstone mechanism

Draft transaction documents (invoices, receipts, payments, billing notes, orders, quotations, returns, etc.) are soft-deleted by **negating `company_id`** on the header row and all child item rows:

```sql
UPDATE td_invoice      SET company_id = company_id * -1 WHERE id = :id AND company_id = :cid
UPDATE td_invoice_item SET company_id = company_id * -1 WHERE invoice_id = :id AND company_id = :cid
```

This is the tombstone convention used by every `softDelete()` method across all managers. Because every read query filters `WHERE company_id = :cid` (positive), tombstoned rows are automatically excluded without any additional flag. Any query that omits the `company_id` filter will expose tombstoned rows — treat this filter as mandatory.

`deleted_at`, `deleted_by`, and `delete_reason` audit columns are not yet implemented.

## GL Versioning

When a source document is posted to the GL more than once (re-post after edit), `GlManager::replace()` is called instead of `GlManager::post()`. The replace path:

1. Reads the current `td_gl` and `td_gl_item` rows.
2. Appends a snapshot of the current lines as JSON into the `td_gl.history` column.
3. Increments `td_gl.current_version`.
4. Writes the new lines into `td_gl_item`.

This means the full posting history for a document is preserved in `td_gl.history` as a versioned JSON array. `GlManager::delete()` creates a **reversal journal entry** (debits and credits swapped, lines prefixed with `VOID:`) linked to the original `source_id`, then tombstones the original `td_gl` row. No rows are physically deleted — the full audit trail is preserved in the database.

Manual journal entries use `GlManager::postManual()` and `GlManager::replaceManual()` which follow the same versioning pattern.