| 1 |
# WCPOS Free Plugin |
| 2 |
|
| 3 |
Domain language for the `woocommerce-pos` WordPress plugin — the server-side foundation for WCPOS. Terms here are binding for code, docs, and reviews; architecture reviews and grilling sessions update this file as concepts crystallize. |
| 4 |
|
| 5 |
## Language |
| 6 |
|
| 7 |
### Settings |
| 8 |
|
| 9 |
**Settings**: |
| 10 |
User-configurable intent stored in `woocommerce_pos_settings_*` options and read through the Settings module. Distinct from Plugin State. |
| 11 |
_Avoid_: options, config, preferences |
| 12 |
|
| 13 |
**Settings Section**: |
| 14 |
The unit that owns one settings group end to end: schema, defaults, sanitization, secret redaction, merge strategy, and (when not option-backed) custom read/write behaviour. Nine exist: general, checkout, tax_ids, payment_gateways, tools, visibility, cloud_print, access (role-backed), license (Pro-injected). Classes are named `{Id}_Section`. |
| 15 |
_Avoid_: settings group, settings schema, settings tab |
| 16 |
|
| 17 |
**Section Registry**: |
| 18 |
The seam where Settings Sections are registered. The free plugin registers its nine; Pro and extensions register theirs through it instead of hooking ad-hoc filters. |
| 19 |
_Avoid_: section manager, settings factory |
| 20 |
|
| 21 |
**Plugin State**: |
| 22 |
Machine bookkeeping stored in options but not user intent: site UUID, JWT secret keys, install timestamp, DB version. Owned by the module that uses it (e.g. Auth owns its secret keys), never by the Settings module. |
| 23 |
_Avoid_: settings (for these), internal options |
| 24 |
|
| 25 |
### Receipts |
| 26 |
|
| 27 |
**Receipt Data**: |
| 28 |
The JSON payload a receipt template renders from: `order`, `store`, `cashier`, `customer`, `lines`, `fees`, `shipping`, `discounts`, `totals`, `tax`, `tax_summary`, `payments`, `refunds`, `fiscal`, `presentation_hints`. Built by a source (a live WooCommerce order, or the sample the template editor and gallery use), filtered through `woocommerce_pos_receipt_data`, then rendered identically on the server and offline in the app. Logic-less by ADR 0039: templates branch on data the payload carries. |
| 29 |
_Avoid_: receipt JSON, receipt context, template data |
| 30 |
|
| 31 |
**Receipt Section**: |
| 32 |
One named block of Receipt Data and the shape of its rows. Money keys come in triples (`total`, `total_incl`, `total_excl`) with the bare key filled from the store's tax display basis. Row shapes and the aggregate rules of `totals` (subtotals, item counts, net total after refunds, savings completeness) are declared once in the Receipt Sections module; a source supplies priced values, it never declares keys. |
| 33 |
_Avoid_: receipt block, payload part, builder output |
| 34 |
|
| 35 |
### Sync |
| 36 |
|
| 37 |
**Collection Rule**: |
| 38 |
One POS query behaviour for one collection — the params it claims, the clauses it contributes, the storage it targets — declared once in the Collection Rules module and applied identically on every read lane, so it cannot be wired into only one. |
| 39 |
_Avoid_: query filter, orderby mapping, proxy mirror |
| 40 |
|
| 41 |
**Read Lane**: |
| 42 |
One of the two paths a collection read reaches the client by — the direct lane (`wcpos/v1` controllers, plus the flat `wcpos/v2` routes with no `wc/v3` proxy backing, e.g. `/variations`) and the proxy lane (`wcpos/v2` → `wc/v3`). Behaviour that exists on one lane only is a parity bug, not a design. (Code comments also say "lane" for the request shapes *within* one route — include lane, discovery lane; that narrower sense is not this term.) |
| 43 |
_Avoid_: v1/v2 API, endpoint version |
| 44 |
|
| 45 |
**Write Payload shape**: |
| 46 |
The one pass an order document takes through the Order Write Payload module before WooCommerce sees it, named by what an absent line means. The _full-document_ shape (`for_update`, the `wcpos/v2` push lane) treats the document as the whole order: an omitted stored line is deleted and coupon lines are reconciled. The _partial-document_ shape (`for_partial_update`, the `wcpos/v1` lane) keeps WooCommerce's own semantics: an absent line is untouched and coupon lines pass through to the controller. Both shapes share every other rule; a rule that exists in one shape only is a ruling (recorded on the module), not a drift. |
| 47 |
_Avoid_: v1 sanitizer, v2 forward rules, payload filter |
| 48 |
|
| 49 |
**Create Identity**: |
| 50 |
The proof that a record born on the `wcpos/v2` push lane owns its client UUID before the mutation is finalized: poison checkpoint, UUID persisted, resolved back to the same id, checkpoint finalized. Written once in the Create Identity module; a retry against a `poison` checkpoint re-enters the same proof rather than running a second copy. ADR 0038 decides when identity is re-proved; this module decides where the proof lives. |
| 51 |
_Avoid_: poison retry, identity stamp, recovery path |
| 52 |
|
| 53 |
**Promoted Service**: |
| 54 |
A shared POS service (auth, settings, cashier, receipts, print jobs, stores, extensions, logs, gateways, checkout, templates, shipping methods, tax classes, order statuses) that answers identically under `wcpos/v1` and `wcpos/v2`. The Controller Registry derives the v2 map from the v1 map, so promotion is the default and only the nine frozen data controllers (the sync surface replaced them, #544) are excluded. |
| 55 |
_Avoid_: v2 twin, pass-through subclass, v2 controllers map |
| 56 |
|
| 57 |
**Replica policy**: |
| 58 |
What a collection's client-side copy aims to hold: `complete` (a full replica, e.g. products, |
| 59 |
variations) or `windowed` (a bounded recent window of an unbounded set, e.g. orders). |
| 60 |
_Avoid_: cache mode, sync mode |
| 61 |
|
| 62 |
**Trickle**: |
| 63 |
Low-priority idle seeding that pages a complete-replica collection down to the client until |
| 64 |
it holds everything. |
| 65 |
_Avoid_: background sync, prefetch |
| 66 |
|
| 67 |
**Pointer stream**: |
| 68 |
The journal-backed change signal (`/changes/sequence-log`): tiny id-pointers the client |
| 69 |
filters and hydrates through the collection's read lane (the wc/v3 proxy — or the flat |
| 70 |
route where the registry has no proxy lane, e.g. variations). The engine's single |
| 71 |
transport paradigm. |
| 72 |
_Avoid_: change feed, event stream |
| 73 |
|
| 74 |
**Canonical revision**: |
| 75 |
THE content fingerprint of a record — a sha256 over its schema-scoped, canonicalized wc/v3 |
| 76 |
serialization, computed at read time, never stored. The `baseRevision` a client echoes for |
| 77 |
optimistic concurrency. |
| 78 |
_Avoid_: version, hash (unqualified), rev |
| 79 |
|
