WorkSheetState
: string
in package
State of a work sheet (`cms_mod_company_work_sheets.state`); a `WorkList` is a job, a `WorkSheet` is a work sheet inside it.
An open sheet accepts more work, a closed sheet is locked and waits for invoicing, an
invoiced sheet links to the invoice (invoicer_invoice_id). Only the manager changes the
state (WorkListManager::invoiceSheets(), WorkSheetManager::closeSheet(),
reopenSheet()); the entity is just a carrier.
Closing is the intermediate state of invoiceSheets(). The bulk closing builds one invoice
from several sheets of a job, and between "the invoice is saved" and "the sheets know about
it" the process can die; a repeated call would then issue a second invoice for the same work.
A conditional bulk update (WHERE state IN ('open','closed')) moves the sheets to closing
right before InvoiceManager::save(), and they leave it only after invoicer_invoice_id is
written:
open/closed to closing: guards pass and the invoice is composed but not saved yet.
closing to invoiced: save succeeded, invoicer_invoice_id and state are written.
closing to the original state: save failed and no invoice was created (revert).
A sheet stays in closing only when the process died inside those few statements. With
invoicer_invoice_id filled, a repeated call completes it idempotently (no second invoice);
closing without invoicer_invoice_id is the only state that needs a human.
IMPORTANT: a sheet may enter closing from closed as well as from open, so the revert
must restore the original state, kept in WorkSheet::$stateBeforeClosing. Reverting to a
fixed open would reopen a manually closed sheet.
NOTE: the state column is a varchar(16), not a database enum, so a new case needs no alter.
Table of Contents
Cases
Methods
- isLocked() : bool
- Returns whether the sheet is locked against changes.
- lockedStates() : array<int, self>
- Returns the states in which the sheet and its work items are read-only; the guards in `WorkSheetManager` and `WorkItemManager` reject both `save()` and `updateColumns()`.
Cases
Open
Closing
Closed
Invoiced
Methods
isLocked()
Returns whether the sheet is locked against changes.
public
isLocked() : bool
Return values
boollockedStates()
Returns the states in which the sheet and its work items are read-only; the guards in `WorkSheetManager` and `WorkItemManager` reject both `save()` and `updateColumns()`.
public
static lockedStates() : array<int, self>
Closing is included on purpose: work added during a running closing would be missing
from the invoice yet sit in the sheet as invoiced.