diff --git a/CLAUDE.md b/CLAUDE.md index 53054a3..a8d0f3c 100644 --- 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: