# SAP Migration CSV Mapper

## Project Overview

This is a single-page Vue.js application for preparing SAP migration SpreadsheetML files from CSV input. The UI lets you inspect the source data, map CSV columns to SAP target fields, apply optional transformations, validate required fields, and export a fresh XML file based on the original SAP template.

## Key Components

### HTML Structure (`mapper.html`)

- Uses Vue 3 and Tailwind CSS.
- Provides a three-column workspace:
  1. CSV source data and row preview
  2. Worksheet-by-worksheet SAP mapping editor
  3. Generated SpreadsheetML output with copy/download actions

### JavaScript Logic (`mapper.js`)

- Manages all application state with the Vue 3 Composition API.
- Loads CSV data and SAP SpreadsheetML templates.
- Detects relevant worksheets, SAP headers, required fields, data start rows, and field metadata.
- Supports drag-and-drop mappings, constants, field search, worksheet collapsing, and sample previews.
- Can auto-map fields either with local fuzzy matching or with an OpenAI-assisted match request when an API key is configured.
- Generates XML rows from the original worksheet template so formatting and structure stay close to the uploaded SAP file.

### Utilities (`mapper-utils.js`)

- CSV parsing via PapaParse
- SpreadsheetML-safe XML escaping
- Date parsing/formatting helpers
- Output row splicing into the original XML template
- Value transformation logic for lookup, date, string, and JS expressions

### Styling (`mapper.css`)

- Provides project-specific visual styling, layout refinements, and drag/drop feedback.

## Program Flow

The runtime flow in `mapper.js` is organized around a few main steps:

1. **Application setup**
   The Vue app creates reactive stores for CSV data, XML worksheet metadata, mappings, transformations, validation state, UI toggles, and generated output.

2. **Load XML template**
   `loadXML()` reads the SAP SpreadsheetML file and passes it through `parseXmlWithFallback()`.
   The parser tries the browser `DOMParser` first, falls back to `xmldom` if needed, and sanitizes common SAP markup problems such as raw `<LS>` markers or invalid ampersands.

3. **Analyze worksheets**
   For each worksheet, the app:
   - skips informational sheets such as `Readme` or `Feldliste`
   - detects the header row containing SAP field names
   - determines which fields are required
   - finds the row where generated data should begin
   - reads technical field metadata used for output types
   - captures a reusable row template so generated rows inherit the original structure

4. **Load CSV source data**
   `loadCSV()` parses the CSV into `headers` and `rows`.
   The first row becomes the list of draggable source fields and the remaining rows are used for preview and output generation.

5. **Create mappings**
   Users can map fields manually by drag and drop or let `autoMap()` suggest mappings.
   Auto-mapping first tries cached/OpenAI results when an API key is available, otherwise it uses local fuzzy matching based on normalized names and token overlap.

6. **Apply transformations**
   Each mapped SAP field can optionally run through `applyTransform()` before export.
   Supported transformation types are:
   - lookup table
   - date conversion
   - string operation
   - JavaScript expression

7. **Validate before export**
   `validateBeforeGenerate()` checks two things:
   - required SAP fields that are not mapped at all
   - CSV rows that would still produce empty required values after constants and transformations

8. **Generate output XML**
   `generateXmlFromTemplate()` loops through every mapped worksheet and every CSV row.
   For each row it:
   - reads the mapped CSV values
   - applies transformations
   - infers the correct SpreadsheetML cell type
   - builds a new `<Row>` either from the detected template row or from scratch
   - inserts the generated row block back into the original worksheet using `spliceRows()`

9. **Export**
   The final XML is shown in the output pane and can be copied to the clipboard or downloaded as a file.

## Core Functionality

1. **Load SAP Template**: Upload SpreadsheetML (.xml) file to detect target schema
2. **Load CSV Data**: Upload source data file
3. **Field Mapping**: Drag CSV fields to SAP fields or set constants
4. **Data Transformation**: Apply lookups, date conversions, string operations, or JS expressions
5. **Validation**: Check for required fields and missing data
6. **XML Generation**: Produce migration-ready SpreadsheetML output

## Technical Features

- **Robust XML parsing**: Handles malformed SAP templates with sanitization and parser fallback.
- **Worksheet introspection**: Detects SAP headers, metadata rows, required flags, and row templates.
- **Auto-mapping**: Supports OpenAI-assisted and local fuzzy field matching.
- **Preview system**: Lets users inspect sample CSV values and transformation results before export.
- **Validation**: Warns about missing required mappings and empty required output values.
- **Export options**: Supports clipboard copy and file download.

## Use Case

This tool is aimed at SAP migration scenarios where CSV source data must be inserted into a pre-defined SpreadsheetML template with strict field names, types, and required-field expectations. The included test data suggests a strong focus on HR-style migration packages, but the mapper itself is generic enough for other SAP import templates that follow the same worksheet structure.