# CLAUDE.md - Studiou WC Free Photo Product

## Project Overview

WordPress/WooCommerce plugin called **studiou-wc-free-photo-product** (QDR - Studiou WC Free Photo Product) v1.0.0.
Allows publishing special variable products where customers upload custom raw images to be printed for a price.

## Initial Requirements

1. WP (6.9.4) / WooCommerce (10.6.2) plugin with variants and custom raw image upload for photo printing. Frontend shows product with upload box, preview, and variant table.
2. Product configuration area: Media Category for uploaded files, Maximum raw file size. Shortcode to embed product on any page.
3. Uploaded raw files stored in WP media library with a specific media category per product. Chunked upload to bypass PHP upload size limits. Media files linked with product.
4. Admin summary page: list of uploaded files, download as ZIP (bulk), order number, delete, change state (downloaded, ready, solved).
5. HPOS support and localization (English, Czech).

## Tech Stack

- PHP 8.2+, WordPress 6.9.4+, WooCommerce 10.0+
- jQuery for frontend/admin JS
- WordPress AJAX (admin-ajax.php) for all async operations
- Custom DB table via dbDelta for file tracking
- Custom taxonomy `studiou_media_category` on `attachment` post type

## Architecture

- Main class: `Studiou_WC_Free_Photo_Product` in root plugin file
- Constants prefix: `STUDIOU_WCFPP_`
- CSS class prefix: `studiou-fpp-`
- JS namespace: `studiouWcfppFront` (frontend), `studiouWcfpp` (admin)
- Nonces: `studiou-wcfpp-front-nonce` (frontend), `studiou-wcfpp-nonce` (admin)
- Text domain: `studiou-wc-free-photo-product`

## Key Classes

- `Studiou_WC_FPP_DB` - Custom table CRUD, media category taxonomy
- `Studiou_WC_FPP_Product` - WC product data tab, product meta
- `Studiou_WC_FPP_Upload` - Chunked upload AJAX, file assembly, attachment creation
- `Studiou_WC_FPP_Shortcode` - `[studiou_free_photo_product id="X"]`
- `Studiou_WC_FPP_Cart` - Cart item data, order item meta, order linking
- `Studiou_WC_FPP_Admin` - Summary page, status management, ZIP download

## Coding Conventions

- Follow patterns from sibling plugin `studiou-wc-product-cat-manage`
- All PHP files start with `if (!defined('WPINC')) { die; }`
- AJAX handlers: verify nonce, check capabilities, try/catch with WP_DEBUG logging
- Output buffer cleanup in AJAX handlers
- Use `wp_send_json_success` / `wp_send_json_error` for all AJAX responses
- All user-facing strings wrapped in `__()` or `esc_html_e()` with text domain
- Sanitize all inputs: `absint()`, `sanitize_text_field()`, `sanitize_file_name()`
- Escape all outputs: `esc_html()`, `esc_attr()`, `esc_url()`, `wp_kses_post()`

## Build / Deploy Notes

- Generate .mo from .po: `php languages/generate-mo.php` or `wp i18n make-mo languages/`
- Plugin creates DB table on activation via `register_activation_hook`
- Temp chunks stored in `wp-content/uploads/studiou-fpp-chunks/` (cleaned on deactivation)
- Assembled files stored in `wp-content/uploads/YYYY/MM/free-photo/`

## Version Bumping

When changing JS or CSS files, always bump the plugin version in the main PHP file header AND the `STUDIOU_WCFPP_VERSION` constant to bust browser cache.