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
325
ADDON_BRIDGE_PATTERN.md
Normal file
325
ADDON_BRIDGE_PATTERN.md
Normal file
@@ -0,0 +1,325 @@
|
||||
# Addon Bridge Pattern - Rajaongkir Example
|
||||
|
||||
## Philosophy
|
||||
|
||||
**WooNooW Core = Zero Addon Dependencies**
|
||||
|
||||
We don't integrate specific addons into WooNooW core. Instead, we provide:
|
||||
1. **Hook system** for addons to extend functionality
|
||||
2. **Bridge snippets** for compatibility with existing plugins
|
||||
3. **Addon development guide** for building proper WooNooW addons
|
||||
|
||||
---
|
||||
|
||||
## Problem: Rajaongkir Plugin
|
||||
|
||||
Rajaongkir is a WooCommerce plugin that:
|
||||
- Removes standard address fields (city, state)
|
||||
- Adds custom destination dropdown
|
||||
- Stores data in WooCommerce session
|
||||
- Works on WooCommerce checkout page
|
||||
|
||||
**It doesn't work with WooNooW OrderForm because:**
|
||||
- OrderForm uses standard WooCommerce fields
|
||||
- Rajaongkir expects session-based destination
|
||||
- No destination = No shipping calculation
|
||||
|
||||
---
|
||||
|
||||
## Solution: Bridge Snippet (Not Core Integration!)
|
||||
|
||||
### Option A: Standalone Bridge Plugin
|
||||
|
||||
Create a tiny bridge plugin that makes Rajaongkir work with WooNooW:
|
||||
|
||||
```php
|
||||
<?php
|
||||
/**
|
||||
* Plugin Name: WooNooW Rajaongkir Bridge
|
||||
* Description: Makes Rajaongkir plugin work with WooNooW OrderForm
|
||||
* Version: 1.0.0
|
||||
* Requires: WooNooW, Rajaongkir Official
|
||||
*/
|
||||
|
||||
// Hook into WooNooW's shipping calculation
|
||||
add_filter('woonoow_before_shipping_calculate', function($shipping_data) {
|
||||
// If Indonesia and has city, convert to Rajaongkir destination
|
||||
if ($shipping_data['country'] === 'ID' && !empty($shipping_data['city'])) {
|
||||
// Search Rajaongkir API for destination
|
||||
$api = Cekongkir_API::get_instance();
|
||||
$results = $api->search_destination_api($shipping_data['city']);
|
||||
|
||||
if (!empty($results[0])) {
|
||||
// Set Rajaongkir session data
|
||||
WC()->session->set('selected_destination_id', $results[0]['id']);
|
||||
WC()->session->set('selected_destination_label', $results[0]['text']);
|
||||
}
|
||||
}
|
||||
|
||||
return $shipping_data;
|
||||
});
|
||||
|
||||
// Add Rajaongkir destination field to OrderForm via hook system
|
||||
add_action('wp_enqueue_scripts', function() {
|
||||
if (!is_admin()) return;
|
||||
|
||||
wp_enqueue_script(
|
||||
'woonoow-rajaongkir-bridge',
|
||||
plugin_dir_url(__FILE__) . 'dist/bridge.js',
|
||||
['woonoow-admin'],
|
||||
'1.0.0',
|
||||
true
|
||||
);
|
||||
});
|
||||
```
|
||||
|
||||
**Frontend (bridge.js):**
|
||||
|
||||
```typescript
|
||||
import { addonLoader, addFilter } from '@woonoow/hooks';
|
||||
|
||||
addonLoader.register({
|
||||
id: 'rajaongkir-bridge',
|
||||
name: 'Rajaongkir Bridge',
|
||||
version: '1.0.0',
|
||||
init: () => {
|
||||
// Add destination search field after shipping address
|
||||
addFilter('woonoow_order_form_after_shipping', (content, formData, setFormData) => {
|
||||
// Only for Indonesia
|
||||
if (formData.shipping?.country !== 'ID') return content;
|
||||
|
||||
return (
|
||||
<>
|
||||
{content}
|
||||
<div className="border rounded-lg p-4 mt-4">
|
||||
<h3 className="font-medium mb-3">📍 Shipping Destination</h3>
|
||||
<RajaongkirDestinationSearch
|
||||
value={formData.shipping?.destination_id}
|
||||
onChange={(id, label) => {
|
||||
setFormData({
|
||||
...formData,
|
||||
shipping: {
|
||||
...formData.shipping,
|
||||
destination_id: id,
|
||||
destination_label: label,
|
||||
}
|
||||
});
|
||||
}}
|
||||
/>
|
||||
</div>
|
||||
</>
|
||||
);
|
||||
});
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Option B: Code Snippet (No Plugin)
|
||||
|
||||
For users who don't want a separate plugin, provide a code snippet:
|
||||
|
||||
```php
|
||||
// Add to theme's functions.php or custom plugin
|
||||
|
||||
// Bridge Rajaongkir with WooNooW
|
||||
add_filter('woonoow_shipping_data', function($data) {
|
||||
if ($data['country'] === 'ID' && !empty($data['city'])) {
|
||||
// Auto-search and set destination
|
||||
$api = Cekongkir_API::get_instance();
|
||||
$results = $api->search_destination_api($data['city']);
|
||||
if (!empty($results[0])) {
|
||||
WC()->session->set('selected_destination_id', $results[0]['id']);
|
||||
}
|
||||
}
|
||||
return $data;
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Proper Solution: Build WooNooW Addon
|
||||
|
||||
Instead of bridging Rajaongkir, build a proper WooNooW addon:
|
||||
|
||||
**WooNooW Indonesia Shipping Addon**
|
||||
|
||||
```php
|
||||
<?php
|
||||
/**
|
||||
* Plugin Name: WooNooW Indonesia Shipping
|
||||
* Description: Indonesia shipping with Rajaongkir API
|
||||
* Version: 1.0.0
|
||||
* Requires: WooNooW 1.0.0+
|
||||
*/
|
||||
|
||||
// Register addon
|
||||
add_filter('woonoow/addon_registry', function($addons) {
|
||||
$addons['indonesia-shipping'] = [
|
||||
'id' => 'indonesia-shipping',
|
||||
'name' => 'Indonesia Shipping',
|
||||
'version' => '1.0.0',
|
||||
'spa_bundle' => plugin_dir_url(__FILE__) . 'dist/addon.js',
|
||||
'dependencies' => ['woocommerce' => '8.0'],
|
||||
];
|
||||
return $addons;
|
||||
});
|
||||
|
||||
// Add API endpoints
|
||||
add_action('rest_api_init', function() {
|
||||
register_rest_route('woonoow/v1', '/indonesia/search-destination', [
|
||||
'methods' => 'GET',
|
||||
'callback' => function($req) {
|
||||
$query = $req->get_param('query');
|
||||
$api = new RajaongkirAPI(get_option('rajaongkir_api_key'));
|
||||
return $api->searchDestination($query);
|
||||
},
|
||||
]);
|
||||
|
||||
register_rest_route('woonoow/v1', '/indonesia/calculate-shipping', [
|
||||
'methods' => 'POST',
|
||||
'callback' => function($req) {
|
||||
$origin = $req->get_param('origin');
|
||||
$destination = $req->get_param('destination');
|
||||
$weight = $req->get_param('weight');
|
||||
|
||||
$api = new RajaongkirAPI(get_option('rajaongkir_api_key'));
|
||||
return $api->calculateShipping($origin, $destination, $weight);
|
||||
},
|
||||
]);
|
||||
});
|
||||
```
|
||||
|
||||
**Frontend:**
|
||||
|
||||
```typescript
|
||||
// dist/addon.ts
|
||||
|
||||
import { addonLoader, addFilter } from '@woonoow/hooks';
|
||||
import { DestinationSearch } from './components/DestinationSearch';
|
||||
|
||||
addonLoader.register({
|
||||
id: 'indonesia-shipping',
|
||||
name: 'Indonesia Shipping',
|
||||
version: '1.0.0',
|
||||
init: () => {
|
||||
// Add destination field
|
||||
addFilter('woonoow_order_form_after_shipping', (content, formData, setFormData) => {
|
||||
if (formData.shipping?.country !== 'ID') return content;
|
||||
|
||||
return (
|
||||
<>
|
||||
{content}
|
||||
<DestinationSearch
|
||||
value={formData.shipping?.destination_id}
|
||||
onChange={(id, label) => {
|
||||
setFormData({
|
||||
...formData,
|
||||
shipping: { ...formData.shipping, destination_id: id, destination_label: label }
|
||||
});
|
||||
}}
|
||||
/>
|
||||
</>
|
||||
);
|
||||
});
|
||||
|
||||
// Add validation
|
||||
addFilter('woonoow_order_form_validation', (errors, formData) => {
|
||||
if (formData.shipping?.country === 'ID' && !formData.shipping?.destination_id) {
|
||||
errors.destination = 'Please select shipping destination';
|
||||
}
|
||||
return errors;
|
||||
});
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Comparison
|
||||
|
||||
### Bridge Snippet (Quick Fix)
|
||||
✅ Works immediately
|
||||
✅ No new plugin needed
|
||||
✅ Minimal code
|
||||
❌ Depends on Rajaongkir plugin
|
||||
❌ Limited features
|
||||
❌ Not ideal UX
|
||||
|
||||
### Proper WooNooW Addon (Best Practice)
|
||||
✅ Native WooNooW integration
|
||||
✅ Better UX
|
||||
✅ More features
|
||||
✅ Independent of Rajaongkir plugin
|
||||
✅ Can use any shipping API
|
||||
❌ More development effort
|
||||
❌ Separate plugin to maintain
|
||||
|
||||
---
|
||||
|
||||
## Recommendation
|
||||
|
||||
**For WooNooW Core:**
|
||||
- ❌ Don't integrate Rajaongkir
|
||||
- ✅ Provide hook system
|
||||
- ✅ Document bridge pattern
|
||||
- ✅ Provide code snippets
|
||||
|
||||
**For Users:**
|
||||
- **Quick fix:** Use bridge snippet
|
||||
- **Best practice:** Build proper addon or use community addon
|
||||
|
||||
**For Community:**
|
||||
- Build "WooNooW Indonesia Shipping" addon
|
||||
- Publish on WordPress.org
|
||||
- Support Rajaongkir, Biteship, and other Indonesian shipping APIs
|
||||
|
||||
---
|
||||
|
||||
## Hook Points Needed in WooNooW Core
|
||||
|
||||
To support addons like this, WooNooW core should provide:
|
||||
|
||||
```php
|
||||
// Before shipping calculation
|
||||
apply_filters('woonoow_before_shipping_calculate', $shipping_data);
|
||||
|
||||
// After shipping calculation
|
||||
apply_filters('woonoow_after_shipping_calculate', $rates, $shipping_data);
|
||||
|
||||
// Modify shipping data
|
||||
apply_filters('woonoow_shipping_data', $data);
|
||||
```
|
||||
|
||||
```typescript
|
||||
// Frontend hooks
|
||||
'woonoow_order_form_after_shipping'
|
||||
'woonoow_order_form_shipping_fields'
|
||||
'woonoow_order_form_validation'
|
||||
'woonoow_order_form_submit'
|
||||
```
|
||||
|
||||
**These hooks already exist in our addon system!**
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
**WooNooW Core = Zero addon dependencies**
|
||||
|
||||
Instead of integrating Rajaongkir into core:
|
||||
1. Provide hook system ✅ (Already done)
|
||||
2. Document bridge pattern ✅ (This document)
|
||||
3. Encourage community addons ✅
|
||||
|
||||
This keeps WooNooW core:
|
||||
- Clean
|
||||
- Maintainable
|
||||
- Flexible
|
||||
- Extensible
|
||||
|
||||
Users can choose:
|
||||
- Bridge snippet (quick fix)
|
||||
- Proper addon (best practice)
|
||||
- Build their own
|
||||
|
||||
**No bloat in core!**
|
||||
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
|
||||
380
SETTINGS_PLACEMENT_STRATEGY.md
Normal file
380
SETTINGS_PLACEMENT_STRATEGY.md
Normal file
@@ -0,0 +1,380 @@
|
||||
# WooNooW Settings Placement Strategy
|
||||
|
||||
## Philosophy
|
||||
|
||||
**No separate "WooNooW Settings" page needed.**
|
||||
|
||||
Instead, integrate WooNooW settings seamlessly into existing WooCommerce/WordPress settings pages by context.
|
||||
|
||||
---
|
||||
|
||||
## Current WooCommerce Settings Structure
|
||||
|
||||
```
|
||||
WooCommerce > Settings
|
||||
├── General
|
||||
│ ├── Store Address
|
||||
│ ├── Selling Location
|
||||
│ ├── Currency
|
||||
│ └── ...
|
||||
├── Products
|
||||
│ ├── General
|
||||
│ ├── Inventory
|
||||
│ └── ...
|
||||
├── Tax
|
||||
│ ├── Tax Options
|
||||
│ └── Standard Rates
|
||||
├── Shipping
|
||||
│ ├── Shipping Zones
|
||||
│ └── Shipping Options
|
||||
└── ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## WooNooW Settings Integration
|
||||
|
||||
### 1. Store Identity Settings
|
||||
|
||||
**Location:** `WooCommerce > Settings > General` (or new "Store Details" tab)
|
||||
|
||||
**WooNooW Fields:**
|
||||
- ✅ Store Logo (upload)
|
||||
- ✅ Store Icon/Favicon
|
||||
- ✅ Brand Colors (primary, secondary)
|
||||
- ✅ Store Tagline
|
||||
|
||||
**Why here?**
|
||||
- Related to store identity
|
||||
- Used across admin and frontend
|
||||
- Makes sense with existing "Store Address" fields
|
||||
|
||||
**Implementation:**
|
||||
```php
|
||||
add_filter('woocommerce_general_settings', function($settings) {
|
||||
$woonoow_settings = [
|
||||
[
|
||||
'title' => __('Store Identity', 'woonoow'),
|
||||
'type' => 'title',
|
||||
'desc' => __('Customize your store branding', 'woonoow'),
|
||||
'id' => 'woonoow_store_identity',
|
||||
],
|
||||
[
|
||||
'title' => __('Store Logo', 'woonoow'),
|
||||
'type' => 'text',
|
||||
'desc' => __('Upload your store logo', 'woonoow'),
|
||||
'id' => 'woonoow_store_logo',
|
||||
'custom_attributes' => ['data-upload' => 'image'],
|
||||
],
|
||||
[
|
||||
'title' => __('Primary Color', 'woonoow'),
|
||||
'type' => 'color',
|
||||
'id' => 'woonoow_primary_color',
|
||||
'default' => '#3b82f6',
|
||||
],
|
||||
[
|
||||
'type' => 'sectionend',
|
||||
'id' => 'woonoow_store_identity',
|
||||
],
|
||||
];
|
||||
|
||||
return array_merge($settings, $woonoow_settings);
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Order Settings
|
||||
|
||||
**Location:** `WooCommerce > Settings > General` or new "Orders" tab
|
||||
|
||||
**WooNooW Fields:**
|
||||
- ✅ Default order status
|
||||
- ✅ Order number format
|
||||
- ✅ Enable order notes
|
||||
- ✅ Auto-complete virtual orders
|
||||
|
||||
**Why here?**
|
||||
- Order-specific settings
|
||||
- Used in OrderForm and order processing
|
||||
- Contextually related
|
||||
|
||||
---
|
||||
|
||||
### 3. Product Settings
|
||||
|
||||
**Location:** `WooCommerce > Settings > Products`
|
||||
|
||||
**WooNooW Fields:**
|
||||
- ✅ Enable quick edit
|
||||
- ✅ Default product type
|
||||
- ✅ Enable bulk actions
|
||||
- ✅ Product image sizes
|
||||
|
||||
**Why here?**
|
||||
- Product-specific settings
|
||||
- Used in ProductForm
|
||||
- Already in Products context
|
||||
|
||||
---
|
||||
|
||||
### 4. UI/UX Settings
|
||||
|
||||
**Location:** New tab `WooCommerce > Settings > Admin UI` or `WooNooW`
|
||||
|
||||
**WooNooW Fields:**
|
||||
- ✅ Enable/disable SPA mode
|
||||
- ✅ Theme (light/dark/auto)
|
||||
- ✅ Sidebar collapsed by default
|
||||
- ✅ Items per page
|
||||
- ✅ Date format preference
|
||||
|
||||
**Why separate tab?**
|
||||
- WooNooW-specific features
|
||||
- Not related to store operations
|
||||
- Admin experience customization
|
||||
|
||||
**Implementation:**
|
||||
```php
|
||||
add_filter('woocommerce_settings_tabs_array', function($tabs) {
|
||||
$tabs['woonoow'] = __('Admin UI', 'woonoow');
|
||||
return $tabs;
|
||||
}, 50);
|
||||
|
||||
add_action('woocommerce_settings_woonoow', function() {
|
||||
woocommerce_admin_fields([
|
||||
[
|
||||
'title' => __('WooNooW Admin Settings', 'woonoow'),
|
||||
'type' => 'title',
|
||||
'desc' => __('Customize your admin experience', 'woonoow'),
|
||||
],
|
||||
[
|
||||
'title' => __('Enable SPA Mode', 'woonoow'),
|
||||
'type' => 'checkbox',
|
||||
'desc' => __('Use single-page application for faster navigation', 'woonoow'),
|
||||
'id' => 'woonoow_enable_spa',
|
||||
'default' => 'yes',
|
||||
],
|
||||
[
|
||||
'title' => __('Theme', 'woonoow'),
|
||||
'type' => 'select',
|
||||
'options' => [
|
||||
'light' => __('Light', 'woonoow'),
|
||||
'dark' => __('Dark', 'woonoow'),
|
||||
'auto' => __('Auto (System)', 'woonoow'),
|
||||
],
|
||||
'id' => 'woonoow_theme',
|
||||
'default' => 'auto',
|
||||
],
|
||||
]);
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Settings Organization
|
||||
|
||||
### By Context (Recommended):
|
||||
|
||||
```
|
||||
WooCommerce > Settings > General
|
||||
└── Store Identity (WooNooW)
|
||||
├── Store Logo
|
||||
├── Brand Colors
|
||||
└── ...
|
||||
|
||||
WooCommerce > Settings > Products
|
||||
└── Product Management (WooNooW)
|
||||
├── Quick Edit
|
||||
├── Bulk Actions
|
||||
└── ...
|
||||
|
||||
WooCommerce > Settings > Orders
|
||||
└── Order Processing (WooNooW)
|
||||
├── Order Number Format
|
||||
├── Default Status
|
||||
└── ...
|
||||
|
||||
WooCommerce > Settings > Admin UI (New Tab)
|
||||
└── WooNooW Settings
|
||||
├── SPA Mode
|
||||
├── Theme
|
||||
├── UI Preferences
|
||||
└── ...
|
||||
```
|
||||
|
||||
### Benefits:
|
||||
|
||||
✅ **Contextual** - Settings appear where they're relevant
|
||||
✅ **Familiar** - Uses existing WooCommerce settings structure
|
||||
✅ **No clutter** - No separate "WooNooW Settings" menu
|
||||
✅ **Intuitive** - Users find settings where they expect them
|
||||
✅ **Seamless** - Feels like native WooCommerce
|
||||
|
||||
---
|
||||
|
||||
## Implementation Strategy
|
||||
|
||||
### Phase 1: Integrate into Existing Tabs
|
||||
|
||||
```php
|
||||
// Store Identity → General tab
|
||||
add_filter('woocommerce_general_settings', 'woonoow_add_store_identity_settings');
|
||||
|
||||
// Product Settings → Products tab
|
||||
add_filter('woocommerce_product_settings', 'woonoow_add_product_settings');
|
||||
|
||||
// Order Settings → General tab or new Orders tab
|
||||
add_filter('woocommerce_general_settings', 'woonoow_add_order_settings');
|
||||
```
|
||||
|
||||
### Phase 2: Add WooNooW-Specific Tab (If Needed)
|
||||
|
||||
```php
|
||||
// Only for settings that don't fit elsewhere
|
||||
add_filter('woocommerce_settings_tabs_array', function($tabs) {
|
||||
$tabs['woonoow'] = __('Admin UI', 'woonoow');
|
||||
return $tabs;
|
||||
});
|
||||
```
|
||||
|
||||
### Phase 3: Settings API
|
||||
|
||||
Provide a clean API for addons to register settings:
|
||||
|
||||
```php
|
||||
// Addon can add settings to any tab
|
||||
WooNooW_Settings::add_field('general', [
|
||||
'id' => 'my_addon_setting',
|
||||
'title' => 'My Setting',
|
||||
'type' => 'text',
|
||||
]);
|
||||
|
||||
// Or create own section
|
||||
WooNooW_Settings::add_section('general', [
|
||||
'id' => 'my_addon_section',
|
||||
'title' => 'My Addon Settings',
|
||||
'fields' => [...],
|
||||
]);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Store Logo
|
||||
|
||||
**Bad (Separate Page):**
|
||||
```
|
||||
WooNooW > Settings > Store Logo
|
||||
```
|
||||
|
||||
**Good (Contextual):**
|
||||
```
|
||||
WooCommerce > Settings > General > Store Identity > Store Logo
|
||||
```
|
||||
|
||||
### Example 2: Order Number Format
|
||||
|
||||
**Bad (Separate Page):**
|
||||
```
|
||||
WooNooW > Settings > Order Number Format
|
||||
```
|
||||
|
||||
**Good (Contextual):**
|
||||
```
|
||||
WooCommerce > Settings > Orders > Order Number Format
|
||||
```
|
||||
|
||||
### Example 3: SPA Mode
|
||||
|
||||
**Acceptable (WooNooW-Specific):**
|
||||
```
|
||||
WooCommerce > Settings > Admin UI > Enable SPA Mode
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Settings Categories
|
||||
|
||||
### Store Settings (Contextual Integration)
|
||||
- Store Logo → `General`
|
||||
- Brand Colors → `General`
|
||||
- Currency Display → `General`
|
||||
- Tax Display → `Tax`
|
||||
- Shipping Display → `Shipping`
|
||||
|
||||
### Product Settings (Contextual Integration)
|
||||
- Default Product Type → `Products > General`
|
||||
- Quick Edit → `Products > General`
|
||||
- Inventory Settings → `Products > Inventory`
|
||||
|
||||
### Order Settings (Contextual Integration)
|
||||
- Order Number Format → `Orders` (new tab) or `General`
|
||||
- Default Status → `Orders`
|
||||
- Auto-complete → `Orders`
|
||||
|
||||
### Admin UI Settings (New Tab)
|
||||
- SPA Mode → `Admin UI`
|
||||
- Theme → `Admin UI`
|
||||
- Sidebar → `Admin UI`
|
||||
- Items per Page → `Admin UI`
|
||||
|
||||
---
|
||||
|
||||
## Migration from Current Settings
|
||||
|
||||
If WooNooW currently has a separate settings page:
|
||||
|
||||
### Step 1: Identify Settings
|
||||
```
|
||||
Current: WooNooW > Settings > All Settings
|
||||
```
|
||||
|
||||
### Step 2: Categorize
|
||||
```
|
||||
Store Logo → Move to General
|
||||
Order Format → Move to Orders
|
||||
SPA Mode → Move to Admin UI
|
||||
```
|
||||
|
||||
### Step 3: Migrate
|
||||
```php
|
||||
// Remove old settings page
|
||||
remove_menu_page('woonoow-settings');
|
||||
|
||||
// Add to WooCommerce settings
|
||||
add_filter('woocommerce_general_settings', ...);
|
||||
add_filter('woocommerce_settings_tabs_array', ...);
|
||||
```
|
||||
|
||||
### Step 4: Redirect
|
||||
```php
|
||||
// Redirect old URL to new location
|
||||
add_action('admin_init', function() {
|
||||
if (isset($_GET['page']) && $_GET['page'] === 'woonoow-settings') {
|
||||
wp_redirect(admin_url('admin.php?page=wc-settings&tab=general'));
|
||||
exit;
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
**No separate "WooNooW Settings" page needed.**
|
||||
|
||||
Instead:
|
||||
1. ✅ Integrate into existing WooCommerce settings tabs by context
|
||||
2. ✅ Add "Admin UI" tab for WooNooW-specific UI settings
|
||||
3. ✅ Provide settings API for addons
|
||||
4. ✅ Keep settings contextual and intuitive
|
||||
|
||||
**Result:**
|
||||
- Seamless integration
|
||||
- Better UX
|
||||
- No clutter
|
||||
- Familiar to users
|
||||
|
||||
**WooNooW feels like a native part of WooCommerce, not a separate plugin.**
|
||||
Reference in New Issue
Block a user