ZincoGroup Hub — WordPress plugin

The WordPress side of the price report. The hub (pharma-hub) reads the store's offers on KuantoKusta, collects competitor prices and compares them; this plugin shows the result inside WooCommerce and links each KuantoKusta offer to a WooCommerce product.

The plugin is shown to the client as ZincoGroup Hub. "Pharma Hub" is only the technical name of the service and of this repository.

Status

Requirements

Installing

1. Download pharma-hub-plugin-X.Y.Z.zip from the releases and upload it in Plugins → Add New → Upload Plugin.

2. Recommended: put the hub's address and the token in wp-config.php, above the "That's all, stop editing!" line:

   define( 'PHARMA_HUB_URL', 'https://hub.example.com' );
   define( 'PHARMA_HUB_TOKEN', 'phk_...' );

   Without them, type both in ZincoGroup Hub → Ligação ao hub. The token is then stored encrypted with a key derived from the site's secret keys in wp-config.php; if those keys are regenerated, the token has to be typed again.

3. In ZincoGroup Hub → KuantoKusta → Definições, send the store's KuantoKusta API key to the hub. The hub checks it with KuantoKusta and stores it; the plugin keeps no copy.

4. The EAN is looked up in WooCommerce's own "GTIN, UPC, EAN or ISBN" field and then in _alg_ean, the field of "EAN Barcode Generator for WooCommerce". If the store uses another EAN plugin, type its meta key in Definições.

5. Relatório shows each product's price against the lowest on KuantoKusta, with filters and a CSV export. Regenerar asks the hub for a new collection and follows it until the report is updated. The "histórico" link of a row shows how the store's price and the lowest price moved over time.

6. Vínculos links each KuantoKusta offer to a product by SKU, EAN or store address, and lists the offers a person has to resolve.

The screen needs the manage_woocommerce capability (administrators and shop managers).

Development

composer install
composer lint     # WordPress coding standards, PHP compatibility, docblocks
composer test     # PHPUnit; no WordPress needed

The tests load the plugin's classes with a handful of stubbed WordPress functions (tests/bootstrap.php). Code that needs a real WordPress is checked on a test site.

Commit messages follow Conventional Commits (commitlint.config.js). CI runs the lint, php -l on PHP 7.4 and 8.3, PHPUnit on both, and commitlint on every commit of a pull request. Merging a version bump into production creates the tag, the release and the zip (.github/workflows/release.yml).

Layout

pharma-hub-plugin.php                    plugin header, constants, bootstrap
includes/
  class-pharma-hub-settings.php          settings: read, validate, store
  class-pharma-hub-secret-box.php        encryption of the token kept in the database
  class-pharma-hub-client.php            calls to the hub
  class-pharma-hub-error.php             a failed call, with the hub's error code
  class-pharma-hub-linker.php            linking rules: SKU, then EAN, then store address
  class-pharma-hub-links.php             the links table and the lookups on this site
  class-pharma-hub-admin.php             menu, tabs, settings, hub connection page, shared styles
  class-pharma-hub-format.php            money, percentages, Portugal time, CSV cells
  class-pharma-hub-report.php            reading, filtering and sorting the report
  class-pharma-hub-admin-report.php      the Relatório tab and the CSV export
  class-pharma-hub-history.php           one offer's history: periods, changes, chart geometry
  class-pharma-hub-admin-history.php     the history screen and its SVG chart
  class-pharma-hub-admin-runs.php        the Regenerar button and its admin-ajax actions
assets/js/regenerate.js                  follows a collection from the report page
  class-pharma-hub-admin-links.php       the Vínculos tab and its actions
uninstall.php                            removes the settings when the plugin is deleted
tests/                                   PHPUnit, without WordPress
docs/design.md                           how the plugin works and why