docs: add Vue to React migration strategy document
- MIGRATION_STRATEGY.md: explains Vue → React coexistence approach - Documents custom Vue app in admin-product-editor.js (variation pricing table) - Provides data compatibility requirements and testing strategy - TASKLIST.md: references migration strategy in Phase 2 section Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
dwindown
200
MIGRATION_STRATEGY.md
Normal file
200
MIGRATION_STRATEGY.md
Normal file
@@ -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.*
|
||||
14
TASKLIST.md
14
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
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user