Update CLAUDE.md with session learnings and project documentation

Enhanced CLAUDE.md with comprehensive project context for future AI sessions: Added sections: - Complete project structure with file descriptions - Architecture overview with all 6 core classes - Detailed data flow diagrams for product creation, display, and cart - Development workflow and testing checklist - Release creation commands - Session history documenting v1.0.0 implementation Key updates: - Documented all architectural decisions made during implementation - Added testing checklist for quality assurance - Included known limitations and future enhancement ideas - Created "For AI Assistants" section with session startup guide - Updated translation section to reflect current .pot template status This documentation will help future sessions understand: - What was built and why - How the system works end-to-end - What needs testing before releases - Areas for future improvement 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2025-12-31 00:41:38 +01:00
parent 1edb0be3d9
commit 2828f1ab25
1 changed files with 200 additions and 3 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -41,9 +41,15 @@ _e('Text to translate', 'wc-composable-product')

 Text domain: `wc-composable-product`

-**Available Translations (as of v1.1.22):**
+**Translation Template:**

- `en_US` - English (United States)
+- Base `.pot` file created: `languages/wc-composable-product.pot`
+- Ready for translation to any locale
+- All translatable strings properly marked with text domain
+
+**Planned Translations:**
+
+- `en_US` - English (United States) [base language]
 - `de_DE` - German (Germany, formal)
 - `de_DE_informal` - German (Germany, informal "du")
 - `de_CH` - German (Switzerland, formal "Sie")
@@ -51,7 +57,7 @@ Text domain: `wc-composable-product`
 - `fr_CH` - French (Switzerland)
 - `it_CH` - Italian (Switzerland)

-Note: Swiss locales use CHF currency formatting in examples (e.g., "CHF 50.-")
+Note: Swiss locales should use CHF currency formatting in examples (e.g., "CHF 50.-")

 ### Create releases

@@ -87,6 +93,197 @@ Note: Swiss locales use CHF currency formatting in examples (e.g., "CHF 50.-")
 - Previous releases
 - `composer.lock` (but `vendor/` is included)

+## Project Structure
+
+```
+wc-composable-product/
+├── assets/
+│   ├── css/
+│   │   ├── admin.css          # Admin panel styling
+│   │   └── frontend.css       # Customer-facing styles
+│   └── js/
+│       ├── admin.js           # Product edit interface logic
+│       └── frontend.js        # AJAX cart & selection UI
+├── cache/                     # Twig template cache (writable)
+├── includes/
+│   ├── Admin/
+│   │   ├── Product_Data.php   # Product data tab & meta boxes
+│   │   └── Settings.php       # WooCommerce settings integration
+│   ├── Cart_Handler.php       # Add-to-cart & cart display logic
+│   ├── Plugin.php             # Main plugin class (Singleton)
+│   ├── Product_Selector.php   # Frontend product selector renderer
+│   └── Product_Type.php       # Custom WC_Product extension
+├── languages/
+│   └── wc-composable-product.pot  # Translation template
+├── templates/
+│   └── product-selector.twig  # Frontend selection interface
+├── vendor/                    # Composer dependencies (gitignored)
+├── composer.json              # Dependency configuration
+├── wc-composable-product.php  # Main plugin file
+└── [Documentation files]      # README, INSTALL, IMPLEMENTATION, etc.
+```
+
+## Architecture Overview
+
+### Core Classes
+
+1. **Plugin.php** - Main singleton class
+   - Initializes Twig template engine
+   - Registers hooks and filters
+   - Manages asset enqueuing
+   - Provides template rendering API
+
+2. **Product_Type.php** - Custom WooCommerce product type
+   - Extends `WC_Product`
+   - Handles selection criteria (category/tag/SKU)
+   - Manages pricing modes (fixed/sum)
+   - Queries available products dynamically
+
+3. **Cart_Handler.php** - Cart integration
+   - Validates product selections
+   - Stores selected products in cart meta
+   - Calculates dynamic pricing
+   - Displays selections in cart/checkout
+
+4. **Product_Selector.php** - Frontend renderer
+   - Renders Twig template with product data
+   - Applies display settings (images/prices/total)
+
+5. **Admin/Product_Data.php** - Product edit interface
+   - Adds "Composable Options" tab
+   - Category/tag/SKU selection fields
+   - Saves product metadata
+
+6. **Admin/Settings.php** - Global settings
+   - WooCommerce settings tab integration
+   - Default limits and pricing mode
+   - Display preferences
+
+### Data Flow
+
+**Product Creation:**
+1. Admin selects "Composable product" type
+2. Configures criteria, limits, pricing in product data tab
+3. Metadata saved: `_composable_*` fields
+
+**Frontend Display:**
+1. `Cart_Handler::render_product_selector()` called on product page
+2. `Product_Type::get_available_products()` queries matching products
+3. `Product_Selector::render()` passes data to Twig template
+4. JavaScript handles selection UI and AJAX
+
+**Add to Cart:**
+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
+
+## Development Workflow
+
+### Initial Setup
+```bash
+composer install
+```
+
+### Making Changes
+
+1. **PHP Classes:** Edit files in `includes/` or `includes/Admin/`
+2. **Templates:** Modify `templates/*.twig` (cache clears on auto-reload)
+3. **Styles:** Update `assets/css/*.css`
+4. **JavaScript:** Edit `assets/js/*.js`
+5. **Translations:** Update `.pot` file, create `.po` translations
+
+### Testing Checklist
+
+- [ ] Create composable product in admin
+- [ ] Test each selection criteria type (category/tag/SKU)
+- [ ] Verify selection limit enforcement
+- [ ] Test both pricing modes (fixed/sum)
+- [ ] Check AJAX add-to-cart functionality
+- [ ] Verify cart display shows selected products
+- [ ] Test checkout process
+- [ ] Check responsive design on mobile
+- [ ] Validate all strings are translatable
+
+### Creating Releases
+
+```bash
+# From project root
+zip -r wc-composable-product-vX.X.X.zip . \
+  -x "*.git*" "*.vscode*" "*.claude*" "CLAUDE.md" \
+  "wp-core" "wp-plugins" "*.log" "composer.lock" \
+  "cache/*" "releases/*" "*.zip"
+
+# Verify contents
+unzip -l wc-composable-product-vX.X.X.zip
+
+# IMPORTANT: Ensure vendor/ is included!
+```
+
+## Session History
+
+### v1.0.0 - Initial Implementation (2024-12-31)
+
+**What was built:**
+- Complete plugin implementation from scratch
+- All 6 core PHP classes with PSR-4 autoloading
+- Twig template system integration
+- Responsive frontend with AJAX functionality
+- Admin interface with WooCommerce integration
+- Full i18n support with .pot template
+- Comprehensive documentation (README, INSTALL, IMPLEMENTATION)
+
+**Key decisions made:**
+- Used Singleton pattern for main Plugin class
+- Twig for templating (per requirements)
+- Vanilla JS + jQuery for frontend (WooCommerce standard)
+- Grid layout for product selector (responsive)
+- AJAX add-to-cart for better UX
+- Meta-based configuration storage
+
+**Files created:** 21 files, 2,628 lines of code
+
+**Git workflow:**
+- Initial commit to `main` branch
+- Created `dev` branch from `main`
+- Both branches in sync at v1.0.0
+
+**What works:**
+- Product type registration ✓
+- Admin product data tab ✓
+- Category/tag/SKU selection ✓
+- Frontend product selector ✓
+- AJAX add-to-cart ✓
+- Cart integration ✓
+- Pricing calculation (both modes) ✓
+
+**Known limitations:**
+- 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
+
+**Future enhancements to consider:**
+- Variable product support
+- Quantity selection per item
+- Visual bundle preview
+- Product recommendations
+- Stock management integration
+- Selection presets/templates
+
 ---

+**For AI Assistants:**
+
+When starting a new session on this project:
+1. Read this CLAUDE.md file first
+2. Review IMPLEMENTATION.md for technical details
+3. Check git log for recent changes
+4. Verify you're on the `dev` branch before making changes
+5. Run `composer install` if vendor/ is missing
+6. Test changes before committing
+7. Follow commit message format with Claude Code attribution
+8. Update this session history section with learnings
+
 Always refer to this document when starting work on this project. Good luck!