docs: Add comprehensive settings tree implementation plan
This commit is contained in:
dwindown
550
SETTINGS_TREE_PLAN.md
Normal file
550
SETTINGS_TREE_PLAN.md
Normal file
@@ -0,0 +1,550 @@
|
|||||||
|
# WooNooW Settings Tree - Implementation Plan
|
||||||
|
|
||||||
|
## 📋 Overview
|
||||||
|
|
||||||
|
This document defines the complete settings structure for WooNooW Admin SPA, including what needs to be built, priorities, and implementation approach.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 Strategy: Option A - Everyday Use Dashboard
|
||||||
|
|
||||||
|
**Philosophy:**
|
||||||
|
- Focus on most-used settings (80/20 rule)
|
||||||
|
- Bridge to wp-admin for advanced/rarely-used features
|
||||||
|
- Extensible for 3rd party plugins
|
||||||
|
- Coexist with WooCommerce (no replacement)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🌲 Settings Tree Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
Settings
|
||||||
|
├── 🔧 WooNooW (Plugin Settings)
|
||||||
|
│ └── /settings
|
||||||
|
│
|
||||||
|
├── 🏪 General (Store Settings)
|
||||||
|
│ └── /settings/general
|
||||||
|
│
|
||||||
|
├── 💳 Payments (Payment Gateways)
|
||||||
|
│ └── /settings/payments
|
||||||
|
│
|
||||||
|
├── 📦 Shipping (Zones & Methods)
|
||||||
|
│ └── /settings/shipping
|
||||||
|
│
|
||||||
|
├── 📦 Products (Inventory & Downloads)
|
||||||
|
│ └── /settings/products
|
||||||
|
│
|
||||||
|
├── 💰 Tax (Tax Rates & Classes)
|
||||||
|
│ └── /settings/tax
|
||||||
|
│
|
||||||
|
├── 👤 Accounts & Privacy
|
||||||
|
│ └── /settings/accounts
|
||||||
|
│
|
||||||
|
├── 📧 Emails (Templates & Settings)
|
||||||
|
│ └── /settings/emails
|
||||||
|
│
|
||||||
|
├── ⚙️ Advanced (Bridge to wp-admin)
|
||||||
|
│ └── /wp-admin/admin.php?page=wc-settings&tab=advanced
|
||||||
|
│
|
||||||
|
├── 🔌 Integration (Bridge to wp-admin)
|
||||||
|
│ └── /wp-admin/admin.php?page=wc-settings&tab=integration
|
||||||
|
│
|
||||||
|
├── 🔍 Status (System Status)
|
||||||
|
│ └── /wp-admin/admin.php?page=wc-status
|
||||||
|
│
|
||||||
|
└── 🧩 Extensions (Marketplace)
|
||||||
|
└── /wp-admin/admin.php?page=wc-addons
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 Implementation Priority
|
||||||
|
|
||||||
|
### **Phase 1: Core Settings (HIGH PRIORITY)** 🔴
|
||||||
|
|
||||||
|
#### 1. General Settings (`/settings/general`)
|
||||||
|
**Purpose:** Store address, currency, units
|
||||||
|
**Complexity:** Medium
|
||||||
|
**Estimated Time:** 4-6 hours
|
||||||
|
|
||||||
|
**Fields:**
|
||||||
|
- Store Address (address 1, address 2, city, country, state, postcode)
|
||||||
|
- Selling Location (sell to all countries, specific countries)
|
||||||
|
- Shipping Location (ship to all countries, specific countries, disable shipping)
|
||||||
|
- Default Customer Location (shop country, geolocate, no location by default)
|
||||||
|
- Currency (currency, position, thousand separator, decimal separator, decimals)
|
||||||
|
- API Settings (REST API enabled)
|
||||||
|
|
||||||
|
**UI Components:**
|
||||||
|
- Text inputs
|
||||||
|
- Country/State selectors
|
||||||
|
- Currency selector
|
||||||
|
- Radio groups
|
||||||
|
- Checkboxes
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### 2. Payment Settings (`/settings/payments`)
|
||||||
|
**Purpose:** Enable/disable payment gateways, configure settings
|
||||||
|
**Complexity:** Medium-High
|
||||||
|
**Estimated Time:** 6-8 hours
|
||||||
|
|
||||||
|
**Features:**
|
||||||
|
- List all available payment gateways
|
||||||
|
- Enable/disable toggle for each gateway
|
||||||
|
- Gateway-specific settings (expandable panels)
|
||||||
|
- Drag-and-drop ordering
|
||||||
|
- Test mode indicators
|
||||||
|
|
||||||
|
**UI Components:**
|
||||||
|
- Sortable list
|
||||||
|
- Toggle switches
|
||||||
|
- Expandable panels (accordion)
|
||||||
|
- Gateway-specific forms (dynamic based on gateway)
|
||||||
|
|
||||||
|
**Gateways to Support:**
|
||||||
|
- Direct Bank Transfer (BACS)
|
||||||
|
- Check Payments
|
||||||
|
- Cash on Delivery
|
||||||
|
- PayPal (if installed)
|
||||||
|
- Stripe (if installed)
|
||||||
|
- Other 3rd party gateways (extensible)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### 3. Shipping Settings (`/settings/shipping`)
|
||||||
|
**Purpose:** Shipping zones, methods, and classes
|
||||||
|
**Complexity:** High
|
||||||
|
**Estimated Time:** 8-12 hours
|
||||||
|
|
||||||
|
**Features:**
|
||||||
|
- **Shipping Zones:**
|
||||||
|
- List all zones
|
||||||
|
- Add/edit/delete zones
|
||||||
|
- Zone regions (countries, states, postcodes)
|
||||||
|
- Zone methods (flat rate, free shipping, local pickup)
|
||||||
|
|
||||||
|
- **Shipping Classes:**
|
||||||
|
- List all classes
|
||||||
|
- Add/edit/delete classes
|
||||||
|
- Class descriptions
|
||||||
|
|
||||||
|
- **Shipping Options:**
|
||||||
|
- Enable/disable shipping calculator
|
||||||
|
- Hide shipping costs until address entered
|
||||||
|
- Debug mode
|
||||||
|
|
||||||
|
**UI Components:**
|
||||||
|
- Zone list with drag-and-drop
|
||||||
|
- Region selector (multi-select countries/states)
|
||||||
|
- Method configuration forms
|
||||||
|
- Shipping class manager
|
||||||
|
- Cost calculator inputs
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### **Phase 2: Product & Customer Settings (MEDIUM PRIORITY)** 🟡
|
||||||
|
|
||||||
|
#### 4. Product Settings (`/settings/products`)
|
||||||
|
**Purpose:** Shop page, inventory, downloadable products
|
||||||
|
**Complexity:** Medium
|
||||||
|
**Estimated Time:** 4-6 hours
|
||||||
|
|
||||||
|
**Sections:**
|
||||||
|
- **General:**
|
||||||
|
- Shop page
|
||||||
|
- Add to cart behavior
|
||||||
|
- Placeholder images
|
||||||
|
|
||||||
|
- **Inventory:**
|
||||||
|
- Manage stock
|
||||||
|
- Hold stock (minutes)
|
||||||
|
- Notifications (low stock, out of stock)
|
||||||
|
- Low stock threshold
|
||||||
|
- Out of stock threshold
|
||||||
|
- Hide out of stock items
|
||||||
|
|
||||||
|
- **Downloadable Products:**
|
||||||
|
- File download method
|
||||||
|
- Access restriction
|
||||||
|
- Grant access after payment
|
||||||
|
|
||||||
|
**UI Components:**
|
||||||
|
- Page selectors
|
||||||
|
- Number inputs
|
||||||
|
- Checkboxes
|
||||||
|
- Radio groups
|
||||||
|
- Select dropdowns
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### 5. Tax Settings (`/settings/tax`)
|
||||||
|
**Purpose:** Tax rates, classes, and options
|
||||||
|
**Complexity:** Medium-High
|
||||||
|
**Estimated Time:** 6-8 hours
|
||||||
|
|
||||||
|
**Features:**
|
||||||
|
- **Tax Options:**
|
||||||
|
- Prices entered with tax
|
||||||
|
- Calculate tax based on (customer address, shop address)
|
||||||
|
- Shipping tax class
|
||||||
|
- Rounding
|
||||||
|
- Additional tax classes
|
||||||
|
|
||||||
|
- **Standard Rates:**
|
||||||
|
- Country/State/Postcode
|
||||||
|
- Rate %
|
||||||
|
- Tax name
|
||||||
|
- Priority
|
||||||
|
- Compound
|
||||||
|
- Shipping
|
||||||
|
|
||||||
|
- **Tax Classes:**
|
||||||
|
- List all classes
|
||||||
|
- Add/edit/delete classes
|
||||||
|
|
||||||
|
**UI Components:**
|
||||||
|
- Tax rate table (sortable, editable)
|
||||||
|
- Country/State selectors
|
||||||
|
- Percentage inputs
|
||||||
|
- Checkbox groups
|
||||||
|
- Tax class manager
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### 6. Accounts & Privacy (`/settings/accounts`)
|
||||||
|
**Purpose:** Guest checkout, account creation, privacy
|
||||||
|
**Complexity:** Low-Medium
|
||||||
|
**Estimated Time:** 3-4 hours
|
||||||
|
|
||||||
|
**Sections:**
|
||||||
|
- **Guest Checkout:**
|
||||||
|
- Allow customers to place orders without account
|
||||||
|
- Allow customers to log in during checkout
|
||||||
|
|
||||||
|
- **Account Creation:**
|
||||||
|
- Allow customers to create account during checkout
|
||||||
|
- Allow customers to create account on "My Account" page
|
||||||
|
- Automatically generate username
|
||||||
|
- Automatically generate password
|
||||||
|
|
||||||
|
- **Privacy:**
|
||||||
|
- Privacy policy page
|
||||||
|
- Registration privacy policy text
|
||||||
|
- Checkout privacy policy text
|
||||||
|
- Remove personal data (retention period)
|
||||||
|
- Remove access to download (retention period)
|
||||||
|
|
||||||
|
**UI Components:**
|
||||||
|
- Checkboxes
|
||||||
|
- Page selector
|
||||||
|
- Textarea for policy text
|
||||||
|
- Number inputs (retention periods)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### **Phase 3: Communication (MEDIUM PRIORITY)** 🟡
|
||||||
|
|
||||||
|
#### 7. Email Settings (`/settings/emails`)
|
||||||
|
**Purpose:** Email templates and settings
|
||||||
|
**Complexity:** Medium-High
|
||||||
|
**Estimated Time:** 6-8 hours
|
||||||
|
|
||||||
|
**Features:**
|
||||||
|
- **Email List:**
|
||||||
|
- New Order (admin)
|
||||||
|
- Cancelled Order (admin)
|
||||||
|
- Failed Order (admin)
|
||||||
|
- Order On-Hold (customer)
|
||||||
|
- Processing Order (customer)
|
||||||
|
- Completed Order (customer)
|
||||||
|
- Refunded Order (customer)
|
||||||
|
- Customer Invoice
|
||||||
|
- Customer Note
|
||||||
|
- Reset Password
|
||||||
|
- New Account
|
||||||
|
|
||||||
|
- **Email Settings (per email):**
|
||||||
|
- Enable/disable
|
||||||
|
- Subject
|
||||||
|
- Heading
|
||||||
|
- Additional content
|
||||||
|
- Email type (plain text, HTML, multipart)
|
||||||
|
|
||||||
|
- **Global Settings:**
|
||||||
|
- "From" name
|
||||||
|
- "From" email address
|
||||||
|
- Header image
|
||||||
|
- Footer text
|
||||||
|
- Base color
|
||||||
|
- Background color
|
||||||
|
- Body background color
|
||||||
|
- Body text color
|
||||||
|
|
||||||
|
**UI Components:**
|
||||||
|
- Email list with enable/disable toggles
|
||||||
|
- Email editor (per email)
|
||||||
|
- Color pickers
|
||||||
|
- Image uploader
|
||||||
|
- Text inputs
|
||||||
|
- Textarea
|
||||||
|
- Email preview
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### **Phase 4: Advanced (KEEP IN WP-ADMIN)** ⚪
|
||||||
|
|
||||||
|
These settings are rarely used and can remain in wp-admin:
|
||||||
|
|
||||||
|
#### 8. Advanced Settings (Bridge)
|
||||||
|
- Page setup (cart, checkout, my account, terms)
|
||||||
|
- REST API
|
||||||
|
- Webhooks
|
||||||
|
- Legacy API
|
||||||
|
- WooCommerce.com account
|
||||||
|
|
||||||
|
#### 9. Integration Settings (Bridge)
|
||||||
|
- MaxMind Geolocation
|
||||||
|
- Other integrations
|
||||||
|
|
||||||
|
#### 10. System Status (Bridge)
|
||||||
|
- System status report
|
||||||
|
- Tools (clear cache, regenerate thumbnails, etc.)
|
||||||
|
- Logs
|
||||||
|
- Scheduled actions
|
||||||
|
|
||||||
|
#### 11. Extensions (Bridge)
|
||||||
|
- WooCommerce marketplace
|
||||||
|
- Browse extensions
|
||||||
|
- My subscriptions
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔧 Technical Implementation
|
||||||
|
|
||||||
|
### Backend (PHP)
|
||||||
|
|
||||||
|
**Files to Create/Modify:**
|
||||||
|
1. `includes/Admin/Rest/SettingsController.php` - REST endpoints
|
||||||
|
2. `includes/Compat/SettingsProvider.php` - Settings data provider
|
||||||
|
3. `includes/Compat/NavigationRegistry.php` - ✅ Already updated
|
||||||
|
|
||||||
|
**REST Endpoints:**
|
||||||
|
```php
|
||||||
|
GET /wp-json/woonoow/v1/settings/general
|
||||||
|
POST /wp-json/woonoow/v1/settings/general
|
||||||
|
GET /wp-json/woonoow/v1/settings/payments
|
||||||
|
POST /wp-json/woonoow/v1/settings/payments
|
||||||
|
GET /wp-json/woonoow/v1/settings/shipping
|
||||||
|
POST /wp-json/woonoow/v1/settings/shipping
|
||||||
|
// ... etc
|
||||||
|
```
|
||||||
|
|
||||||
|
**Data Flow:**
|
||||||
|
1. Frontend requests settings via REST API
|
||||||
|
2. Backend reads from WooCommerce options
|
||||||
|
3. Backend returns structured JSON
|
||||||
|
4. Frontend displays in form
|
||||||
|
5. User submits changes
|
||||||
|
6. Backend validates and saves to WooCommerce options
|
||||||
|
7. Frontend shows success/error
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Frontend (React/TypeScript)
|
||||||
|
|
||||||
|
**Files to Create:**
|
||||||
|
```
|
||||||
|
admin-spa/src/routes/Settings/
|
||||||
|
├── index.tsx ✅ Done (WooNooW settings)
|
||||||
|
├── General.tsx ✅ Placeholder created
|
||||||
|
├── Payments.tsx ✅ Placeholder created
|
||||||
|
├── Shipping.tsx ✅ Placeholder created
|
||||||
|
├── Products.tsx ⏳ To create
|
||||||
|
├── Tax.tsx ⏳ To create
|
||||||
|
├── Accounts.tsx ⏳ To create
|
||||||
|
├── Emails.tsx ⏳ To create
|
||||||
|
└── components/
|
||||||
|
├── SettingsForm.tsx ⏳ Reusable form component
|
||||||
|
├── SettingsSection.tsx ⏳ Section wrapper
|
||||||
|
├── SettingsField.tsx ⏳ Field renderer
|
||||||
|
├── PaymentGatewayList.tsx ⏳ Payment gateway manager
|
||||||
|
├── ShippingZoneList.tsx ⏳ Shipping zone manager
|
||||||
|
├── TaxRateTable.tsx ⏳ Tax rate editor
|
||||||
|
└── EmailTemplateList.tsx ⏳ Email template manager
|
||||||
|
```
|
||||||
|
|
||||||
|
**Shared Components:**
|
||||||
|
- Form wrapper with save/cancel
|
||||||
|
- Field renderer (text, select, checkbox, radio, textarea, color, image)
|
||||||
|
- Section headers
|
||||||
|
- Help text/tooltips
|
||||||
|
- Validation messages
|
||||||
|
- Loading states
|
||||||
|
- Success/error notifications
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎨 UI/UX Guidelines
|
||||||
|
|
||||||
|
### Layout
|
||||||
|
- Two-column layout on desktop (sidebar + content)
|
||||||
|
- Single column on mobile
|
||||||
|
- Sticky save button
|
||||||
|
- Breadcrumb navigation
|
||||||
|
- Section anchors (jump to section)
|
||||||
|
|
||||||
|
### Forms
|
||||||
|
- Clear labels and help text
|
||||||
|
- Inline validation
|
||||||
|
- Required field indicators
|
||||||
|
- Default values shown
|
||||||
|
- Reset to defaults button
|
||||||
|
- Unsaved changes warning
|
||||||
|
|
||||||
|
### Feedback
|
||||||
|
- Loading spinners during save
|
||||||
|
- Success toast notifications
|
||||||
|
- Error messages with details
|
||||||
|
- Confirmation dialogs for destructive actions
|
||||||
|
|
||||||
|
### Accessibility
|
||||||
|
- Keyboard navigation
|
||||||
|
- Screen reader support
|
||||||
|
- Focus indicators
|
||||||
|
- ARIA labels
|
||||||
|
- Color contrast compliance
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📝 Implementation Checklist
|
||||||
|
|
||||||
|
### Phase 1: Core Settings
|
||||||
|
- [ ] General Settings page
|
||||||
|
- [ ] Store address fields
|
||||||
|
- [ ] Currency settings
|
||||||
|
- [ ] Location settings
|
||||||
|
- [ ] Save/load functionality
|
||||||
|
- [ ] Validation
|
||||||
|
|
||||||
|
- [ ] Payment Settings page
|
||||||
|
- [ ] Gateway list
|
||||||
|
- [ ] Enable/disable toggles
|
||||||
|
- [ ] Gateway configuration
|
||||||
|
- [ ] Drag-and-drop ordering
|
||||||
|
- [ ] Save/load functionality
|
||||||
|
|
||||||
|
- [ ] Shipping Settings page
|
||||||
|
- [ ] Shipping zones list
|
||||||
|
- [ ] Zone editor
|
||||||
|
- [ ] Region selector
|
||||||
|
- [ ] Shipping methods
|
||||||
|
- [ ] Shipping classes
|
||||||
|
- [ ] Save/load functionality
|
||||||
|
|
||||||
|
### Phase 2: Product & Customer Settings
|
||||||
|
- [ ] Product Settings page
|
||||||
|
- [ ] Tax Settings page
|
||||||
|
- [ ] Accounts & Privacy page
|
||||||
|
|
||||||
|
### Phase 3: Communication
|
||||||
|
- [ ] Email Settings page
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🧪 Testing Requirements
|
||||||
|
|
||||||
|
### Functional Testing
|
||||||
|
- [ ] All fields save correctly
|
||||||
|
- [ ] Validation works
|
||||||
|
- [ ] Default values load
|
||||||
|
- [ ] Changes persist after reload
|
||||||
|
- [ ] Bridge links work
|
||||||
|
- [ ] Mobile responsive
|
||||||
|
|
||||||
|
### Integration Testing
|
||||||
|
- [ ] WooCommerce compatibility
|
||||||
|
- [ ] 3rd party gateway support
|
||||||
|
- [ ] Plugin conflict testing
|
||||||
|
- [ ] Multi-currency support
|
||||||
|
|
||||||
|
### User Testing
|
||||||
|
- [ ] Intuitive navigation
|
||||||
|
- [ ] Clear labels
|
||||||
|
- [ ] Helpful error messages
|
||||||
|
- [ ] Fast performance
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📚 Documentation
|
||||||
|
|
||||||
|
### User Documentation
|
||||||
|
- Settings overview
|
||||||
|
- Field descriptions
|
||||||
|
- Common configurations
|
||||||
|
- Troubleshooting
|
||||||
|
|
||||||
|
### Developer Documentation
|
||||||
|
- API endpoints
|
||||||
|
- Filter hooks
|
||||||
|
- Extension points
|
||||||
|
- Code examples
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔄 Migration Notes
|
||||||
|
|
||||||
|
**No data migration needed!**
|
||||||
|
- All settings use WooCommerce's native options
|
||||||
|
- Deactivating WooNooW restores wp-admin settings
|
||||||
|
- No data loss risk
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 Success Metrics
|
||||||
|
|
||||||
|
### Phase 1 Complete When:
|
||||||
|
- ✅ General, Payments, Shipping pages functional
|
||||||
|
- ✅ All fields save/load correctly
|
||||||
|
- ✅ Mobile responsive
|
||||||
|
- ✅ No console errors
|
||||||
|
- ✅ User testing passed
|
||||||
|
|
||||||
|
### Phase 2 Complete When:
|
||||||
|
- ✅ Products, Tax, Accounts pages functional
|
||||||
|
- ✅ All validations working
|
||||||
|
- ✅ Performance acceptable (<2s load)
|
||||||
|
|
||||||
|
### Phase 3 Complete When:
|
||||||
|
- ✅ Email settings functional
|
||||||
|
- ✅ Email preview working
|
||||||
|
- ✅ Template customization working
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📅 Timeline Estimate
|
||||||
|
|
||||||
|
| Phase | Pages | Estimated Time | Priority |
|
||||||
|
|-------|-------|----------------|----------|
|
||||||
|
| Phase 1 | General, Payments, Shipping | 18-26 hours | 🔴 HIGH |
|
||||||
|
| Phase 2 | Products, Tax, Accounts | 13-18 hours | 🟡 MEDIUM |
|
||||||
|
| Phase 3 | Emails | 6-8 hours | 🟡 MEDIUM |
|
||||||
|
| **Total** | **7 pages** | **37-52 hours** | |
|
||||||
|
|
||||||
|
**Note:** Times include design, implementation, testing, and documentation.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔗 Related Documents
|
||||||
|
|
||||||
|
- `PROGRESS_NOTE.md` - Development progress
|
||||||
|
- `SPA_ADMIN_MENU_PLAN.md` - Menu structure
|
||||||
|
- `PROJECT_SOP.md` - Development standards
|
||||||
|
- `STANDALONE_MODE_SUMMARY.md` - Mode documentation
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Last Updated:** November 5, 2025
|
||||||
|
**Status:** 📋 Planning Complete, Ready for Implementation
|
||||||
|
**Next Step:** Implement Phase 1 - General Settings
|
||||||
Reference in New Issue
Block a user