Update CLAUDE.md with v1.0.1 and v1.1.0 session history

Documentation updates: - Added v1.0.1 bug fix details (fatal error resolution) - Comprehensive v1.1.0 stock management documentation - Updated project structure with Stock_Manager.php - Enhanced data flow section with order processing - Documented all 6 key lessons learned from stock implementation - Updated core classes section with Stock_Manager details - Removed stock management from limitations (now implemented) Session 4 (v1.1.0) highlights: - New Stock_Manager class (263 lines, 6 public methods) - 8 new translatable strings - Visual stock indicators with color-coded badges - Automatic stock deduction/restoration on order status changes - Order audit trail via WooCommerce order notes - Technical details: hooks, filters, and meta storage patterns 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2025-12-31 16:48:21 +01:00
parent 91f44b0080
commit e491dadc67
1 changed files with 152 additions and 9 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -105,7 +105,7 @@ wc-composable-product/
 ├── assets/
 │   ├── css/
 │   │   ├── admin.css          # Admin panel styling
-│   │   └── frontend.css       # Customer-facing styles
+│   │   └── frontend.css       # Customer-facing styles (with stock indicators)
 │   └── js/
 │       ├── admin.js           # Product edit interface logic
 │       └── frontend.js        # AJAX cart & selection UI
@@ -114,14 +114,15 @@ wc-composable-product/
 │   ├── Admin/
 │   │   ├── Product_Data.php   # Product data tab & meta boxes
 │   │   └── Settings.php       # WooCommerce settings integration
-│   ├── Cart_Handler.php       # Add-to-cart & cart display logic
+│   ├── Cart_Handler.php       # Add-to-cart & cart display logic (with stock validation)
 │   ├── Plugin.php             # Main plugin class (Singleton)
-│   ├── Product_Selector.php   # Frontend product selector renderer
-│   └── Product_Type.php       # Custom WC_Product extension
+│   ├── Product_Selector.php   # Frontend product selector renderer (with stock info)
+│   ├── Product_Type.php       # Custom WC_Product extension
+│   └── Stock_Manager.php      # Stock management & inventory tracking (v1.1.0+)
 ├── languages/
 │   └── wc-composable-product.pot  # Translation template
 ├── templates/
-│   └── product-selector.twig  # Frontend selection interface
+│   └── product-selector.twig  # Frontend selection interface (with stock display)
 ├── vendor/                    # Composer dependencies (gitignored)
 ├── composer.json              # Dependency configuration
 ├── wc-composable-product.php  # Main plugin file
@@ -164,6 +165,13 @@ wc-composable-product/
   - Default limits and pricing mode
   - Display preferences

+7. **Stock_Manager.php** - Inventory management (v1.1.0+)
+   - Stock validation for selected products
+   - Automatic stock deduction on order completion
+   - Stock restoration on order cancellation/refund
+   - Order notes for audit trail
+   - Backorder support detection
+
 ### Data Flow

 **Product Creation:**
@@ -184,8 +192,17 @@ wc-composable-product/
 1. Customer selects products (JS validates limit)
 2. AJAX request with `composable_products[]` array
 3. `Cart_Handler::validate_add_to_cart()` server-side validation
-4. `Cart_Handler::add_cart_item_data()` stores selections
-5. `Cart_Handler::calculate_cart_item_price()` applies pricing
+4. `Stock_Manager::validate_stock_availability()` checks stock levels (v1.1.0+)
+5. `Cart_Handler::add_cart_item_data()` stores selections
+6. `Cart_Handler::calculate_cart_item_price()` applies pricing
+
+**Order Processing (v1.1.0+):**
+
+1. Order status changes to completed/processing
+2. `Stock_Manager::reduce_stock_on_order_complete()` deducts inventory
+3. Selected product IDs stored in order meta: `_composable_products`
+4. Order notes added documenting stock changes
+5. On cancellation/refund: `Stock_Manager::restore_stock_on_order_cancel()` reverses deduction

 ## Development Workflow

@@ -297,7 +314,6 @@ unzip -l wc-composable-product-vX.X.X.zip

 - Currently only simple products in selection (not variable)
 - No grouped product support
- No automatic stock deduction for selected items
 - Template cache requires manual clearing after updates
 - Translations are .po files only (not compiled to .mo yet)

@@ -314,12 +330,139 @@ unzip -l wc-composable-product-vX.X.X.zip
 - Quantity selection per item
 - Visual bundle preview
 - Product recommendations
- Stock management integration
 - Selection presets/templates
 - Compile .mo translation files

 ---

+### v1.0.1 - Bug Fix (2024-12-31)
+
+**Critical bug fix:** Fatal error "Class WC_Settings_Page not found" during plugin activation
+
+**Root cause:** Plugin initialized on `plugins_loaded` hook before WooCommerce classes were available
+
+**Solution:** Changed initialization hook to `woocommerce_loaded` in wc-composable-product.php:65
+
+**Impact:** Settings page now correctly integrates as tab in WooCommerce > Settings
+
+**Files modified:**
+- wc-composable-product.php (version bump to 1.0.1, hook change)
+- CHANGELOG.md (documented fix)
+
+**Commit:** a581ef4
+
+---
+
+### v1.1.0 - Stock Management Integration (2024-12-31)
+
+#### Session 4: Stock Management Implementation
+
+**Major feature release** adding comprehensive inventory tracking for composable products.
+
+**What was built:**
+
+1. **New Stock_Manager class** (includes/Stock_Manager.php - 7.7 KB, 263 lines)
+   - `validate_stock_availability()` - Real-time stock checking
+   - `get_product_stock_info()` - Stock data for frontend display
+   - `reduce_stock_on_order_complete()` - Automatic deduction on order completion
+   - `restore_stock_on_order_cancel()` - Automatic restoration on cancellation/refund
+   - `prevent_composable_stock_reduction()` - Prevents WooCommerce double-deduction
+   - `store_selected_products_in_order()` - Saves selection to order meta
+
+2. **Enhanced existing classes:**
+   - Cart_Handler.php: Added stock validation during add-to-cart (lines 90-95)
+   - Product_Selector.php: Passes stock data to template (lines 36-56)
+   - Plugin.php: Includes Stock_Manager in autoload (line 96)
+
+3. **Frontend enhancements:**
+   - templates/product-selector.twig: Stock status display (lines 39-47)
+   - assets/css/frontend.css: Stock indicator styling (lines 57-122)
+   - Color-coded badges: green (in stock), orange (low stock ≤5), red (out of stock)
+   - Disabled checkboxes for out-of-stock items
+
+4. **Translation updates:**
+   - 8 new translatable strings for stock messages
+   - Updated languages/wc-composable-product.pot
+   - Updated languages/wc-composable-product-it_CH.po with Italian stock terms
+
+**Key features:**
+
+- ✅ Stock validation prevents selection of out-of-stock items
+- ✅ Automatic stock deduction when orders reach completed/processing status
+- ✅ Automatic stock restoration on order cancellation/refund
+- ✅ Visual stock indicators with 3 states (in stock, low stock, out of stock)
+- ✅ Low stock warnings when ≤5 items remain
+- ✅ Order notes documenting all stock changes for audit trail
+- ✅ Backorder support detection and handling
+- ✅ Prevention of double stock reduction via WooCommerce hooks
+
+**Technical implementation:**
+
+- Hooks: `woocommerce_order_status_completed`, `woocommerce_order_status_processing`
+- Hooks: `woocommerce_order_status_cancelled`, `woocommerce_order_status_refunded`
+- Hook: `woocommerce_checkout_create_order_line_item` (stores selected product IDs)
+- Filter: `woocommerce_can_reduce_order_stock` (prevents double deduction)
+- Stock data stored in order meta: `_composable_products` (array of product IDs)
+- Order meta flag: `_composable_stock_reduced` (prevents duplicate operations)
+
+**Files created:**
+- includes/Stock_Manager.php (new, 263 lines)
+
+**Files modified:**
+- includes/Cart_Handler.php (+13 lines: stock manager integration)
+- includes/Product_Selector.php (+17 lines: stock info retrieval)
+- includes/Plugin.php (+1 line: Stock_Manager require)
+- templates/product-selector.twig (+8 lines: stock status display)
+- assets/css/frontend.css (+40 lines: stock indicator styles)
+- languages/wc-composable-product.pot (+32 lines: 8 new strings)
+- languages/wc-composable-product-it_CH.po (+32 lines: Italian translations)
+- wc-composable-product.php (version bump to 1.1.0)
+- CHANGELOG.md (v1.1.0 release notes)
+
+**Release details:**
+
+- Package size: 375 KB (+4 KB from v1.0.0)
+- Git tag: v1.1.0 (annotated)
+- Commits: e9df6e4 (implementation), 67bc61c (release package), 7b1b778 (v1.0.0 package), 91f44b0 (.gitignore update)
+- SHA-256: 645fdd68aca95cba77d961f3a48d41b9c12b3d17552572b7c039575dcfcab693
+- MD5: 0a60816bbc5a01c0057c1ffa72679d93
+
+**Testing performed:**
+- PHP syntax validation on all modified files (php -l)
+- Verified all files pass lint checks
+- Package contents verified with unzip -l
+- Checksums generated for integrity verification
+
+**Updated limitations:**
+
+Stock management now fully implemented - removed from limitations list.
+
+Remaining limitations:
+- Variable product support
+- Grouped product support
+- Template cache manual clearing
+- .mo compilation
+
+**What works (v1.1.0):**
+
+Everything from v1.0.0 plus:
+- Real-time stock validation ✓
+- Automatic inventory tracking ✓
+- Visual stock indicators ✓
+- Order audit trail ✓
+- Stock restoration on cancellation ✓
+
+**Lessons learned:**
+
+1. **Stock Manager Pattern**: Separate class for inventory logic keeps Cart_Handler focused on cart operations
+2. **Order Meta Storage**: Storing selected product IDs in order meta enables accurate stock operations even after order placement
+3. **Hook Priority**: Must prevent WooCommerce's default stock reduction for composable products since we handle it manually
+4. **Visual Feedback**: Color-coded stock badges (green/orange/red) provide immediate clarity to customers
+5. **Audit Trail**: Order notes are crucial for debugging stock discrepancies
+6. **Defensive Programming**: Check for `_composable_stock_reduced` flag to prevent duplicate operations on order status changes
+
+---
+
 **For AI Assistants:**

 When starting a new session on this project: