munch-ease-frontend/refactor-strategy.md

Refactor Strategy

This document outlines a pragmatic, step-by-step refactor plan to improve structure, readability, and maintainability. Each step includes a clear outcome and a checkbox to track progress.

Last updated: 2025-10-18

Goals

• Separate concerns (routing, HTTP/API, mapping/normalization, UI logic)
• Improve readability and testability
• Establish light-weight standards (naming, lint/format) without blocking development
• Keep changes incremental and safe

Phases and Steps

Phase 1 — Routing and Auth (Foundational)

• Extract router into src/router/index.js with named routes
• Add route meta requiresAuth and a global auth guard
• Remove auth-redirect from App.vue (handled by guard instead)
• Convert top-level nav to use route names consistently (optional)

Outcome: Routing logic is centralized and testable; pages redirect consistently based on auth.

Phase 2 — API Layer Split (Incremental)

• Add src/api/http.js wrapper for JSON fetch with error handling and env-based base URL
• Add src/api/mappers/mealMapper.js to normalize Meal data (dates)
• Add src/api/meals.js and migrate MealPlan API calls (get upcoming, mark consumed, delete)
• Create src/api/recipes.js and migrate recipe endpoints
• Create src/api/shopping.js and migrate shopping endpoints
• Create src/api/auth.js and migrate auth endpoints

Outcome: Feature modules call cohesive services; logic for mapping/normalization is isolated and testable.

Phase 3 — Composables (UI-Facing Logic)

• Add src/composables/useAuth.js (user ref, ensureAuth)
• Add src/composables/useMeals.js (fetch and mutate meals)
• Refactor pages to use composables and <script setup> where appropriate
  • Converted: MealPlanPage.vue, EditMealPage.vue, CurrentShoppingListPage.vue, MyShoppingPage.vue, PurchasedShoppingListPage.vue
  • Added: src/composables/useShopping.js; adopted by shopping pages

Outcome: Components get smaller and easier to read; business logic is reusable.

Phase 4 — Tooling and Standards

• Add Prettier config and .editorconfig; wire Prettier with ESLint
• Upgrade ESLint (if/when convenient) and align with Vue 3 rules
• Ensure Volar is used (dev environment) for Vue 3 type intelligence
  • Add lint-staged + husky for pre-commit formatting
  • Optional next: enable Vue macros (defineProps/defineOptions) in ESLint or upgrade ESLint/vue plugin

Outcome: Stable formatting and consistent linting across contributors.

Phase 5 — Tests (Targeted)

• Add a unit test runner (Vitest or Jest)
• Test mappers (dates/reference wiring)
• Test units.js conversions and totals

Outcome: Confidence in refactors and easier onboarding.

Environment

• Prefer VUE_APP_API_BASE for backend base URL (fallback to /api for dev). Optionally set a devServer proxy in vue.config.js.

Progress Log

• 2025-10-18:
  • Extracted router with names and auth guard
  • Removed App.vue auth redirect
  • Added api/http.js, api/mappers/mealMapper.js, api/meals.js
  • Updated MealPlanPage.vue to use meals API
  • Added api/mappers/recipeMapper.js, api/recipes.js; updated recipes components
  • Added api/mappers/shoppingListMapper.js, api/shopping.js; updated shopping components
  • Added api/auth.js and api/persons.js; router uses auth API
  • Added composables/useAuth.js and used in MyShoppingPage.vue
  • Added Prettier and EditorConfig
  • Added composables/useMeals.js; migrated meal pages to composable and <script setup>
  • Added composables/useShopping.js; migrated shopping pages to composable and <script setup>
  • Added VS Code Volar recommendation (.vscode/extensions.json)