# Existing Data Migration Guide

## Source inputs included for controlled import

- `colorjet-service-pro-backup-2026-07-02(1).json`
- `colorjet-item-ledger-2026-07-02.csv`

The JSON backup contains customer, engineer, machine, service, stock/parts, invoice, import/LC/TT, GRN, landed-cost, cash/bank and activity-oriented records. The CSV contains item-ledger movements and stock balance fields.

## Security before import

1. Back up production database.
2. Keep the files inside `data/migration-input/`; do not publish them.
3. Do not import the original `odooSyncConfig` credentials. Configure Odoo separately through encrypted deployment secrets after validation.

## Preview mode

```bash
docker compose exec server npm run import:colorjet:docker -- \
  --file /app/data/migration-input/colorjet-service-pro-backup-2026-07-02.json \
  --preview

docker compose exec server npm run import:ledger:docker -- \
  --file /app/data/migration-input/colorjet-item-ledger-2026-07-02.csv \
  --preview
```

## Commit mode

```bash
docker compose exec server npm run import:colorjet:docker -- \
  --file /app/data/migration-input/colorjet-service-pro-backup-2026-07-02.json

docker compose exec server npm run import:ledger:docker -- \
  --file /app/data/migration-input/colorjet-item-ledger-2026-07-02.csv
```

## Current mapper behavior

The migration scripts create an auditable import batch and map these core records: customers, engineers, machines, products/parts, suppliers, import orders, LC payments, shipments, landed cost records, cash/bank opening records, invoices, service tickets, schedules and activity logs. Item-ledger CSV creates/updates product records and stock movements.

Duplicate safety is based on stable legacy IDs when present, then uses business identifiers such as SKU, invoice number, ticket number, LC/order number, machine serial or normalized customer identity. Never rerun a commit import without checking the previous import batch status.

## Reconciliation checklist

After import, compare:

- Customer count and total due
- Product/part count and stock value
- Open service-ticket count
- Invoice count and due total
- Cash/bank opening balance
- LC/TT outstanding total
- Imported stock movement count

For legacy records without a valid foreign key, keep the source reference in `legacy_id` or import audit notes. Do not silently fabricate relationships.