# CLAUDE.md

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

## Project Overview

**QDR - Studiou WC Export/Import Product Categories** is a WordPress plugin that extends WooCommerce to provide batch export/import functionality for product categories and category manipulation tools.

**Current Version:** 1.3.0

## Requirements

- WordPress 6.8.1+
- PHP 8.2+
- WooCommerce 9.8+
- WooCommerce Protected Categories 2.7+ (optional, for visibility features)

## Plugin Architecture

### Core Files

- **studiou-wc-product-cat-manage.php** - Main plugin file containing:
  - Plugin initialization and dependency loading
  - Admin menu registration under Products menu
  - Asset enqueueing for admin pages
  - WooCommerce HPOS compatibility declaration
  - Text domain loading for translations

### Class Structure (includes/)

The plugin follows a modular class-based architecture:

- **class-studiou-wc-product-cat-manage-db.php** - Database operations layer
  - Handles all database queries for product categories
  - Manages category hierarchy (parent/child relationships)
  - Provides category formatting and data retrieval
  - Interfaces with WooCommerce taxonomy and WooCommerce Protected Categories plugin

- **class-studiou-wc-product-cat-manage-export.php** - Export functionality
  - Generates CSV files from product categories
  - Includes all category properties (name, slug, parent, description, display-type, visibility, protected-passwords)
  - Handles UTF-8 encoding and proper CSV formatting

- **class-studiou-wc-product-cat-manage-import.php** - Import functionality
  - Processes CSV files with operations: 'A' (add), 'U' (update), 'D' (delete)
  - Validates data and handles errors
  - Creates/updates/deletes categories based on operation column
  - Manages WooCommerce Protected Categories settings

- **class-studiou-wc-product-cat-manage-manipulator.php** - Category manipulation operations
  - Move products between categories (removes from source, adds to target)
  - Batch description updates for multiple categories
  - Delete products in category (permanently deletes products and variants)
  - Uses direct database queries for reliable product detection
  - Batch processing for delete operations (10 products per batch)

### Views (views/)

- **import.php** - Import page UI
- **export.php** - Export page UI
- **manipulations.php** - Category manipulations page UI with three operations:
  - Move products between categories (two dropdowns + "Do" button)
  - Batch description between categories (checkbox list + textarea + "Do" button)
  - Delete products in category (checkbox list + "Delete" button + progress bar)

### Assets

- **assets/css/admin.css** - Admin styling including:
  - Progress bar styling
  - Warning message styling (yellow background for destructive operations)
  - Danger button styling (red for delete operations)
- **assets/js/admin.js** - Admin JavaScript including:
  - AJAX handlers for all operations
  - Batch processing logic for delete operations
  - Real-time progress bar updates
  - Confirmation dialogs for destructive operations

### Translations

- **languages/** - Contains .pot, .po, and .mo files
- Text domain: `studiou-wc-product-cat-manage`
- All user-facing strings must be wrapped in translation functions: `__()`, `_e()`, `sprintf()`

## CSV Format

CSV files use comma separators, double-quote string isolation, UTF-8 encoding:

| Column | Description |
|--------|-------------|
| name | Category name (required, used as identifier) |
| url-name | URL slug |
| parent-name | Parent category name (empty if root) |
| description | Category description |
| display-type | Values: 'default', 'products', 'subcategories', 'both' |
| visibility | Values: 'public', 'protected' (WooCommerce Protected Categories) |
| protected-passwords | Pipe-separated passwords (|) if visibility='protected' |
| operation | 'A' (add), 'U' (update), 'D' (delete) |

## Development Guidelines

### When Modifying Code

1. **Translations**: All new user-facing strings must use `__()` or `_e()` with text domain `'studiou-wc-product-cat-manage'`
2. **Security**: Always validate and sanitize user input, use nonces for form submissions
3. **WooCommerce Integration**: Use WooCommerce taxonomy 'product_cat' for all category operations
4. **Error Handling**: Provide clear error messages and validation feedback
5. **Compatibility**: Maintain HPOS (High-Performance Order Storage) compatibility declaration
6. **Direct Exits**: Always include `if (!defined('WPINC')) { die; }` at top of PHP files
7. **Batch Processing**: For operations on large datasets, use batch processing (10 items per batch recommended)
8. **Destructive Operations**: Always include confirmation dialogs and warning messages for operations that cannot be undone
9. **Progress Tracking**: For long-running operations, implement real-time progress bars

### Plugin Constants

```php
STUDIOU_WCPCM_VERSION        // Plugin version
STUDIOU_WCPCM_PLUGIN_DIR     // Plugin directory path
STUDIOU_WCPCM_PLUGIN_URL     // Plugin URL
STUDIOU_WCPCM_PLUGIN_BASENAME // Plugin basename
```

### Admin Menu Structure

All pages are added under **Products** menu:
- Import Product Categories (slug: `studiou-import-product-categories`)
- Export Product Categories (slug: `studiou-export-product-categories`)
- Category Manipulations (slug: `studiou-category-manipulations`)
  - Move products between categories
  - Batch description between categories
  - Delete products in category

### Key Integration Points

- **WooCommerce Protected Categories**: Plugin extends category visibility with 'public'/'protected' settings and password protection
- **Product Assignment**: When moving products, the plugin modifies product-category term relationships while preserving other category assignments
- **Hierarchy Management**: Categories maintain parent-child relationships via `parent-name` field
- **Product Deletion**: Uses WooCommerce `wc_get_product()` and `product->delete(true)` for proper product deletion
  - Automatically handles variable products by deleting all variations first
  - Force delete (true parameter) ensures permanent removal bypassing trash
  - Processes in batches to prevent PHP timeouts and memory issues

## Testing Notes

- Test import/export with categories that have special characters, quotes, commas
- Test category hierarchy (parent/child relationships)
- Test moving products between categories when products have multiple category assignments
- Test batch description updates with multiline text
- Test delete products operation with:
  - Simple products
  - Variable products with multiple variations
  - Products in multiple categories
  - Large numbers of products (test batch processing)
  - Edge cases: empty categories, categories with only variations
- Verify translations are properly loaded
- Verify progress bar updates correctly during delete operations
- Verify confirmation dialogs appear for destructive operations

## AJAX Handlers

The plugin registers the following AJAX actions:

1. **studiou_wcpcm_import** - Handles CSV import
2. **studiou_wcpcm_export** - Generates CSV export
3. **studiou_wcpcm_move_products** - Moves products between categories
4. **studiou_wcpcm_batch_description** - Updates descriptions for multiple categories
5. **studiou_wcpcm_delete_products** - Initial request to get product IDs for deletion
6. **studiou_wcpcm_delete_products_batch** - Processes product deletion in batches

All AJAX handlers include:
- Nonce verification (`studiou-wcpcm-nonce`)
- Permission checks (`manage_woocommerce` capability)
- Output buffer cleaning to prevent JSON corruption
- Comprehensive error logging when WP_DEBUG is enabled