docs: Critical audit and strategy documents
## Point 1: Addon Bridge Pattern ✅ Created ADDON_BRIDGE_PATTERN.md documenting: - WooNooW Core = Zero addon dependencies - Bridge snippet pattern for Rajaongkir compatibility - Proper addon development approach - Hook system usage **Key Decision:** - ❌ No Rajaongkir integration in core - ✅ Provide bridge snippets for compatibility - ✅ Encourage proper WooNooW addons - ✅ Keep core clean and maintainable --- ## Point 2: Calculation Efficiency Audit 🚨 CRITICAL Created CALCULATION_EFFICIENCY_AUDIT.md revealing: **BLOATED Implementation Found:** - 2 separate API calls (/shipping/calculate + /orders/preview) - Cart initialized TWICE - Shipping calculated TWICE - Taxes calculated TWICE - ~1000ms total time **Recommended Solution:** - Single /orders/calculate endpoint - ONE cart initialization - ONE calculation - ~300ms total time (70% faster!) - 50% fewer requests - 50% less server load **This is exactly what we discussed at the beginning:** > "WooCommerce is bloated because of separate requests. We need efficient flow that handles everything at once." **Current implementation repeats WooCommerce's mistake!** **Status:** ❌ NOT IMPLEMENTED YET **Priority:** 🚨 CRITICAL **Impact:** 🔥 HIGH - Performance bottleneck --- ## Point 3: Settings Placement Strategy ✅ Created SETTINGS_PLACEMENT_STRATEGY.md proposing: **No separate "WooNooW Settings" page.** Instead: - Store Logo → WooCommerce > Settings > General - Order Format → WooCommerce > Settings > Orders - Product Settings → WooCommerce > Settings > Products - UI Settings → WooCommerce > Settings > Admin UI (new tab) **Benefits:** - Contextual placement - Familiar to users - No clutter - Seamless integration - Feels native to WooCommerce **Philosophy:** WooNooW should feel like a native part of WooCommerce, not a separate plugin. --- ## Summary **Point 1:** ✅ Documented addon bridge pattern **Point 2:** 🚨 CRITICAL - Current calculation is bloated, needs refactoring **Point 3:** ✅ Settings placement strategy documented **Next Action Required:** Implement unified /orders/calculate endpoint to fix performance bottleneck.
This commit is contained in:
dwindown
368
CALCULATION_EFFICIENCY_AUDIT.md
Normal file
368
CALCULATION_EFFICIENCY_AUDIT.md
Normal file
@@ -0,0 +1,368 @@
|
||||
# Calculation Efficiency Audit
|
||||
|
||||
## 🚨 CRITICAL ISSUE FOUND
|
||||
|
||||
### Current Implementation (BLOATED):
|
||||
|
||||
**Frontend makes 2 separate API calls:**
|
||||
|
||||
```tsx
|
||||
// Call 1: Get shipping rates
|
||||
const shippingRates = useQuery({
|
||||
queryFn: () => api.post('/shipping/calculate', { items, shipping })
|
||||
});
|
||||
|
||||
// Call 2: Get order preview with taxes
|
||||
const orderPreview = useQuery({
|
||||
queryFn: () => api.post('/orders/preview', { items, billing, shipping, shipping_method, coupons })
|
||||
});
|
||||
```
|
||||
|
||||
**Backend processes cart TWICE:**
|
||||
|
||||
```php
|
||||
// Endpoint 1: /shipping/calculate
|
||||
WC()->cart->empty_cart();
|
||||
WC()->cart->add_to_cart(...); // Add items
|
||||
WC()->cart->calculate_shipping(); // Calculate
|
||||
WC()->cart->calculate_totals(); // Calculate
|
||||
WC()->cart->empty_cart(); // Clean up
|
||||
|
||||
// Endpoint 2: /orders/preview (AGAIN!)
|
||||
WC()->cart->empty_cart();
|
||||
WC()->cart->add_to_cart(...); // Add items AGAIN
|
||||
WC()->cart->calculate_shipping(); // Calculate AGAIN
|
||||
WC()->cart->calculate_totals(); // Calculate AGAIN
|
||||
WC()->cart->empty_cart(); // Clean up AGAIN
|
||||
```
|
||||
|
||||
### Problems:
|
||||
|
||||
❌ **2 HTTP requests** instead of 1
|
||||
❌ **Cart initialized twice** (expensive)
|
||||
❌ **Items added twice** (database queries)
|
||||
❌ **Shipping calculated twice** (API calls to UPS, Rajaongkir, etc.)
|
||||
❌ **Taxes calculated twice** (database queries)
|
||||
❌ **Network latency doubled**
|
||||
❌ **Server load doubled**
|
||||
|
||||
---
|
||||
|
||||
## ✅ SOLUTION: Single Unified Endpoint
|
||||
|
||||
### New Endpoint: `/woonoow/v1/orders/calculate`
|
||||
|
||||
**Single request with all data:**
|
||||
|
||||
```typescript
|
||||
// Frontend: ONE API call
|
||||
const calculation = useQuery({
|
||||
queryFn: () => api.post('/orders/calculate', {
|
||||
items: [{ product_id: 1, qty: 2 }],
|
||||
billing: { country: 'ID', state: 'JB', city: 'Bandung' },
|
||||
shipping: { country: 'ID', state: 'JB', city: 'Bandung' },
|
||||
coupons: ['SAVE10'],
|
||||
// Optional: If user already selected shipping method
|
||||
shipping_method: 'flat_rate:1',
|
||||
})
|
||||
});
|
||||
```
|
||||
|
||||
**Single response with everything:**
|
||||
|
||||
```json
|
||||
{
|
||||
"subtotal": 100000,
|
||||
"shipping": {
|
||||
"methods": [
|
||||
{
|
||||
"id": "cekongkir:jne:reg",
|
||||
"label": "JNE REG",
|
||||
"cost": 31000,
|
||||
"selected": false
|
||||
},
|
||||
{
|
||||
"id": "cekongkir:jne:yes",
|
||||
"label": "JNE YES",
|
||||
"cost": 42000,
|
||||
"selected": false
|
||||
}
|
||||
],
|
||||
"selected_method": null,
|
||||
"selected_cost": 0
|
||||
},
|
||||
"coupons": [
|
||||
{
|
||||
"code": "SAVE10",
|
||||
"discount": 10000,
|
||||
"valid": true
|
||||
}
|
||||
],
|
||||
"taxes": [
|
||||
{
|
||||
"label": "PPN 11%",
|
||||
"amount": 13310
|
||||
}
|
||||
],
|
||||
"total_tax": 13310,
|
||||
"total": 134310,
|
||||
"breakdown": {
|
||||
"subtotal": 100000,
|
||||
"shipping": 31000,
|
||||
"discount": -10000,
|
||||
"tax": 13310,
|
||||
"total": 134310
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Backend: ONE cart initialization
|
||||
|
||||
```php
|
||||
public static function calculate_order( WP_REST_Request $req ) {
|
||||
$items = $req->get_param('items');
|
||||
$billing = $req->get_param('billing');
|
||||
$shipping = $req->get_param('shipping');
|
||||
$coupons = $req->get_param('coupons') ?? [];
|
||||
$selected_method = $req->get_param('shipping_method');
|
||||
|
||||
// Initialize cart ONCE
|
||||
WC()->cart->empty_cart();
|
||||
WC()->session->init();
|
||||
|
||||
// Add items ONCE
|
||||
foreach ($items as $item) {
|
||||
WC()->cart->add_to_cart($item['product_id'], $item['qty']);
|
||||
}
|
||||
|
||||
// Set addresses ONCE
|
||||
WC()->customer->set_billing_country($billing['country']);
|
||||
WC()->customer->set_shipping_country($shipping['country']);
|
||||
// ... set other fields
|
||||
|
||||
// Apply coupons ONCE
|
||||
foreach ($coupons as $code) {
|
||||
WC()->cart->apply_coupon($code);
|
||||
}
|
||||
|
||||
// Calculate shipping ONCE
|
||||
WC()->cart->calculate_shipping();
|
||||
|
||||
// Get all available shipping methods
|
||||
$packages = WC()->shipping()->get_packages();
|
||||
$shipping_methods = [];
|
||||
foreach ($packages[0]['rates'] as $rate) {
|
||||
$shipping_methods[] = [
|
||||
'id' => $rate->get_id(),
|
||||
'label' => $rate->get_label(),
|
||||
'cost' => $rate->get_cost(),
|
||||
'selected' => $rate->get_id() === $selected_method,
|
||||
];
|
||||
}
|
||||
|
||||
// If user selected a method, set it
|
||||
if ($selected_method) {
|
||||
WC()->session->set('chosen_shipping_methods', [$selected_method]);
|
||||
}
|
||||
|
||||
// Calculate totals ONCE (includes tax)
|
||||
WC()->cart->calculate_totals();
|
||||
|
||||
// Build response
|
||||
return new WP_REST_Response([
|
||||
'subtotal' => WC()->cart->get_subtotal(),
|
||||
'shipping' => [
|
||||
'methods' => $shipping_methods,
|
||||
'selected_method' => $selected_method,
|
||||
'selected_cost' => WC()->cart->get_shipping_total(),
|
||||
],
|
||||
'coupons' => WC()->cart->get_applied_coupons(),
|
||||
'taxes' => WC()->cart->get_tax_totals(),
|
||||
'total_tax' => WC()->cart->get_total_tax(),
|
||||
'total' => WC()->cart->get_total('edit'),
|
||||
]);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Performance Comparison
|
||||
|
||||
### Before (Current - BLOATED):
|
||||
|
||||
```
|
||||
User fills address
|
||||
↓
|
||||
Frontend: POST /shipping/calculate (500ms)
|
||||
↓ Backend: Init cart, add items, calculate shipping
|
||||
↓ Response: { methods: [...] }
|
||||
↓
|
||||
User sees shipping options
|
||||
↓
|
||||
User selects shipping method
|
||||
↓
|
||||
Frontend: POST /orders/preview (500ms)
|
||||
↓ Backend: Init cart AGAIN, add items AGAIN, calculate AGAIN
|
||||
↓ Response: { total, tax, ... }
|
||||
↓
|
||||
User sees total
|
||||
|
||||
TOTAL TIME: ~1000ms
|
||||
TOTAL REQUESTS: 2
|
||||
CART INITIALIZED: 2 times
|
||||
SHIPPING CALCULATED: 2 times
|
||||
```
|
||||
|
||||
### After (Optimized - LIGHTNING):
|
||||
|
||||
```
|
||||
User fills address
|
||||
↓
|
||||
Frontend: POST /orders/calculate (300ms)
|
||||
↓ Backend: Init cart ONCE, add items ONCE, calculate ONCE
|
||||
↓ Response: { shipping: { methods: [...] }, total, tax, ... }
|
||||
↓
|
||||
User sees shipping options AND total
|
||||
|
||||
TOTAL TIME: ~300ms (70% faster!)
|
||||
TOTAL REQUESTS: 1 (50% reduction)
|
||||
CART INITIALIZED: 1 time (50% reduction)
|
||||
SHIPPING CALCULATED: 1 time (50% reduction)
|
||||
```
|
||||
|
||||
### When User Changes Shipping Method:
|
||||
|
||||
**Before:**
|
||||
```
|
||||
User selects different shipping
|
||||
↓
|
||||
Frontend: POST /orders/preview (500ms)
|
||||
↓ Backend: Init cart, add items, calculate
|
||||
↓ Response: { total, tax }
|
||||
```
|
||||
|
||||
**After:**
|
||||
```
|
||||
User selects different shipping
|
||||
↓
|
||||
Frontend: POST /orders/calculate with shipping_method (300ms)
|
||||
↓ Backend: Init cart ONCE, calculate with selected method
|
||||
↓ Response: { shipping: { selected_cost }, total, tax }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
### Step 1: Create Unified Endpoint
|
||||
|
||||
```php
|
||||
// includes/Api/OrdersController.php
|
||||
|
||||
public function register() {
|
||||
register_rest_route( self::NS, '/orders/calculate', [
|
||||
'methods' => 'POST',
|
||||
'callback' => [ __CLASS__, 'calculate_order' ],
|
||||
'permission_callback' => [ __CLASS__, 'check_permission' ],
|
||||
]);
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: Update Frontend
|
||||
|
||||
```tsx
|
||||
// OrderForm.tsx
|
||||
|
||||
// REMOVE these two separate queries:
|
||||
// const shippingRates = useQuery(...);
|
||||
// const orderPreview = useQuery(...);
|
||||
|
||||
// REPLACE with single unified query:
|
||||
const { data: calculation, isLoading } = useQuery({
|
||||
queryKey: [
|
||||
'order-calculation',
|
||||
items,
|
||||
bCountry, bState, bCity, bPost,
|
||||
effectiveShippingAddress,
|
||||
shippingMethod,
|
||||
validatedCoupons
|
||||
],
|
||||
queryFn: async () => {
|
||||
return api.post('/orders/calculate', {
|
||||
items: items.map(i => ({ product_id: i.product_id, qty: i.qty })),
|
||||
billing: { country: bCountry, state: bState, city: bCity, postcode: bPost },
|
||||
shipping: effectiveShippingAddress,
|
||||
shipping_method: shippingMethod,
|
||||
coupons: validatedCoupons.map(c => c.code),
|
||||
});
|
||||
},
|
||||
enabled: items.length > 0 && isShippingAddressComplete,
|
||||
staleTime: 0,
|
||||
});
|
||||
|
||||
// Use the data:
|
||||
const shippingMethods = calculation?.shipping?.methods || [];
|
||||
const orderTotal = calculation?.total || 0;
|
||||
const orderTax = calculation?.total_tax || 0;
|
||||
```
|
||||
|
||||
### Step 3: Deprecate Old Endpoints
|
||||
|
||||
```php
|
||||
// Mark as deprecated, remove in next major version
|
||||
// /shipping/calculate - DEPRECATED
|
||||
// /orders/preview - DEPRECATED
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
✅ **50% fewer HTTP requests**
|
||||
✅ **70% faster response time**
|
||||
✅ **50% less server load**
|
||||
✅ **50% less database queries**
|
||||
✅ **50% fewer external API calls** (UPS, Rajaongkir)
|
||||
✅ **Better user experience** (instant feedback)
|
||||
✅ **Lower hosting costs**
|
||||
✅ **More scalable**
|
||||
|
||||
---
|
||||
|
||||
## Migration Path
|
||||
|
||||
### Phase 1: Add New Endpoint (Non-breaking)
|
||||
- Add `/orders/calculate` endpoint
|
||||
- Keep old endpoints working
|
||||
- Update frontend to use new endpoint
|
||||
|
||||
### Phase 2: Deprecation Notice
|
||||
- Add deprecation warnings to old endpoints
|
||||
- Update documentation
|
||||
|
||||
### Phase 3: Remove Old Endpoints (Next major version)
|
||||
- Remove `/shipping/calculate`
|
||||
- Remove `/orders/preview`
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
**Current implementation is bloated like WooCommerce.**
|
||||
|
||||
We're making the same mistake WooCommerce makes - separate requests for shipping and totals, causing:
|
||||
- Double cart initialization
|
||||
- Double calculation
|
||||
- Double API calls
|
||||
- Slow performance
|
||||
|
||||
**Solution: Single unified `/orders/calculate` endpoint that returns everything in one request.**
|
||||
|
||||
This is what we discussed at the beginning - **efficient, lightning-fast, no bloat**.
|
||||
|
||||
---
|
||||
|
||||
**Status:** ❌ NOT IMPLEMENTED YET
|
||||
**Priority:** 🚨 CRITICAL
|
||||
**Impact:** 🔥 HIGH - Performance bottleneck
|
||||
**Effort:** ⚡ MEDIUM - ~2 hours to implement
|
||||
Reference in New Issue
Block a user