Implementation Plan — Auto "Done Print" on bulk "Change status to Completed"

File: docs/order-done-plan-01.md Target version: 1.5.1 Status: Draft / not yet implemented Supersedes: docs/order-done-plan-00.md (kept for history)

0. Changes from plan-00 (review folded in)

This revision incorporates the findings from the code-review of plan-00. Summary of what changed:

Per-order failure isolation — each order is processed inside try/catch so one bad order can no longer fatal the request and strand the whole batch (was: an uncaught throwable in the loop aborts everything, including WooCommerce's own completion pass).
Terminal / already-completed skip — the advance loop now skips any order already in Studiou_DB_Manager::TERMINAL_STATUSES (completed/cancelled/refunded/failed). This fixes the silent mutation of already-completed orders (whose items lazily default to pending-print) and resolves the terminal-order question (Q2) toward the plugin's established skip-terminal philosophy. See §6 for the precise resulting behaviour, including one honest residual edge case.
Stronger hook-ordering / outcome test — test §9 #8 now asserts the end state (order completed, no "completion blocked" notice) rather than only log-line ordering, so a future WooCommerce regression in the load-bearing assumption is actually caught.
Two-instance/cache dependency documented — §5 now states explicitly that the advance and the guard run on two different wc_get_order() instances and why that is expected to be coherent (and what would break it).
i18n corrected — the sketch carries /* translators */ comments on every new string, and §8 states the real new-string count.
Double order hydration acknowledged — §6 notes the two wc_get_order() loads per order across the two callbacks.

1. Goal

On the HPOS Orders list (wp-admin/admin.php?page=wc-orders), when the operator runs the built-in WooCommerce bulk action "Change status to Completed" (mark_completed, Czech "Změnit stav na Dokončeno"), the plugin must — before the order status is flipped — advance every still-unresolved product line-item print status to Done Print (done-print) for orders that are actually about to transition.

"Unresolved / unset" means any product item currently in pending-print or in-print. Items already in done-print or skip-print are left alone. This is exactly the semantics of the existing Order_Item_Status_Manager::advance_remaining_to_done() — we reuse it, we do not reimplement it.

Hard scope constraint

This auto-advance is proprietary to this one entry point only:

the mark_completed bulk action, and
the woocommerce_page_wc-orders (HPOS) screen.

It must not fire for:

single-order completion from the order-edit status dropdown,
programmatic / REST / cron status changes,
the InPrint or Delivered protocol imports (the Delivered import already does its own advance),
any other bulk action (Prepare to Printing, In Printing, export, trash, etc.),
the legacy CPT orders screen (edit-shop_order) — out of scope; operator uses HPOS.

Everywhere else, the existing completion guard behaviour is preserved: completing an order while items are still pending/in-print is blocked and reverted with an admin notice.

2. Why this is needed (current behaviour)

Today the only coupling on → wc-completed is the completion guard in Order_Item_Status_Manager::on_order_status_changed() (hooked to woocommerce_order_status_changed, priority 5). It does the opposite of what we want here: if any product item is still pending-print/in-print it reverts the order back to its previous status and shows an error notice.

So a bulk "mark completed" over orders whose items are still pending currently fails for those orders — WooCommerce sets them to completed, our guard immediately reverts them, and the operator sees N "completion blocked" notices. The operator's intent in this specific bulk action is the reverse: "I'm done — mark the items done and complete the orders."

The fix is to advance the items before the status change reaches the guard, so the guard sees a ready order and lets the completion stand.

3. How WooCommerce dispatches the bulk action

WooCommerce routes all orders-list bulk actions — including the core mark_* ones — through the WordPress filter:

handle_bulk_actions-woocommerce_page_wc-orders   ( $redirect_to, $action, $ids )

The plugin already proves this: Bulk_Actions_Manager registers its custom actions on this exact filter at priority 10 and they work. WooCommerce core's own handler for mark_* (which loops the selected IDs and calls $order->update_status( 'completed', ... )) is — on the WooCommerce versions in scope — another callback on the same filter, registered at priority 10.

Key lever: a callback registered on the same filter at a lower priority number runs first. So a callback at priority 9 runs before WooCommerce changes any status — the exact window we need to advance items.

(Priority is what orders callbacks, not registration time. Our managers register at plugins_loaded 10; WC registers its list-table handler later in the request during screen setup. Using priority 9 guarantees we still run first regardless of registration order.)

Load-bearing assumption. The whole feature depends on WC core's mark_completed handler being a priority-10 filter callback that priority 9 pre-empts. If a future WC version processes mark_* inline (before applying the filter) the priority-9 window disappears. This is why §9 #8 asserts the actual outcome on the installed WC, and why §7 documents a fallback.

4. Chosen approach (Approach A — pre-flip in the bulk filter)

Add one new callback on handle_bulk_actions-woocommerce_page_wc-orders at priority 9 that:

returns $redirect_to untouched unless $action === 'mark_completed';
bails (returns $redirect_to untouched) if the user lacks edit_shop_orders — let WC's own handler reject the request; we never mutate without the cap;
sanitises the ID list (array_filter(array_map('intval', (array) $ids)));
for each ID, inside a try/catch: wc_get_order($id), skip falsy, skip any order already in a terminal status (see §6), then call advance_remaining_to_done($order) (reused as-is);
adds a per-order summary order note when count > 0 ("N line items advanced to Done Print before bulk completion.");
accumulates totals and emits one UtilsLog::message(..., 'success') summary across the batch (e.g. "Auto-advanced 12 items to Done Print across 4 orders before completion."); if any order threw, emits one warning summarising the failure count;
returns $redirect_to unchanged — it does not short-circuit. WooCommerce's priority-10 handler then runs the actual status change, and because every item on the advanced orders is now done-print/skip-print, the completion guard at priority 5 sees a ready order and lets it through silently.

No change is needed to the completion guard itself. The guard stays as the safety net for every other path — and, by design (§6), for the terminal orders we deliberately do not advance.

Where the code lives — recommendation

Put the new hook + handler in Order_Item_Status_Manager (not Bulk_Actions_Manager):

It already owns advance_remaining_to_done(), set_status(), get_status(), the completion guard, and the recursion-guard flag — all the moving parts of this feature are in one class, so the author reasons about the guard/advance interaction in one place.
It already hooks WooCommerce actions in its constructor, so adding one add_filter(...) line there is idiomatic.
It avoids wiring a new cross-manager dependency. (It does reference Studiou_DB_Manager::TERMINAL_STATUSES — a constant on an always-loaded class — which is acceptable: Studiou_DB_Manager itself already does new Order_Item_Status_Manager(), so the two classes are already mutually aware.)

Constructor addition:

add_filter(
    'handle_bulk_actions-woocommerce_page_wc-orders',
    array($this, 'bulk_complete_advance_items'),
    9,   // before WooCommerce's own mark_completed handler (priority 10)
    3
);

New method (sketch — final code to match house style):

/**
 * Proprietary behaviour for the HPOS Orders list "Change status to Completed"
 * bulk action ONLY: advance every still-pending/in-print product item to
 * done-print BEFORE WooCommerce flips the order, so the completion guard is
 * satisfied instead of reverting. Runs at priority 9 (before WC's priority-10
 * mark_completed handler). Returns the redirect unchanged so WC still performs
 * the status change.
 *
 * Orders already in a terminal status (completed/cancelled/refunded/failed) are
 * deliberately NOT advanced — see the class-level coupling notes and
 * docs/order-done-plan-01.md §6:
 *   - already-completed: WC's flip is a no-op, so advancing would silently
 *     mutate items (and add a misleading note) with no transition;
 *   - cancelled/refunded/failed with unresolved items: leaving them unadvanced
 *     lets the existing completion guard revert WC's flip, protecting them from
 *     being completed by an over-broad selection — matching the protocol-import
 *     skip-terminal philosophy.
 *
 * Each order is processed inside try/catch: a single failing order must not
 * abort the whole batch (which would also stop WC's priority-10 handler from
 * completing ANY order and leave earlier orders with advanced-but-uncompleted
 * items).
 */
public function bulk_complete_advance_items($redirect_to, $action, $ids) {
    if ($action !== 'mark_completed') {
        return $redirect_to;
    }
    if (!current_user_can('edit_shop_orders')) {
        return $redirect_to; // WC's handler enforces caps; we don't mutate without it.
    }
    $ids = array_filter(array_map('intval', (array) $ids));
    if (empty($ids)) {
        return $redirect_to;
    }

    $total_items  = 0;
    $total_orders = 0;
    $failures     = 0;

    foreach ($ids as $id) {
        try {
            $order = wc_get_order($id);
            if (!$order) {
                continue;
            }
            // Do not touch terminal/already-completed orders (see docblock).
            if ($order->has_status(Studiou_DB_Manager::TERMINAL_STATUSES)) {
                continue;
            }

            $advanced = $this->advance_remaining_to_done($order);
            if ($advanced > 0) {
                $order->add_order_note(sprintf(
                    /* translators: %d is the number of line items advanced. */
                    _n(
                        '%d line item advanced to "Done Print" before bulk completion.',
                        '%d line items advanced to "Done Print" before bulk completion.',
                        $advanced,
                        'studiou-wc-ord-print-statuses'
                    ),
                    $advanced
                ));
                $total_items += $advanced;
                $total_orders++;
            }
        } catch (\Throwable $e) {
            $failures++;
            UtilsLog::log(sprintf(
                'bulk_complete_advance_items: order #%d failed to pre-advance: %s',
                $id,
                $e->getMessage()
            ));
        }
    }

    if ($total_items > 0) {
        UtilsLog::message(
            sprintf(
                /* translators: 1: item count, 2: order count */
                __('Auto-advanced %1$d line item(s) to "Done Print" across %2$d order(s) before completion.', 'studiou-wc-ord-print-statuses'),
                $total_items,
                $total_orders
            ),
            'success'
        );
        UtilsLog::log(sprintf('bulk mark_completed: advanced %d items across %d orders', $total_items, $total_orders));
    }
    if ($failures > 0) {
        UtilsLog::message(
            sprintf(
                /* translators: %d is the number of orders that errored during pre-advance. */
                _n(
                    '%d order could not be pre-advanced and may not complete — check the debug log.',
                    '%d orders could not be pre-advanced and may not complete — check the debug log.',
                    $failures,
                    'studiou-wc-ord-print-statuses'
                ),
                $failures
            ),
            'warning'
        );
    }

    return $redirect_to;
}

(\Throwable is available on PHP 7.2+, the plugin's minimum.)

Alternative placement (if preferred)

If the team would rather keep all bulk-action hooks in Bulk_Actions_Manager, the identical logic can live there instead, with the Order_Item_Status_Manager instance injected via the constructor. The main plugin (initialize_managers()) currently builds Bulk_Actions_Manager (line ~89) before Order_Item_Status_Manager (line ~92), so this would also require reordering those two instantiations and passing the item-status manager into new Bulk_Actions_Manager($itemStatus). Functionally equivalent; more wiring. Recommendation stays with Order_Item_Status_Manager.

5. Interaction with the existing completion guard

Confirm during implementation:

The guard runs at woocommerce_order_status_changed priority 5; it fires after WC's bulk handler calls update_status('completed'), i.e. after our priority-9 pre-advance.
Sequence for one non-terminal order in the bulk action:
1. our priority-9 filter advances items → done-print and saves each one ($item->save());
2. WC's priority-10 filter calls $order->update_status('completed');
3. that fires woocommerce_order_status_changed → guard (priority 5) → is_order_ready_for_completion() now returns ready → guard returns without reverting.
The $inside_self_revert recursion flag is not involved (no revert happens), so no conflict.

Two `WC_Order` instances — coherency note (review finding)

Unlike the Delivered-import path — which advances items and completes on the same $order object — Approach A inherently involves two different wc_get_order($id) instances: ours at priority 9 (which advances + saves the item meta) and WooCommerce's own at priority 10 (which calls update_status and whose object the guard inspects).

This is expected to be coherent because WC_Order_Item::save() writes _print_status to woocommerce_order_itemmeta and invalidates that item's meta entry in the WP object cache, so WC's fresh load at priority 10 reads the just-saved done-print value. The risk to watch: a persistent object cache / order cache layer that returns a stale item-meta view to the second instance would make the guard still see pending-print and revert — re-producing exactly the "completion blocked" notices this feature removes. The §9 #8 test asserts the real outcome precisely to exercise this on the live stack rather than trusting the invalidation in theory.

(If a future change ever makes this unreliable, the simplest hardening is to advance and complete in a single pass ourselves — but that is the §7 fallback's territory, not Approach A.)

6. Edge cases & decisions

Terminal-status orders selected (completed / cancelled / refunded / failed): We skip the advance for any order already in Studiou_DB_Manager::TERMINAL_STATUSES. Resulting behaviour:
- already completed (incl. legacy orders created before 1.5.0, whose items lazily default to pending-print): we do not advance them. WC's update_status('completed') is a no-op (no transition), so nothing else happens either. This fixes the silent item-mutation + misleading note that an unconditional advance would cause on non-transitioning orders.
- cancelled/refunded/failed with unresolved items: we do not advance them; WC core still calls update_status('completed'), but the existing completion guard then reverts the order to its prior status and shows its standard "completion blocked" notice. Net effect: the order stays terminal — protected from being completed by an over-broad selection, consistent with how the protocol imports skip TERMINAL_STATUSES.
- Honest residual edge: a cancelled/refunded/failed order whose product items are already all done-print/skip-print will pass the guard and will be completed by WC core. The guard only blocks on unresolved items, never on the order's terminal status, and Approach A cannot remove IDs from WC's own pass. This matches existing 1.5.0 guard behaviour (it is not a regression introduced here) but is documented so nobody is surprised. If full terminal protection is required, it needs the §7 fallback or an ID-filtering approach, not Approach A. Tracked as Q2.
Empty selection: handled (returns early).
Per-order failure isolation: each order's processing is wrapped in try/catch. A single order that throws (e.g. a DB error during $item->save()) is logged and counted as a failure; the loop continues so the rest of the batch is still pre-advanced and WC's priority-10 pass still runs. Without this, an uncaught throwable would propagate out of the filter, fatal the request, leave already-processed orders with advanced-but-uncompleted items, and complete nothing.
Capability: mirror existing pattern (edit_shop_orders); bail without mutating if absent rather than wp_die() — WC's handler already enforces caps and we don't want to change the failure UX of the core action.
Non-product items (shipping/fee/coupon): advance_remaining_to_done() already skips anything that isn't a WC_Order_Item_Product. No change.
Performance: two cost notes, both acceptable and not optimised now:
1. advance_remaining_to_done() saves each changed item individually ($item->save()), consistent with the existing import path — N item-saves for N pending items.
2. Each selected order is hydrated twice per request: once by our priority-9 callback and once by WC's priority-10 callback. For very large selections this doubles order-object hydration. Acceptable; flagged for awareness.
Idempotency: re-running the bulk action over the same (non-terminal) orders is safe (already-done items are skipped, count 0, no note).

7. Fallback approach (only if Approach A proves unreliable)

If a future WooCommerce version stops routing mark_completed through handle_bulk_actions-woocommerce_page_wc-orders, or our priority-9 callback cannot be made to run first, or the two-instance cache coherency in §5 proves unreliable, fall back to context-aware guard relaxation:

In on_order_status_changed(), when $to === 'completed', detect the bulk-complete request context — is_admin() and the request carries the wc-orders bulk action, e.g. ($_REQUEST['page'] ?? '') === 'wc-orders' and the resolved bulk action ($_REQUEST['action'] / action2) is mark_completed.
In that context only, instead of reverting, call advance_remaining_to_done($order) and allow completion. Because this path runs inside the guard on the same $order object WC is completing, it also sidesteps the two-instance concern in §5.
Everywhere else, keep the current block-and-revert.

This is more coupled (inspects superglobals inside a domain listener) and is documented here only as a contingency. Verify Approach A on staging first (see §9); prefer it.

8. Files to change

includes/class-order-item-status-manager.php
- add the add_filter('handle_bulk_actions-woocommerce_page_wc-orders', ..., 9, 3) in the constructor;
- add bulk_complete_advance_items() method (with the terminal-skip guard and per-order try/catch).
studiou-wc-ord-print-statuses.php
- bump Version: header and STUDIOU_WC_OPS_VERSION → 1.5.1.
README.md
- extend §6 "Per-order-item print status" coupling notes with the new bulk-complete-on-wc-orders behaviour (be explicit that it is screen- and action-scoped, does NOT change single-order or programmatic completion, and skips terminal/completed orders per §6 of this plan);
- add a ## 1.5.1 changelog entry.
CLAUDE.md
- add a "Version 1.5.1" entry under Recent Changes;
- extend the Order_Item_Status_Manager architecture bullet with the new bulk-complete pre-advance hook (priority 9 on handle_bulk_actions-woocommerce_page_wc-orders, scoped to mark_completed, terminal-skipping, per-order try/catch);
- add a one-line pointer to this plan in the Documentation list: - [docs/order-done-plan-01.md](docs/order-done-plan-01.md) — Plan for auto "Done Print" on the HPOS bulk "Change status to Completed" action (1.5.1).
(No JS/CSS change → no asset cache-bust concern. Version bump still required by repo release convention.)

New translatable strings (correcting plan-00's undercount — three new source formats, two of them singular/plural pairs):

per-order note — _n('%d line item advanced to "Done Print" before bulk completion.', …);
batch success notice — __('Auto-advanced %1$d line item(s) to "Done Print" across %2$d order(s) before completion.', …);
failure warning notice — _n('%d order could not be pre-advanced and may not complete — check the debug log.', …).

Add their English sources and refresh cs_CZ (docs/translations.txt, languages/*.po/*.mo) per the existing process. Each _n()/__() call carries a /* translators */ comment in the sketch — keep them in the final code (matches the existing _n() at on_order_status_changed()).

9. Test plan

Manual, on staging with HPOS enabled and WP_DEBUG/WP_DEBUG_LOG on:

Happy path: create an order with several product items in mixed statuses (pending-print, in-print, one skip-print). On wp-admin/admin.php?page=wc-orders, select it, run Change status to Completed. Expect: order becomes completed; the pending/in items are now done-print; the skip-print item is untouched; one order note "N line items advanced to Done Print before bulk completion."; one success admin notice; no "completion blocked" notice.
Multi-order batch: select several orders; verify per-order notes and a single batch summary notice with correct totals.
Already-ready order: items all done-print/skip-print → completes with no advance note (count 0).
Already-completed / legacy order (Finding 2): select an order already in completed whose items are still pending-print (e.g. completed before 1.5.0, lazy default). Expect: no item mutation, no advance note, no new transition — the order is left exactly as it was.
Terminal-status order (Finding 4 / Q2): select a refunded (or cancelled/failed) order with pending items. Expect: it is not advanced and is not completed — WC's flip is reverted by the existing guard and the order stays refunded, with the standard "completion blocked" notice. (Also note the documented residual edge in §6: a terminal order whose items are already all resolved will be completed.)
Scope — single order edit screen: open one order with pending items, set status to Completed via the order dropdown + Update. Expect the old behaviour: blocked + reverted + error notice (auto-advance must NOT apply here).
Scope — other bulk actions: run "Set Status to In Printing" / "Prepare to Printing Export" — unchanged; no done-print advance.
Scope — programmatic: trigger a completion via WP-CLI/REST (or a quick snippet) — guard still blocks pending orders; no auto-advance.
Capability: as a role without edit_shop_orders, confirm no item mutation occurs.
Hook-order + outcome verification (the load-bearing assumption, Findings 3 & 5): on the installed WC version, run the happy path (#1) and assert the end state: the order row shows Completed, the items are done-print, and no "completion blocked" notice appears. As supporting evidence, with WP_DEBUG_LOG log the item statuses at the top of bulk_complete_advance_items() and inside the completion guard and confirm the advance log line precedes the guard line for the same order in one request. (The end-state assertion — not just log ordering — is what proves priority 9 actually wins and that the guard's order instance observed the saved meta. Re-check after any WC upgrade.)

10. Open questions

Q1 (placement): keep the handler in Order_Item_Status_Manager (recommended) or move to Bulk_Actions_Manager with dependency injection (requires reordering manager instantiation)? Default: Order_Item_Status_Manager.
Q2 (terminal orders) — resolved toward skip: this plan now skips advancing terminal/completed orders (§6). For cancelled/refunded/failed with unresolved items the existing guard reverts WC's completion, so they stay terminal; the one residual edge (terminal order with already-resolved items still completes) is documented and would need the §7 fallback / ID-filtering to close. If the team instead wants the original "follow core, complete everything" behaviour, remove the TERMINAL_STATUSES skip — but that re-introduces the silent refunded→completed + item-advance risk the review flagged.
Q3 (legacy CPT screen): confirm the legacy edit-shop_order screen is genuinely out of scope (operator uses HPOS only). If it must be covered too, mirror the hook on handle_bulk_actions-edit-shop_order.

order-done-plan-01.md 26 KB تاريخچه خام