magdev/wc-composable-product
1
Fork 0
Code Issues Pull Requests Activity

Update CLAUDE.md with session learnings and project documentation

Browse Source 
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>
This commit is contained in:
Marco Grätsch
2025-12-31 00:41:38 +01:00
parent 1edb0be3d9
commit 2828f1ab25
1 changed files with 200 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

203
CLAUDE.md
View File

@@ -41,9 +41,15 @@ _e('Text to translate', 'wc-composable-product')
Text domain: `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` - German (Germany, formal)
- `de_DE_informal` - German (Germany, informal "du") - `de_DE_informal` - German (Germany, informal "du")
- `de_CH` - German (Switzerland, formal "Sie") - `de_CH` - German (Switzerland, formal "Sie")
@@ -51,7 +57,7 @@ Text domain: `wc-composable-product`
- `fr_CH` - French (Switzerland) - `fr_CH` - French (Switzerland)
- `it_CH` - Italian (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 ### Create releases
@@ -87,6 +93,197 @@ Note: Swiss locales use CHF currency formatting in examples (e.g., "CHF 50.-")
- Previous releases - Previous releases
- `composer.lock` (but `vendor/` is included) - `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! Always refer to this document when starting work on this project. Good luck!