Athenian Order Resolution Manager

Developer starting point

This baseline is generated from the reviewed local technical reference and source folder. Deployed-version parity and external-provider effects remain separate verification steps.

5. Customer-Facing Workflow

The plugin adds a customer order resolution experience through the WooCommerce My Account area and a shortcode-based portal.

My Account Endpoint

The plugin registers a WooCommerce account endpoint:

/order-resolutions/

It also adds a My Account menu item labeled Order resolutions.

Shortcode

The same portal can be rendered on a page with:

[athenian_order_resolution]

If the visitor is not logged in, the shortcode returns a sign-in prompt.

New Case Intake Flow

A logged-in customer can:

1. Open the Order resolutions portal.
2. Select one of their recent WooCommerce orders.
3. Review the order summary, status, total, payment method, shipping method, item count, and vendor count.
4. Select the affected line items involved in the issue.
5. Choose the requested resolution.
6. Enter a requested amount when the selected resolution requires one.
7. Add additional details.
8. Add a subject and issue description.
9. Submit the case.

The customer is then redirected into the case detail thread.

Customer Case Detail View

The case detail screen shows:

• Case heading and status badge.
• Related WooCommerce order number.
• Case ID.
• Requested resolution summary.
• Requested amount when applicable.
• Requested-resolution review status.
• Affected item cards.
• Item thumbnails where available.
• Vendor label where available.
• SKU and item total.
• Add-on/custom metadata and uploaded asset links where available.
• Customer-visible threaded messages.
• Reply form for customer updates.

---

7. Case Status Model

The plugin tracks the lifecycle of each resolution case with stored status metadata.

| Status Key | Label | Typical Meaning | |---|---|---| | pending_review | Pending review | Customer has submitted or updated a case and support needs to review it. | | pending_customer | Waiting on customer | Support has replied and is waiting for the customer. | | resolved | Resolved | The issue has been resolved without necessarily closing the record. | | closed | Closed | The case is closed. | | partial_refund | Partial refund | A partial refund was recorded. | | refunded | Refunded | The remaining refundable balance was fully refunded. |

Customer replies automatically move the case back to pending_review. Admin replies can set the status after posting.

---

9. Admin Workflow

The plugin registers a private admin-facing case post type and places it under the WooCommerce admin menu.

Admin Post Type

| Detail | Value | |---|---| | Post type | aor_case | | Admin label | Resolution Cases | | Menu location | WooCommerce | | Public | No | | UI enabled | Yes | | Supports | Title, author, comments | | Rewrite | Disabled |

Admin List Columns

The case list includes columns for:

• Case title.
• Related order.
• Customer.
• Status.
• Updated date.

Case Admin Meta Boxes

The case edit screen includes four main meta boxes:

1. Resolution details

Shows the related WooCommerce order, customer, affected items, requested resolution, requested amount, review status, and editable case status.

1. Case thread

Displays the full message history, including customer messages, admin replies, system messages, and internal notes.

1. Add reply or note

Allows admins to post a customer-visible reply or an internal-only note and optionally update the case status.

1. Refund action

Shows the order’s remaining refundable balance and allows an admin to create a WooCommerce refund record from the case.

Admin Form Handlers

The plugin uses WordPress admin-post.php handlers for admin actions:

| Action | Purpose | |---|---| | aor_update_case | Updates case status and requested-resolution review status. | | aor_admin_message | Adds an admin reply or internal note. | | aor_process_refund | Creates a WooCommerce refund record and updates the case thread/status. |

All admin actions verify permissions with current_user_can('edit_post', $case_id) and WordPress nonces.

---

10. Refund Workflow

Athenian Order Resolution integrates with WooCommerce refunds through wc_create_refund().

Refund Behavior

Admins can enter:

• Refund amount.
• Refund reason.
• Manual-only toggle.

By default, the refund form is configured to create a manual WooCommerce refund record only. If manual-only is disabled, WooCommerce attempts to process the refund through the payment gateway.

Refund Validation

The plugin validates that:

• The case is attached to a valid WooCommerce order.
• The order has a remaining refundable balance.
• The refund amount is greater than zero.
• The refund amount does not exceed the remaining refundable amount.

Refund Side Effects

When a refund succeeds, the plugin:

• Saves _aor_resolution_type as full_refund or partial_refund.
• Saves _aor_resolution_amount.
• Updates the case status to refunded or partial_refund.
• Adds a customer-visible system message to the thread.
• Fires the aor_case_refund_processed action.
• Sends a refund notification email to the customer.

---

11. Data Model

Case Storage

Cases are stored as posts of type:

aor_case

Case Metadata

| Meta Key | Purpose | |---|---| | _aor_order_id | Related WooCommerce order ID. | | _aor_customer_id | Customer user ID. | | _aor_status | Current case status. | | _aor_last_actor | Last actor role to update the case. | | _aor_last_message_at | Timestamp of the last message. | | _aor_resolution_type | Final/admin-applied resolution type. | | _aor_resolution_amount | Final/admin-applied resolution amount. | | _aor_selected_items | Normalized snapshot of selected affected order items. | | _aor_requested_resolution | Customer-requested resolution type. | | _aor_requested_amount | Customer-requested amount, when applicable. | | _aor_requested_details | Customer-provided requested-resolution details. | | _aor_request_review_status | Review state of the requested resolution. |

Message Storage

Thread messages are stored as WordPress comments attached to the case post.

| Message Detail | Value | |---|---| | Comment type | aor_message | | Visibility meta | aor_visibility | | Author role meta | aor_author_role |

Supported visibility values include:

• customer — visible in the customer case thread.
• internal — admin-only note.

Supported author roles include:

• customer
• admin
• system

---

14. Custom Product / Add-On Metadata Support

Athenian Order Resolution is designed to provide more context than a generic order support form. It inspects order item metadata and surfaces meaningful custom details in the customer and admin case views.

Supported Metadata Patterns

The inspected plugin includes specific handling for:

• _apadd_addons — Athenian product add-on field groups and selected options.
• _apadd_signature — structured JSON containing custom metadata and uploads.
• Uploaded asset URLs associated with add-ons or custom signatures.
• Non-private order item metadata that passes display filtering.

Displayed Extension Types

| Type | Meaning | |---|---| | option | A selected add-on, option, or custom field value. | | upload | A linked uploaded customer/production asset. | | meta | Other display-safe line-item metadata. |

The plugin deduplicates extensions and filters out empty, hidden, private, or noisy metadata before displaying them.

---

17. Technical Architecture

Main Bootstrap File

athenian-order-resolution.php

Responsibilities:

• Defines plugin constants.
• Loads class files.
• Registers activation and deactivation hooks.
• Boots the plugin on plugins_loaded.
• Checks for WooCommerce availability.

Core Classes

| File | Class | Responsibility | |---|---|---| | includes/class-plugin.php | Athenian\OrderResolution\Plugin | Main service bootstrap and WooCommerce dependency notice. | | includes/class-activator.php | Activator | Registers post type/endpoint and flushes rewrite rules on activation/deactivation. | | includes/class-post-types.php | Post_Types | Registers aor_case and admin list columns. | | includes/class-case-service.php | Case_Service | Core business logic for cases, messages, status, selected items, requested resolutions, refunds, vendor context, and item metadata. | | includes/class-account.php | Account | My Account endpoint, shortcode, customer portal rendering, and customer POST actions. | | includes/class-admin.php | Admin | Admin meta boxes, admin replies, internal notes, status updates, and refund action handling. | | includes/class-emails.php | Emails | Notification handling for case lifecycle events. | | includes/class-assets.php | Assets | Conditional frontend/admin asset loading and admin notices. |

---

18. WordPress & WooCommerce Hooks

Registered Hooks

| Hook | Purpose | |---|---| | init | Registers the aor_case post type and account endpoint. | | query_vars | Adds aor_case query var. | | woocommerce_account_menu_items | Adds the Order resolutions My Account menu item. | | woocommerce_account_order-resolutions_endpoint | Renders the customer portal. | | template_redirect | Handles customer case creation and replies. | | add_meta_boxes | Registers admin case meta boxes. | | admin_post_aor_update_case | Handles admin case status/review updates. | | admin_post_aor_admin_message | Handles admin replies/internal notes. | | admin_post_aor_process_refund | Handles refund creation from the case screen. | | wp_enqueue_scripts | Conditionally loads customer portal assets. | | admin_enqueue_scripts | Loads case admin CSS. | | admin_notices | Renders plugin/admin action notices. |

Custom Actions Fired

| Action | Arguments | Purpose | |---|---|---| | aor_case_created | $case_id | Fired after a case is created. | | aor_case_message_added | $case_id, $comment_id | Fired after a message is added to a case. | | aor_case_status_changed | $case_id, $old_status, $new_status, $actor_role | Fired after a case status changes. | | aor_case_refund_processed | $case_id, $refund_id, $amount, $manual_only | Fired after a refund is created from a case. |

Custom Filters

| Filter | Purpose | |---|---| | aor_resolve_item_vendor_label | Allows external plugins to provide a vendor label for an order item/product. |

---

19. Security & Validation Notes

The plugin follows several WordPress/WooCommerce security conventions:

• Exits early if accessed outside WordPress.
• Uses strict typing declarations.
• Checks that WooCommerce is active before booting customer/admin workflows.
• Restricts customer actions to logged-in users.
• Verifies that a customer can only access cases tied to their own customer ID.
• Validates that a submitted case order belongs to the current customer.
• Requires at least one affected line item for case creation.
• Validates requested-resolution type and requested amount.
• Uses nonces for customer and admin form submissions.
• Uses current_user_can('edit_post', $case_id) for admin case actions.
• Sanitizes text fields, textarea fields, keys, URLs, and rendered output.
• Uses wp_kses_post() for message content intended to allow safe formatting.
• Hides internal notes from the customer thread.

---

21. Implementation Strengths

• Uses native WordPress posts/comments rather than introducing custom database tables.
• Keeps the case workflow close to WooCommerce orders and refunds.
• Provides both customer and admin interfaces without requiring a third-party helpdesk.
• Captures affected items as normalized case metadata.
• Handles both conversation history and financial resolution events in one thread.
• Includes a thoughtful dual-status model: case status plus requested-resolution review status.
• Supports vendor-aware and custom-product order contexts through metadata parsing and a vendor resolution filter.
• Uses conditional asset loading to avoid unnecessary CSS/JS on unrelated pages.
• Provides extensibility through lifecycle actions and vendor-label filtering.

---