diff --git a/MIGRATION_STRATEGY.md b/MIGRATION_STRATEGY.md new file mode 100644 index 000000000..a30286108 --- /dev/null +++ b/MIGRATION_STRATEGY.md @@ -0,0 +1,200 @@ +# Formipay — Vue to React Migration Strategy + +**Date:** April 18, 2026 +**Context:** Phase 2 — React Admin Foundation + +--- + +## Overview + +This document explains how to approach the existing Vue.js code in Formipay during the migration to React admin panels. + +**Key Principle:** We are NOT doing a "rewrite everything at once" approach. Vue and React will coexist during Phase 2, with Vue being removed incrementally as React replacements are shipped. + +--- + +## Current Vue.js Usage Inventory + +| Type | Location | Purpose | Replacement Phase | +|------|----------|---------|-------------------| +| **WPCFTO Framework** | `vendor/` | Settings form builder (repeater, fields, etc.) | F2.8 (Global Settings) | +| **Custom Vue 2 App** | `admin/assets/js/admin-product-editor.js` | Product variation pricing table | F2.9 (Product Editor) | +| **Partial Vue Editor** | `admin/assets/vue/` (if exists) | Form builder canvas | F2.4 (Form Builder) | + +--- + +## Migration Strategy + +### Phase 1: Coexistence (Current State) + +``` +┌─────────────────────────────────────────────┐ +│ Admin Pages │ +├─────────────────────────────────────────────┤ +│ Forms │ Products │ Orders │ Settings │ +│ WPCFTO │ WPCFTO │ WPCFTO │ WPCFTO │ +│ + Vue │ + Vue │ (none) │ + Vue │ +│ │ (custom) │ │ │ +└─────────────────────────────────────────────┘ +``` + +**Status:** All pages working. WPCFTO handles forms, custom Vue handles product variations. + +--- + +### Phase 2: Incremental React Rollout + +**Week 3:** Build pipeline + React infrastructure. Vue untouched. + +**Week 4:** React Form Builder replaces WPCFTO form editor. +``` +Forms: WPCFTO/Vue → React ✅ +Products: WPCFTO + custom Vue → unchanged +Orders: (none) → React ✅ +Settings: WPCFTO → unchanged +``` + +**Week 5:** React Order Management (no Vue to touch). +``` +Orders → React ✅ +``` + +**Week 6:** React Global Settings replaces WPCFTO. +``` +Settings: WPCFTO → React ✅ +Products: WPCFTO + custom Vue → unchanged +``` + +**After Week 6:** WPCFTO framework can be fully removed. Only custom Vue remains. + +--- + +### Product Editor Migration (F2.9) + +The custom Vue app in `admin-product-editor.js` is the last Vue piece to migrate. + +#### Current Features (Must Recreate in React) + +| Feature | Complexity | Notes | +|---------|-----------|-------| +| Multi-currency flat pricing | Medium | Show all currencies as columns when enabled | +| Multi-currency expanded mode | High | Inner tables per variation row | +| Dynamic rows from attribute repeater | High | Syncs with WPCFTO repeater in real-time | +| Decimal digits per currency | Medium | Step values calculated from currency config | +| Required field validation | Low | Default currency must have price | +| Real-time JSON update to hidden input | Medium | `product_variation_variables` hidden field | +| SweetAlert2 error dialogs | Low | Uses existing window.Swal or custom alert | + +#### Implementation Approach + +**Option A: Recreate from Scratch (Recommended)** + +1. **Read current Vue code logic** — understand the data flow +2. **Build React component** — `VariationPricingTable.jsx` + - Use `@tanstack/react-table` for the table + - Use `@wordpress/components` for form inputs (TextControl, etc.) + - State management via React hooks (useState, useEffect) +3. **Data sync layer** — same API endpoint `get_product_variables` +4. **Validation logic** — port `findFirstMissingDefault()` to React + +**Pros:** Clean React code, modern patterns, better type safety +**Cons:** Requires careful testing to match all edge cases + +**Option B: Vue-in-React Wrapper (Not Recommended)** + +Wrap the existing Vue app in a React component using a library like `vue-react-wrapper`. + +**Pros:** Faster, less risky +**Cons:** Technical debt, adds bundle size, mixing paradigms + +**Recommendation:** Option A — rewrite in React. The logic is well-contained (~500 lines) and rewriting gives us clean, maintainable React code. + +--- + +## Migration Checklist for F2.9 + +When implementing the React Product Editor: + +- [ ] Read and document current Vue variation table behavior +- [ ] Create `src/admin/pages/Products/VariationPricingTable.jsx` +- [ ] Implement multi-currency flat pricing mode +- [ ] Implement multi-currency expanded mode (inner tables) +- [ ] Implement attribute repeater sync (MutationObserver or polling) +- [ ] Implement decimal digits per currency step calculation +- [ ] Implement required field validation (default currency) +- [ ] Implement real-time JSON update to hidden `product_variation_variables` input +- [ ] Add SweetAlert2 or equivalent for validation errors +- [ ] Test with various currency configurations +- [ ] Test with existing products (data migration) +- [ ] Remove old Vue script enqueuing from Product page +- [ ] Remove Vue dependency if no longer used elsewhere + +--- + +## Data Compatibility + +The React component must read/write the same data format as the Vue app: + +**Hidden input format** (`product_variation_variables`): +```json +[ + { + "key": "Red|||Large", + "name": "Red - Large", + "stock": "", + "weight": 0, + "active": true, + "prices": [ + { + "currency": "USD:::United States Dollar:::$", + "regular_price": "29.99", + "sale_price": "24.99", + "currency_decimal_digits": 2 + } + ] + } +] +``` + +**API endpoint** (already exists): +```php +// Product.php - add this if not present +add_action('wp_ajax_get_product_variables', [$this, 'ajax_get_product_variables']); +``` + +--- + +## Testing Strategy + +1. **Unit Tests:** Test variation price calculation logic in isolation +2. **Integration Tests:** Test loading/saving variations via AJAX +3. **Manual Tests:** + - Create product with variations + - Test multi-currency flat mode + - Test multi-currency expanded mode + - Test validation (missing default price) + - Test attribute repeater sync + - Test editing existing products (data compatibility) + +--- + +## Rollback Plan + +If React version has critical bugs: +1. Keep Vue version as fallback +2. Add feature flag in settings: "Use React Product Editor (beta)" +3. Default to Vue, allow opting into React +4. Fix React, then make it default + +--- + +## Notes + +- **No Vue Router used** — the Vue app is a simple mount, no routing to worry about +- **No Vuex** — state is local component state + hidden input sync +- **jQuery dependency** — the Vue app uses jQuery for DOM selection (`$('#product-variables-table')`. React version should eliminate this. +- **Timing:** WPCFTO removal happens after Global Settings (F2.8), but Product Editor Vue app is independent — can be migrated anytime after Week 3. + +--- + +*End of Migration Strategy.* diff --git a/TASKLIST.md b/TASKLIST.md index 5c4edcb69..085e25ad8 100644 --- a/TASKLIST.md +++ b/TASKLIST.md @@ -58,6 +58,13 @@ ## Phase 2 — React Admin Foundation +> ⚠️ **IMPORTANT:** Read `MIGRATION_STRATEGY.md` before starting Phase 2 +> - Explains Vue → React coexistence strategy +> - Documents custom Vue app in `admin-product-editor.js` that needs recreation +> - Provides data compatibility requirements and testing strategy + +> **See `MIGRATION_STRATEGY.md`** for detailed Vue → React migration approach + ### Week 3: Build Pipeline - [ ] **F2.1** Initialize `package.json` with `@wordpress/scripts` @@ -87,11 +94,16 @@ ### Week 6: Settings & Editors - [ ] **F2.18** Build global settings page (replace WPCFTO) -- [ ] **F2.19** Build product editor page +- [ ] **F2.19** Build product editor page (includes variation pricing table) + - **See `MIGRATION_STRATEGY.md`** — custom Vue app in `admin-product-editor.js` must be recreated in React + - Features: multi-currency flat/expanded pricing, attribute repeater sync, validation - [ ] **F2.20** Build coupon editor page - [ ] **F2.21** Build access items manager - [ ] **F2.22** Build license management page - [ ] **F2.23** Remove/deprecate Vue admin code + - After all React admin pages are working, remove `admin/assets/vue/` if exists + - Remove WPCFTO framework dependency after F2.18 + - Remove Vue.js from enqueued scripts after F2.19 complete ---