Athenian E-Pricetag Manager

Developer starting point

This baseline documents the connector and queue architecture. It does not claim a live external e-pricetag sync or physical device update.

Admin Workflow

1. Configure Global Settings

Operators can define sync and payload behavior from the Settings tab.

Available settings include:

• Price policy: catalog, regular, sale_only, or regular_only.
• Include stock in payload: yes/no.
• Include QR URL in payload: yes/no.
• QR URL mode: product URL or custom URL.
• Custom QR URL.
• Debounce seconds.
• Batch size.
• Log retention days.
• Encryption mode.

2. Configure a Connector

The Connectors tab allows an operator or developer to choose the appropriate publishing path.

For the Generic REST connector, settings include:

• Enabled state.
• Endpoint URL.
• Auth type: none, bearer, basic, or custom header.
• Bearer token.
• Basic username/password.
• Custom header name/value.
• Timeout seconds.

3. Create Label Mappings

The Label Mappings tab lets administrators associate a physical label UID with a WooCommerce product and store key.

The UI provides product search, selected-product display, label UID entry, template key entry, notes, and mapping save actions.

4. Queue Updates

Updates can be queued automatically through product/variation save hooks, through label mapping changes, through the scheduled sale scanner, through the admin quick queue tool, or through WP-CLI.

5. Run and Monitor Sync

The Dashboard provides mapped-label and pending-queue counts. The Run Queue action processes ready queue rows and updates each mapping with success or error status.

---

Technical Architecture

Bootstrap and Dependency Model

The main plugin file defines constants, registers an autoloader for the Athenian\EPricetag\ namespace, installs tables on activation, and initializes the plugin on plugins_loaded only when WooCommerce is active.

Core constants:

ATH_EPT_VERSION = '0.1.0'
ATH_EPT_FILE
ATH_EPT_DIR
ATH_EPT_URL
ATH_EPT_SLUG = 'athenian-e-pricetag-sync-manager'

Hard dependency:

• WooCommerce must be installed and active.

Primary namespace:

Athenian\EPricetag

Core Classes

| Class | Responsibility | |---|---| | Plugin | Main singleton, activation coordination, admin/REST/observer/queue registration. | | Bootstrap | Registers WP-CLI commands on init. | | DB | Creates and upgrades custom database tables. | | Settings | Ensures and manages option defaults. | | Util | Time helpers, capability helper, Action Scheduler detection, encryption/decryption, REST response helper. | | Log | Inserts and prunes operational log rows. | | Admin\Admin | Registers the WooCommerce submenu, assets, and admin UI markup. | | REST\Controller | Registers and handles authenticated REST routes. | | Sync\Observer | Observes product, variation, and sale-scan events. | | Sync\Payload | Builds the vendor-agnostic product payload. | | Sync\Queue | Enqueues, batches, publishes, retries, and marks queue items. | | Connectors\Registry | Lists, fetches, and selects active connectors. | | Connectors\GenericRestConnector | Implements HTTP publishing to a configurable endpoint. | | CLI\Commands | Adds wp ath-ept commands. |

Database Tables

The plugin creates three custom tables.

#### {prefix}_ath_ept_labels

Stores physical label mappings and last sync status.

Important columns:

• id
• label_uid
• product_id
• variation_id
• store_key
• template_key
• notes
• last_payload_hash
• last_synced_gmt
• last_status
• last_error
• created_gmt
• updated_gmt

Indexes:

• Primary key on id.
• Unique key on label_uid + store_key.
• Product index on product_id + variation_id.
• Store and updated indexes.

#### {prefix}_ath_ept_queue

Stores queued ESL update work.

Important columns:

• id
• label_uid
• store_key
• product_id
• variation_id
• event_key
• payload
• payload_hash
• status
• attempts
• last_error
• scheduled_gmt
• created_gmt
• updated_gmt

Indexes:

• Status/schedule index for queue runner selection.
• Label/store index.
• Payload hash index.

#### {prefix}_ath_ept_logs

Stores lightweight operational logs.

Important columns:

• id
• level
• message
• context
• created_gmt

Indexes:

• Log level.
• Created timestamp.

WordPress Options

| Option | Purpose | |---|---| | ath_ept_settings | Global plugin settings and payload behavior. | | ath_ept_connectors | Connector-specific configuration payloads. | | ath_ept_db_version | Current installed custom table schema version. |

Default settings:

[
  'price_policy' => 'catalog',
  'include_stock' => false,
  'include_qr' => true,
  'qr_url_mode' => 'product',
  'custom_qr_url' => '',
  'debounce_seconds' => 10,
  'batch_size' => 100,
  'log_retention_days' => 30,
  'encryption' => 'wp_salt',
]

Sync Event Flow

WooCommerce product/variation change
        ↓
Observer identifies product or variation
        ↓
Queue looks up matching label mappings
        ↓
Payload builder creates normalized product payload
        ↓
Payload hash is checked against existing pending/retry rows
        ↓
Queue row is inserted with debounce schedule
        ↓
Action Scheduler or WP-Cron kicks queue runner
        ↓
Queue groups ready rows by store_key
        ↓
Active connector publishes batch
        ↓
Queue rows are marked done or retry
        ↓
Label mapping receives last_status, last_error, last_synced_gmt, and last_payload_hash

Automatic Sync Triggers

| Trigger | Hook / Source | Event Key | |---|---|---| | Product save | save_post_product | product_save | | Variation save | woocommerce_save_product_variation | variation_save | | Scheduled sale scan | ath_ept_cron_scan_sales | sale_scan | | Mapping upsert | REST /labels/upsert | mapping_upsert | | Manual admin queue | REST /sync/queue_for_product | manual | | WP-CLI queue | wp ath-ept sync | wpcli |

Scheduled Tasks

| Task | Schedule | Purpose | |---|---:|---| | ath_ept_cron_scan_sales | Hourly | Scans recent on-sale products and queues mapped products. | | ath_ept_cron_run_queue | Every minute fallback | Runs queue when Action Scheduler is not available. | | ath_ept_run_queue | Action Scheduler / single event | Runs the queue when Action Scheduler is available or as a scheduled single event. | | ath_ept_cron_prune | Daily | Prunes old log rows based on retention settings. |

Queue Retry Behavior

Failed queue rows are marked retry with progressive backoff delays:

30 seconds → 2 minutes → 10 minutes → 30 minutes → 2 hours

> Source reference excerpt truncated; use the linked technical reference and repository baseline for the full implementation context.

Security and Permissions

Security-relevant implementation details include:

• Admin menu uses manage_woocommerce capability.
• REST endpoints use the same manage_woocommerce capability gate.
• Admin JavaScript calls REST endpoints with a WordPress REST nonce.
• Connector inputs are sanitized against connector schemas before saving.
• Connector secrets are encrypted by default using wp_salt('auth')-derived AES-256-CBC encryption.
• Product search is limited to authenticated users with WooCommerce management capability.
• Database writes use $wpdb insert/update helpers and prepared statements where dynamic lookups are used.

---

Current Implementation Boundaries

The uploaded version is 0.1.0, so a few areas should be treated as intentional early-stage boundaries:

• Generic REST is the practical implemented connector path.
• SoluM AIMS, VusionCloud / SES-imagotag, and Pricer Plaza classes are guided setup stubs, not complete first-party vendor integrations.
• The admin mapping UI currently focuses on product-level mapping, while the data model and REST layer include variation_id support.
• Queue visibility in the admin dashboard is limited to counts and mapping status, not a full queue inspector table.
• Logs are stored in a custom table but are not exposed in the visible admin UI in the same way mappings and status are.
• Incoming bidirectional status sync from ESL vendors is not implemented in the reviewed package.
• Template management is represented by template_key metadata but not by a full visual template editor.

---

Technical Summary for Developers

Athenian E-Pricetag Sync Manager is a WooCommerce-dependent WordPress plugin using the Athenian\EPricetag namespace. It installs three custom tables for label mappings, queue rows, and logs; registers an admin page under WooCommerce; exposes REST routes under ath-ept/v1; observes product/variation saves; scans on-sale products hourly; builds normalized payloads from WooCommerce product data; stores queued jobs with payload hashes; runs batches through an active connector; and updates label-level status after success or failure.

The connector architecture currently includes an implemented Generic REST connector and guided setup classes for SoluM AIMS, VusionCloud / SES-imagotag, and Pricer Plaza. WP-CLI support allows product sync queueing and manual queue execution through wp ath-ept commands.

---