dwindown/WooNooW
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
66eb4a1dce7dae7f2e4bdfc5f99b700caad20cc9
WooNooW/SETTINGS_TREE_PLAN.md

13 KiB
Raw Blame History

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:

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