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)

- [x] Extract router into `src/router/index.js` with named routes
- [x] Add route meta `requiresAuth` and a global auth guard
- [x] Remove auth-redirect from `App.vue` (handled by guard instead)
- [x] 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)

- [x] Add `src/api/http.js` wrapper for JSON fetch with error handling and env-based base URL
- [x] Add `src/api/mappers/mealMapper.js` to normalize Meal data (dates)
- [x] Add `src/api/meals.js` and migrate MealPlan API calls (get upcoming, mark consumed, delete)
- [x] Create `src/api/recipes.js` and migrate recipe endpoints
- [x] Create `src/api/shopping.js` and migrate shopping endpoints
- [x] 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)

- [x] Add `src/composables/useAuth.js` (user ref, ensureAuth)
- [x] Add `src/composables/useMeals.js` (fetch and mutate meals)
- [x] 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

- [x] Add Prettier config and .editorconfig; wire Prettier with ESLint
- [ ] Upgrade ESLint (if/when convenient) and align with Vue 3 rules
- [x] Ensure Volar is used (dev environment) for Vue 3 type intelligence
  - [x] 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)

- [x] Add a unit test runner (Vitest)
- [x] Test mappers (dates/reference wiring)
  - Added tests: `tests/mealMapper.test.js`, `tests/shoppingListMapper.test.js`
- [x] Test `units.js` conversions and totals
  - Added tests: `tests/units.test.js`

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`)
  - Set up Vitest (`vitest.config.js`), added test scripts in `package.json`
  - Wrote unit tests for mappers and units: `tests/mealMapper.test.js`, `tests/shoppingListMapper.test.js`, `tests/units.test.js`