z77 / module-order
Z77 Order Module | sales orders (quote and order as one record), statuses as data on five fixed phases with a change log, quote / order confirmation / delivery note as PDF and e-mail, the stock call per write, invoicing through module-debtor (ADR-040, ADR-043, ADR-054).
Requires
- php: >=8.4
- z77/kernel: ^1.0
- z77/module-article: ^1.0
- z77/module-contact: ^1.0
- z77/module-debtor: ^1.0
- z77/module-mandator: ^1.0
- z77/module-vat: ^1.0
- z77/persistence-doctrine: ^1.0
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-20 05:01:29 UTC
README
The sales order of the z77 business modules: quote and order are one record that climbs a
fixed ladder of phases — quote, confirmed, delivered, closed — prints its own documents
(quote, order confirmation, delivery note), sends them by e-mail, and is invoiced through
z77/module-debtor. The status is data (labels the installation maintains);
all behaviour hangs on five phases fixed in code.
Developed in the z77-ch/z77-framework monorepo
(packages/module-order); not yet a split target or on Packagist — projects consume it through a
path repository until it is. MIT licence.
What it does
- One record from quote to invoice (
Entities\SalesOrder,SalesOrderLine,SalesOrderStatusChange): number from the rangeorder, customer (a contact with a debtor profile), billing and delivery address as snapshots, lines that reference an article (every priced line is an article; text lines; one level of indented child lines), a status log. - Phases and statuses (
Entities\OrderPhase,Entities\OrderStatus): five fixed phases —new«Eröffnet»,confirmed«Termin»,delivered«Geliefert»,closed«Abgeschlossen»,cancelled«Abgelegt» — carry every rule (printable, invoiceable, locked, stock target). The statuses are file master data (data/framework/order/order_statuses.json, seeded once fromorder_statuses.default.json) with a start status and one status per action (order confirmation, delivery note, invoicing, journal posting). See ADR-043 and its addenda. - One write path (
Services\OrderService): create, update with optimistic version, status change, the two prints that move the order (printConfirmation(),printDeliveryNote()), invoicing (book()→ debtor's Faktura-Journal), re-invoicing (reinvoice()), delete with a reason (kept, tab «Gelöscht»). Totals always come from debtor's invoice preview (no VAT or rounding logic in this package). - PDFs (
Pdf\OrderPdf, layoutspdf/order,pdf/deliveryNote— overridable underoverride/): quote / order confirmation, delivery note, invoice preview. - E-mail (
Mail\OrderMailson debtor'sDocumentMailer): quote, order confirmation and delivery note to the billing address's e-mail, the PDF rendered at send time (Mail\OrderPdfAttachment). Only wherez77/module-mailingis installed. - Hooks into other modules (
src/App/Config/orderConfig.inc.php): the year-close warning for orders not yet invoiced (openWorkChecks→Close\InvoiceableOrdersCheck), debtor's journal posting moves invoiced orders to «Gebucht» (invoicePostedListeners→Services\OrderInvoicePostedListener), dashboard entries (Dashboard\OrderDashboard), the document-mail kindsquote,order-confirmation,delivery-note. - The stock seam: every write calls article's
StockLedger::bringTo()once with the order's complete target state (reserved inconfirmed, consumed fromdeliveredon). The ledger behind it books nothing yet — see «Not built yet».
Requirements
PHP 8.4 and z77/kernel, z77/persistence-doctrine, z77/module-vat, z77/module-contact,
z77/module-mandator, z77/module-article, z77/module-debtor. Optional: z77/module-mailing
(«Senden ▾»), z77/module-financial (through debtor — posting the invoices).
Enabling it in a project
- Require the package (
composer require z77/module-order, or the monorepo'spathrepository).composer install/updateadds the navigation entries ofdata/framework/routing/navigation.d/module-order.json(ADR-050) and the installer seedsorder_statuses.jsononce. - Register the namespace in the project's
composer.jsonautoload.psr-4— this module plus those of its requires (vat, contact, mandator, article, debtor):"Z77\\Module\\Order\\": ["override/z77/module/order/src/"]— an unregistered package is installed but not a module, andz77-dbdoes not see its migrations (Switch the modules on). - Apply the migrations (
res/migrations, namespaceZ77\Module\Order\Migrations):php vendor/bin/z77-db migrate. - Maintain the statuses under Stammdaten › Auftragswesen › Auftragsstatus if the seed does not fit; check that a status in phase «Abgeschlossen» carries «Wird gesetzt beim Verbuchen».
- Customise the PDF layouts by copying
res/view/templates/pdf/*.tpl.phpunderoverride/(CE principle — never editvendor/).
Backend screens
Mounted by z77/module-backend (thin hosts in src/Ui/Controllers/Order/, logic in this
package's Ui\*ControllerTrait):
| Menu | URL | What |
|---|---|---|
| Auftragswesen › Aufträge | /backend/order/order/list |
the list (tabs Eröffnet · Termin · Geliefert · Fakturiert · Gebucht · Erledigt · Abgelegt · Alle · Gelöscht), «+ Neuer Auftrag», «Fakturieren …» for a selection |
| (window) | /backend/order/order/edit?id= |
the order: head, addresses, lines with the article picker, status, «Drucken ▾», «Senden ▾», «Fakturieren …», «Neu fakturieren …», «Löschen …», history and documents |
| Stammdaten › Auftragswesen › Auftragsstatus | /backend/order/order-status/list |
the status master data with its window |
The order list, the order window and both status screens carry German help
(res/view/templates/Backend/*/*.help.tpl.php, ADR-048; the confirmation dialogs need none); the
workflow guides under res/view/templates/Backend/Guide/ («Ablauf eines Auftrags», «Neuen
Kunden erfassen») feed the backend assistant (ADR-055).
Not built yet
- Stock — the journal ledger (plan step P7b) is not built:
StockLedgers::default()returnsPendingStockLedger, which books nothing and never refuses. No reservation, no stock level, no reason asked when consumed stock would come back. The help says «Lager: noch nicht verfügbar — folgt». - The quote is not archived (owner decision 2026-11-13): its PDF is always rendered from the order as it stands. To keep what was offered, a second order with the quote's content is captured by hand and parked in a status of phase «Abgelegt»; there is no copy action.
- Collective invoice (several orders, one invoice), article variants with options, orders created by a shop or an import screen, a sticky totals line in the window.
Documentation
- Topic:
docs/topics/order.md— model, rules, known issues, pending. - Decisions: ADR-040 (business module cut), ADR-043 (order status and stock movements, with its
addenda), ADR-054 (Faktura-Journal); plan
docs/03-development/p7-order-plan.md. - Harness:
tests/module-order.php(offline sections; section M needs thez77testdatabase).