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