Skip to content

feat: plan 030 — custom workflow catalog: 6 triggers, new condition fields and groups, 4 actions - #37

Merged
jack9x merged 27 commits into
developfrom
jack/feature/030-catalog
Nov 9, 2026
Merged

jack9x merged 27 commits into
developfrom
jack/feature/030-catalog

Conversation

@jack9x

@jack9x jack9x commented Nov 9, 2026

Copy link
Copy Markdown
Collaborator

Summary

Shop owners can now build their own workflows from New Workflow, not only start from a template. This PR adds:

  • 6 triggers: Order paid, Order refunded, Order note added, Customer order count reaches, Customer total spend reaches, Review posted.
  • About 25 condition fields, with list, relative-date ("in the last N days"), "is set" and custom-field comparisons, plus one level of condition groups.
  • 4 actions: Update customer custom field, Change customer role, Resend WooCommerce email, Wait until.
  • A fix to Update order custom field.

Every write action is guarded at run time, because runs execute as user 0.

Base: develop f747ff8. No schema change: the claims table keeps its column, and guest claim keys are hashed to fit it. One commit per checkpoint, plus fix: commits from review. Built in three runs: CP0–CP6, CP7–CP10, CP11–CP16.

Checkpoints

  • CP0 Docs frame (ff2aff2): CT section in ROADMAP-dev, decisions "CT", design pointers. M6 marked done.
  • CP1 Hardening (e9aa3e0)
    • MetaKeys::order_blocked(): Update order custom field refuses WooCommerce's internal keys, wp_* keys and _yaymatik_* keys, at save and at run time.
    • The step's outputs are key + changed. Old → new goes in a private order note.
    • Active-trigger cache: the autoloaded option yaymatik_active_triggers, rewritten under a lock after each activate, deactivate, apply or delete. The Dispatcher listens only to triggers in it.
    • Action::emits() and the may_refire warning, which never blocks Activate.
  • CP2 Types and comparisons (5d12372): list and meta types; matches_any/all/none, is_any_of, in_last / not_in_last (hours, days), is_set / is_not_set.
  • CP3 Fields and stats (50263b7): new order and customer fields, plus order.meta / customer.meta. CustomerStats counts paid statuses only, takes refunds off, and works on both order stores. customer.paid_order_count keeps its key.
  • CP4 Search (b6351cf, fixes 4541dc7, d8f2391): paged REST search for products, categories and coupons; SearchSelect.
  • CP5 Condition form (7f0c99c): a control for each rule kind; customer field names suggested from other workflows.
  • CP6 Groups (a49db82, fix 6025f7e): { match, rules } one level deep. Old configs come out byte-identical. An empty group gets its own message.
  • CP7 Order paid, Order note added (8a8e68f): an order saved already paid is caught around its first save and never starts Order paid. Notes added by a run are skipped by default.
  • CP8 Order refunded (95c47ac): one run per refund; refund data (amount, reason, is_full, stateless).
  • CP9 Milestones (d04cb7a): fire only when this order crosses the threshold.
    • Trigger::claim_key(): the key is user:<id>, or for a guest email: + sha256 of the email.
    • Export lists these claims; erase deletes them.
  • CP10 Review posted (7b0f579, fix 641927b): approved, top-level product reviews only. A guest reviewer is their email only. New Reviews picker section.
  • CP11 Update customer custom field (3fa3e41)
    • MetaKeys::user_collides(): before writing, the step reads the rows the write could reach under the column's collation.
    • New field modifier suggest draws a <datalist>.
  • CP12 Change customer role (dabffe2): add, remove or replace. assignable_roles() leaves out staff roles and roles with a protected capability.
    • At run time it skips super admins, staff, and anyone user_can() grants a protected capability.
    • It never removes a customer's last role.
    • Filter yaymatik_change_role_allow_all lifts the protections, except the last-role rule.
  • CP13 Resend WooCommerce email (5796f31): 7 core customer emails, filter yaymatik_resendable_emails. Skipped when the email is off or the order has no billing email.
  • CP14 Wait until (dc00f64): next_time() steps by calendar day in wp_timezone(), so DST is safe. Its time input came later, below. StepResult::wait() takes outputs, so later steps can read until.
  • CP15 Stop waiting runs (b0f34a3): PersonSubjects::for_email() is moved out of PersonalData, which now uses it too. The action itself is dropped below.
  • CP16 End to end and docs (9a42e75): check-catalog-e2e.php runs one custom workflow per new trigger (group condition → customer email) and one run through all the new actions. Docs read-through; decisions CT gets its Cost block.
  • Drop Stop waiting runs (7efc400): the action leaves v1.0 for the v1.1 backlog, with Cancellation::for_subjects(), WorkflowStore::names() and the power icon. PersonSubjects stays for the personal data tools; RunStore::waiting_ids_for_subjects() stays for cart cancels, without its workflow filter.
  • Wait until takes any minute (d1621c0, ad92485, 69d47c0): time ('HH:MM', 00:00–23:59) replaces hour. PHP keeps it as a text field with a help line; the step's own form draws it as a native time input (step 60) in a 160px kit InputGroup whose Clock button opens the browser's picker (showPicker(), the native icon hidden), next to the Days list. The store-time hint has a Clock icon and reads only "Store time (zone)." while the time is blank. The card and the hint show it in the site's time format (gmdateI18n). WaitUntil::validate() and the TS schema check the format with one message, "Enter a time, e.g. 9:15 am." next_time() takes hour and minute; tests for odd minutes, in a DST gap, in the repeated hour and past today's time. No migration: a stored hour config reads as a setup issue in PHP and on the card (checked in check-catalog).

Worth a closer look

  • Run-time guards for user-0 writes: MetaKeys::user_collides() (per user, no DISTINCT, a failed read refuses), ChangeCustomerRole::user_protected() / role_protected(), and UpdateCustomerMeta, which slashes its key and value so the stored key is the one checked.
  • The active-trigger cache race (WorkflowStore::refresh_active_triggers()): readers store with INSERT IGNORE, and writers rewrite under one lock. check-catalog simulates two interleaved writers from a second process.
  • Order paid on an order saved already paid (OrderPaidTrigger). WooCommerce fires woocommerce_new_order for drafts too, so the order is caught around its first save, not at that hook.
  • Milestone claims hash a guest's email. The Worker releases the claim through scope.trigger.claim_key.
  • Runs keep refs only. Step results are ids, keys, fixed labels or booleans: role names, an email's id, a count, a store-time date. "Sent Completed order" never names the address.
  • PROTECTED_CAPS allows customer rights only. On top of D8's staff and site capabilities: edit_posts, publish_posts, edit_others_posts, edit_pages, upload_files, moderate_comments, edit_products, edit_shop_coupons, manage_product_terms, view_woocommerce_reports, import, export. Triggers fire on public events, so any buyer would get the role, and customer roles only need read. Author, Editor and Contributor aren't assignable.
  • Known limits are under Cost in docs/workflow-core-decisions.md, section CT.

Before merging

  • Browser checks: runs 1 and 2 passed (Jack, Nov 5 and Nov 8). Run 3's (the new actions, the Wait until time input in light, dark and a narrow panel) are pending.
  • Dev site only: 35 product categories named chk… Men &amp; Boys, left by earlier aborted check-catalog runs, can be deleted.

Team after pulling develop

  • composer dump-autoload, then load wp-admin. No DB change.
  • Dev sites made before plan 022 must rebuild trigger_claims: wp db query "DROP TABLE IF EXISTS $(wp db prefix)yaymatik_trigger_claims", wp option delete yaymatik_db_version, then load wp-admin.

How to test

  • ./run.sh check-catalog checks HPOS and the posts store, the second through its own process. It stops if the site has an active workflow on these triggers, so deactivate those first.
  • Also check-winback, check-lifecycle, check-carts, check-runs, check-orders, check-storage, check-late-module, and check-status-flow <two order ids>.
  • Editor:
    • Build a condition with each rule kind and a group. Search, reload: the labels stay.
    • Order status changed + Change order status shows the amber may-refire line.
  • Triggers:
    • Order paid: a pending checkout marked processing gives one run; completed after that gives none.
    • Refunds: a partial refund, then the rest, give two runs, Full refund No then Yes.
    • Review posted: a review held for moderation gives no run until it is approved.
  • Actions:
    • Update customer custom field: wp_capabilities shows an issue.
    • Change customer role: the list has customer roles only (no Administrator, Shop manager, Editor, Author or Contributor); on a shop manager the step is skipped.
    • Resend Completed order: the email arrives.
    • Wait until: Time is a 160px time input (any minute) with a Clock button that opens the picker and the help line about scheduled tasks under it; typing still works; a new step starts at 9:00 am; type 11:10 and the card reads "Until 11:10 am · Mon–Fri" (with 24-hour site time, "Until 11:10"); the hint under the form has a clock icon and shows the store time zone; cleared, it reads only "Store time (…)." The clock button shows in dark mode.

jack9x added 27 commits November 4, 2026 15:49
…earch lists under their fields, rule issues under their rule
@jack9x
jack9x merged commit 8b5c7f5 into develop Nov 9, 2026
1 check passed
@jack9x
jack9x deleted the jack/feature/030-catalog branch November 17, 2026 02:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant