# 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 plugin that extends WooCommerce functionality to manage print orders sent to third-party providers. It adds custom order statuses ("Prepare to Printing" and "In Printing"), bulk actions, CSV export/import capabilities, and tracking fields specific to the printing workflow.

**Plugin Details:**
- Text Domain: `studiou-wc-ord-print-statuses`
- Current Version: 1.3.1
- Requires: WordPress 5.8+, WooCommerce 3.0+, PHP 7.2+

## Architecture

### Manager-Based Pattern

The plugin uses a manager-based architecture where the main plugin class (`Studiou_WC_Ord_Print_Statuses`) initializes specialized manager classes that handle distinct concerns:

1. **Order_Status_Manager** (`includes/class-order-status-manager.php`)
   - Registers custom order statuses: `wc-to-print` and `wc-in-print`
   - Handles status transitions and automatically updates metadata timestamps
   - Hooks into WooCommerce payment completion to set orders to "processing"

2. **Order_Fields_Manager** (`includes/class-order-fields-manager.php`)
   - Adds "Print Information" section to order edit pages
   - Manages fields: `to_print_date`, `in_print_date`, `external_ref_ord_no`, `external_ref_ord_delivered`

3. **Bulk_Actions_Manager** (`includes/class-bulk-actions-manager.php`)
   - Registers bulk actions: "Prepare to Printing Export", "Set Status to Prepare to Printing", "Set Status to In Printing"
   - Generates CSV exports with complex product data (categories, variations, images)

4. **Custom_Columns_Manager** (`includes/class-custom-columns-manager.php`)
   - Adds custom columns to WooCommerce orders list: "To Print Date", "In Print Date", "External Order Number"

5. **Import_Manager** (`includes/class-import-manager.php`)
   - Provides admin UI under WooCommerce menu for importing CSV protocols
   - Handles InPrint Protocol (sets orders to "in-print" with external references)
   - Handles Delivered Protocol (sets orders to "completed" with delivery timestamp)

6. **Order_Search_Manager** (`includes/class-order-search-manager.php`)
   - Extends WooCommerce order search to include external reference order numbers

7. **Studiou_DB_Manager** (`includes/class-db-manager.php`)
   - Centralized database operations using static methods
   - Contains complex SQL for export query joining orders, products, variations, categories, and images
   - Handles CSV parsing and protocol imports

### Key Database Operations

The export query in `Studiou_DB_Manager::get_orders_for_printing()` performs a complex join across:
- `wp_wc_orders` (order data)
- `wp_wc_order_product_lookup` (order products)
- `wp_posts` (products and variations)
- `wp_wc_product_attributes_lookup` (product attributes, specifically 'pa_format')
- `wp_terms` and `wp_term_taxonomy` (product categories)
- `wp_postmeta` and `wp_posts` (product images)

This query extracts: order number, product category, product name, variation name, variation type, image URL, quantity, and customer email.

### Order Metadata Keys

- `to_print_date` - Timestamp when order moved to "Prepare to Printing" status
- `in_print_date` - Timestamp when order moved to "In Printing" status
- `external_ref_ord_no` - External order number from print provider
- `external_ref_ord_date` - Date from external print provider
- `external_ref_ord_delivered` - Delivery timestamp

## Development Commands

### Logging

The plugin includes a simple logging utility (`includes/utils-log.php`):
- `UtilsLog::log($message)` - Logs to WordPress error log when `WP_DEBUG` is enabled
- Check logs in `wp-content/debug.log` if `WP_DEBUG_LOG` is enabled

### WordPress/WooCommerce Hooks

All managers register their hooks in constructors. Common patterns:
- `add_action('init', ...)` - Register post statuses
- `add_filter('wc_order_statuses', ...)` - Modify WooCommerce status lists
- `add_filter('bulk_actions-woocommerce_page_wc-orders', ...)` - Add bulk actions
- `add_action('woocommerce_admin_order_data_after_order_details', ...)` - Display custom fields

### Testing

When testing status changes:
1. Enable `WP_DEBUG` in `wp-config.php` to see log output
2. Check that metadata is properly set when statuses change
3. Test bulk actions with multiple orders to verify CSV generation
4. Test import functionality with properly formatted CSV files

### CSV Formats

**Export Format (Prepare to Printing):**
- Headers: `order_no`, `prod_cat`, `prod_name`, `prod_var`, `prod_var_type`, `prod_img_url`, `qty`, `email`

**InPrint Protocol Import Format:**
- Required headers: `order_no`, `externalorder`, `externalorderdate`

**Delivered Protocol Import Format:**
- Required header: `order_no`

## Localization

The plugin supports internationalization:
- Text domain: `studiou-wc-ord-print-statuses`
- Translation files in `languages/` directory
- Czech localization (cs_CZ) already implemented
- Use WordPress `__()`, `_e()`, `_n_noop()`, `_x()` functions for all user-facing strings

## Important Considerations

1. **HPOS Compatibility**: The plugin uses `woocommerce_page_wc-orders` hooks, indicating support for WooCommerce High-Performance Order Storage (HPOS)

2. **Status Slug Naming**: Custom statuses use `wc-` prefix internally but display without prefix (`wc-to-print` vs "Prepare to Printing")

3. **CSV Output**: The `prepare_to_printing_export` bulk action terminates with `exit` after outputting CSV headers, preventing further PHP execution

4. **Database Queries**: Direct SQL queries use `$wpdb->prepare()` implicitly through `intval()` for order IDs. Always sanitize inputs when modifying database operations.

5. **Admin Menu**: Import functionality is added as a submenu under WooCommerce admin menu, requires `manage_woocommerce` capability