[WOOMOB-3751] Recover from deterministic refund rejections instead of retrying

[samiuelson]

Description

Fixes WOOMOB-3751

The mapped refund errors always fail the same way, so the Retry we show cannot work. Each error now offers what can help:

• order_not_refundable: the "nothing to refund" screen.
• quantity / amount / already refunded: "Review remaining items", which reloads the order and keeps the selection that is still refundable.
• invalid_refund_amount: no action.
• unmapped errors: Retry, as before.

Unmapped create errors now show the generic message instead of the store's raw one. Copy fixes: the missing full stops, and the already-refunded message no longer claims to name one item.

iOS: woocommerce-ios#17732

Test Steps

Needs a second client (web admin) to change the order while the flow is open.

1. Use store that supports server-calculated refunds - this requires WooCommerce 11.1.0 or newer, you can ask claude to generate .zip, or use nightly build from woocommerce monorepo. *
2. In POS, start a refund on a paid order with an item of quantity 2 or more.
3. In the web admin, refund one unit of that item.
4. In POS, tap Continue: the store's reason shows, Continue is disabled, "Review remaining items" appears.
5. Tap it: the list reloads with the units still refundable and keeps your selection.
6. Refund the whole order in the web admin and repeat steps 2-4: the flow ends on the "nothing to refund" screen.
7. Turn off the network mid-preview: the error is generic and still offers Retry.
8. To hit the create path instead of the preview, let the web-admin refund land after you tap Continue but before you confirm: the error screen shows the store's reason with "Review remaining items" as the primary action and "Back to order" below it.

* You can also use the test store cool-shop.mystagingwebsite.com.

Images/gif

N/A

• I have considered if this change warrants release notes and have added them to RELEASE-NOTES.txt if necessary. Use the "[Internal]" label for non-user-facing changes.

[dangermattic]

	2 Warnings
⚠️	This PR is larger than 300 lines of changes. Please consider splitting it into smaller PRs for easier and faster reviews.
⚠️	This PR is assigned to the milestone 25.5. This milestone is due in less than 2 days. Please make sure to get it merged by then or assign it to a milestone with a later deadline.

Generated by 🚫 Danger

[wpmobilebot]

📲 You can test the changes from this Pull Request in WooCommerce Android by scanning the QR code below to install the corresponding build.

	App Name	WooCommerce Android
	Platform	📱 Mobile
	Flavor	Jalapeno
	Build Type	Debug
	Build Number	778
	Version	25.4-rc-1
	Application ID	com.woocommerce.android.prealpha
	Commit	9ca3715
	Installation URL	3i13dnmm6f05o

Automatticians: You can use our internal self-serve MC tool to give yourself access to those builds if needed.

[claude]

AI Code Review - No issues found. The changes look good.

Reviewed the POS refund-recovery flow end to end: the new WooPosBuildRefundContent preserves selection correctly (filters preserved ids to what's still refundable, falls back to selecting all remaining), refreshRefundableItems() sources the preserved selection from either the live Content state or contentStateBeforeRefund and bypasses the loadRefundableItems early-return guard as intended, and both the preview and submission paths route OrderNotRefundable to the terminal NoRefundableItems state while mapped RefreshItems codes offer a reload instead of a retry that cannot succeed. The RefundFlowStarted analytics event is correctly gated to isFlowStart so a reload doesn't double-count, and the recovery mapping / gating is well covered by the new WooPosRefundApiErrorTest and WooPosRefundViewModelTest cases. Dropping the raw store error.message fallback in WooPosRefundSubmissionProcessor is a deliberate UX change (technical, store-locale text stays in the log) and is reflected in the updated processor tests.

PR housekeeping

• Applied repo POS guidance (AGENTS.md): plain ViewModel + StateFlow, no store-only patterns, no Android framework imports in the ViewModel — all respected.
• The strings.xml change is copy-only (trailing periods + the new woopos_refund_review_remaining_items_button); no test plan needed for the wording itself.

---

_{Automatic review · claude-opus-4-8 · Workflow run}

_{How to reply to a finding}

Reply on this review (or inline at the line the finding refers to) with one of:

• @claude addressed - I made the change. Bot verifies against the next diff before marking resolved.
• @claude rejected: <reason> - Will not fix; reason gets quoted on the next review.
• @claude not-applicable - Finding does not apply (wrong file, already covered elsewhere, etc.).

The bot honours these on the next review pass.

[iamgabrielma]

👋 I won't be able to review the Android PRs until next week, can these be redirected to an Android dev?