MiraviaConnector/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a WordPress/WooCommerce plugin that integrates with the Miravia marketplace (owned by Alibaba). The plugin allows merchants to:
- Upload WooCommerce products to Miravia
- Download orders from Miravia
- Manage product synchronization between platforms
- Handle multiple Miravia accounts and profiles

## Architecture

### Core Components

**Main Plugin File**: `connector-miravia/connector-miravia.php`
- Entry point that defines plugin metadata and initializes the MiraviaWOO class
- Sets up WordPress hooks and admin menu structure
- Loads all required class dependencies

**Class Structure**:
- `class.core.php` - Core functionality for accounts, profiles, and database operations
- `class.api.php` - AJAX handlers for all Miravia API interactions
- `class.product.php` - WooCommerce product management and synchronization
- `class.order.php` - Miravia order processing and WooCommerce integration
- `class.categories.php` - Category mapping between WooCommerce and Miravia
- `class.db.php` - Database schema management and installation

**Shared Classes** (in `classes/shared/`):
- `MiraviaProduct.php` - Product data structure for Miravia API
- `MiraviaCombination.php` - Product variations/SKUs handling
- `MiraviaCategory.php`, `MiraviaFilter.php`, `MiraviaFeed.php` - Support classes

### Database Schema

The plugin creates custom tables:
- `{prefix}_miravia_accounts` - Stores Miravia seller account credentials
- `{prefix}_miravia_profiles` - Product upload profiles with mapping rules
- `{prefix}_miravia_products` - Synchronization status between WooCommerce and Miravia
- `{prefix}_miravia_orders` - Order tracking and fulfillment data

### Key Features

**Product Upload**:
- Products are uploaded via profiles that define category mappings and filters
- Images must be formatted as `{"Image": [...]}` structure for Miravia API compliance
- Support for both simple products and variations

**Order Management**:
- Downloads orders from Miravia and creates corresponding WooCommerce orders
- Tracks order status and fulfillment
- Handles shipping label generation

**Multi-Account Support**:
- Multiple Miravia seller accounts can be configured
- Each profile can be associated with specific accounts

## Development Commands

### Deployment
- **Deploy changes**: `./deploy_miravia.sh` - Automated git deployment script that commits and pushes changes

### No Build Process
This is a pure PHP WordPress plugin with no build step required. Changes are deployed directly.

### Testing
No automated test framework is configured. Testing should be done manually in a WordPress/WooCommerce environment.

## Important Implementation Notes

### API Integration
- All Miravia API calls go through the WeComm proxy server
- Authentication uses tokens stored in the accounts table
- Product images must follow specific structure: `Images: {"Image": [...]}`

### WordPress Integration
- Uses standard WordPress hooks and filters
- Admin interface is built with WordPress admin styles
- Internationalization support with 'miraviawoo' text domain

### Error Handling
- Logging is handled through custom LOG class
- Debug mode can be enabled via WordPress options
- Errors are stored in product sync records for troubleshooting

### Security Considerations
- All database operations use WordPress $wpdb for SQL injection protection
- User capability checks (`manage_woocommerce`, `manage_options`)
- Input sanitization with WordPress functions
- Nonce verification for admin actions