PrimeLink – WooCommerce Import Export
=====================================

PrimeLink is an advanced import/export plugin built 100% for WooCommerce (this package is for version **1.0.0**).
It provides visual wizards for imports and exports, template management, scheduling, and integration with external platforms – all inside the WordPress admin.


## Requirements

- **WordPress**: 5.8 or higher  
- **WooCommerce**: 5.0 or higher (latest stable recommended)  
- **PHP**: 7.4 or higher (PHP 8.0+ recommended for best performance)  
- **MySQL/MariaDB**: Same as WordPress requirements  


## Supported WooCommerce entities

- Products  
- Orders  
- Customers  
- Coupons  
- Product Categories  
- Product Tags  
- Product Attributes  
- Product Variations  
- Product Reviews  
- Product Downloads  


## Key import features

- **Step‑by‑step import wizards** for each entity type.
- **Supported sources**:
  - Upload (CSV, XML, XLSX).
  - Existing files on server.
  - URL.
  - FTP/SFTP.
  - Real‑time import from external platforms.
- **Visual field mapping**:
  - Drag & drop mapping between source columns and WooCommerce fields.
  - Presets and templates per entity (products, orders, etc.).
- **Test mode / dry‑run**:
  - Run an import in test mode to validate data without writing to the database.
- **Advanced options**:
  - Batch size and performance controls.
  - Error handling and logging.
  - Rollback support for imports via tracking.
- **Anomaly Detection**:
  - Intelligent detection of data anomalies during import (price changes, content changes, stock issues, missing data).
  - Three severity levels: Critical, Warning, and Info.
  - Automatic import pause on critical anomalies to prevent data corruption.
  - Review modal with detailed anomaly information and export options.
  - Click on product names to navigate directly to items in the import preview.
  - Export anomalies to CSV or Excel for external analysis.


## Key export features

- **Step‑by‑step export wizards** for each entity type.
- **Supported destinations**:
  - Download (CSV, XML, XLSX, PDF).
  - Save to server.
  - FTP/SFTP.
- **Visual field mapping for export**:
  - Choose which fields to export and in what order.
  - Custom columns and formulas depending on entity type.
- **Scheduling**:
  - Schedule automatic exports with WordPress cron.
  - Separate management for manual exports and scheduled exports.


## Template Manager

- Central place to manage import/export mapping templates.
- Templates are stored **per entity type**:
  - Products, Orders, Customers, Coupons, Categories, Tags, Attributes, Variations, Reviews, Downloads.
- Quick loading of templates in the import wizard (final step) and export wizards.


## Manage Imports & Exports

- **Manage Imports** screen:
  - See drafts, running and completed imports grouped by type.
  - Resume wizards, start/pause/resume jobs.
  - View progress bars and basic stats.
  - **Review Anomalies** button appears when anomalies are detected during import.
  - Click to open detailed anomaly review modal with full item information.
- **Manage Exports** screen:
  - Similar management for export drafts and scheduled exports.
  - Direct download of finished export files and logs.

## Anomaly Detection & Review

- **Automatic Detection**:
  - Real-time analysis of import data for potential issues.
  - Detects price anomalies (sudden price drops/increases).
  - Identifies content changes (description/title modifications).
  - Monitors stock level issues and data quality problems.
- **Review Interface**:
  - Dedicated modal for reviewing detected anomalies.
  - Filterable table showing row number, item name, anomaly level, type, and message.
  - Click on product/item names to navigate directly to that row in the import preview table.
  - Export anomalies to CSV or Excel format for external analysis or reporting.
- **Severity Levels**:
  - **Critical**: Automatically pauses import and sends email alerts (e.g., price drops >50%).
  - **Warning**: Logged but import continues (e.g., price changes 10-50%).
  - **Info**: Informational messages logged for review (e.g., minor content changes).


## Statistics & System Status

- **Statistics & analytics** page:
  - High‑level counters for imports and exports per entity.
  - Basic charts (via Chart.js) for activity over time.
- **System status** page:
  - Checks PHP version, WordPress version, WooCommerce environment, required extensions, upload dir permissions, cron mode, etc.


## Activation Wizard

- Non‑intrusive activation wizard for first‑time setup:
  - Appears as a centered pop‑up over the dashboard (WordPress menu remains visible).
  - Collects basic configuration (license, environment checks, email notifications).
- **“Skip for now”** with persistence:
  - If the user skips the wizard, it will not re‑appear automatically until restarted from the dashboard.
- **“Restart wizard”**:
  - Button from the plugin dashboard/settings to re‑launch the wizard at any time.


## Platform Connectors

- **Live platform integration**:
  - Import products, orders, customers and coupons in real time.
  - Connection tests with detailed error messages and logging.
  - Automatic preview of fetched data for the current import type.
- **Connector credentials**:
  - Saved in plugin settings and automatically pre‑filled in the import wizard.


## File Formats and Engines

- CSV parsing with **League CSV** (delimiter and encoding options).
- XLSX parsing with **PhpSpreadsheet**.
- PDF export via **Dompdf** (for supported entities/modes).


## Logging & Diagnostics

- Centralized logging via **Monolog** with a dedicated log file under the WordPress uploads directory.
- Optional logging to WordPress `debug.log` when `WP_DEBUG` is enabled.
- Detailed debug information for platform connectors when needed.


## Architecture Highlights

- Modular services per entity type (imports/exports).
- Background processing via WordPress cron for long‑running jobs.
- REST API layer for wizards, templates, and async operations.
- No front‑end impact: all UI is inside the WordPress admin.


## Installation

1. Upload the plugin folder `primelink` to `wp-content/plugins/` **or** upload the ZIP via **Plugins → Add New → Upload Plugin**.
2. Activate **PrimeLink – WooCommerce Import Export** from the **Plugins** page.
3. After activation, open **WooCommerce → PrimeLink** (or the PrimeLink menu entry) and follow the **Setup Wizard**:
   - Enter your license/purchase code (if applicable).
   - Review basic environment checks.
   - Configure email notifications and basic defaults.


## Quick Start

- **First Import**
  - Go to the PrimeLink menu in the WordPress admin.
  - Choose an import type (e.g. Products) and start the import wizard.
  - Select your source (Upload, URL, FTP, etc.).
  - Map fields using the visual mapping interface.
  - Run in **Test mode** (dry‑run), then start a real import when you are satisfied.

- **First Export**
  - Go to the Exports section.
  - Choose an export type (e.g. Orders) and start the export wizard.
  - Configure filters and field mapping.
  - Run an on‑demand export or schedule it using WordPress cron.


## Uninstall & Data Cleanup

- When uninstalling the plugin from **Plugins → Installed Plugins**, PrimeLink behaves as follows:
  - If the **“Delete all PrimeLink data on uninstall”** option is **disabled** (default):
    - All settings, drafts, and tracking data are kept.
    - Only scheduled cron events related to PrimeLink are removed.
  - If **enabled** in **Settings → Notifications & Cleanup**:
    - PrimeLink deletes its settings, drafts, import/export states and tracking meta.
    - Uploads directory cleanup (source files) is controlled separately by the retention settings and uninstall filters.

This behaviour is implemented in `uninstall.php` and can be customized by developers via the `mt_primelink_uninstall_delete_data` filter/option.


## Internationalization (i18n)

- Text domain: **`primelink`**  
- Translation catalogue: `languages/primelink.pot`  
- All user‑facing strings are wrapped in standard WordPress i18n functions (`__`, `_e`, `esc_html__`, etc.).  
- You can create translations by generating `.po/.mo` files from `primelink.pot` and placing them in the `languages` directory.


## Security & Permissions

- All REST API endpoints are protected by:
  - Capability checks (default: `manage_woocommerce` if WooCommerce is active, otherwise `manage_options`, filterable via `mt_primelink_capability`).
  - Nonce verification via the `X-WP-Nonce` header for write operations.
  - Optional rate limiting via the built‑in rate limiter helper.
- AJAX endpoints are admin‑only (`wp_ajax_...`) and protected by:
  - `check_ajax_referer( 'mt_primelink_nonce', 'nonce' )`.
  - The same capability filter `mt_primelink_capability`.
- Webhook endpoints require a per‑import token; if none is configured, access is denied by default (can be relaxed via a filter for advanced setups).


## License

- PrimeLink itself is licensed under **GPL‑2.0‑or‑later** (see the files in the `licensing` directory).
- The plugin bundles several third‑party libraries (League CSV, PhpSpreadsheet, Guzzle, Dompdf, Monolog, Symfony components, etc.), each shipped under their respective open‑source licenses. See the `licensing` directory and the individual `LICENSE` files inside `lib/vendor/` for more information.

