# Catalog import runbook

## 1. Prepare the database

Back up the existing MySQL database. Set a working MySQL 8 `DATABASE_URL` in `apps/backend/.env` and validate the Prisma schema:

```powershell
npm.cmd run prisma:generate --workspace apps/backend
npx.cmd prisma validate --schema apps/backend/prisma/schema.prisma
```

The checked-in migration is a complete initial schema for a clean database. Because the repository previously had no Prisma migration history and its legacy `docker/mysql/init.sql` schema does not match the Prisma models, an existing populated database must first be introspected and baselined. Do not apply the initial migration blindly to a populated database.

For a clean database:

```powershell
npm.cmd run prisma:deploy --workspace apps/backend
```

## 2. Preflight the workbook

```powershell
npm.cmd run catalog:dry-run --workspace apps/backend -- --workbook "C:\path\IndianBooksWorldwide_Catalog.xlsx"
```

This validates all 14 worksheets, row counts, foreign keys, text grouping, duplicates, invalid numeric values, image URLs, and catalogue URLs without connecting to the database.

## 3. Import

Link remote image/PDF URLs without downloading:

```powershell
npm.cmd run catalog:import --workspace apps/backend -- --workbook "C:\path\IndianBooksWorldwide_Catalog.xlsx" --assets link --batch-size 100 --concurrency 4
```

Or download and signature-check assets into local storage:

```powershell
npm.cmd run catalog:import --workspace apps/backend -- --workbook "C:\path\IndianBooksWorldwide_Catalog.xlsx" --assets download --storage-dir "apps\backend\storage" --asset-public-base-url "http://localhost:5000/assets" --batch-size 100 --concurrency 4
```

Add an approved catalogue/category mapping with:

```powershell
--catalogue-map "apps\backend\config\catalogue-category-map.json"
```

Resume is enabled by default and uses the workbook fingerprint plus per-row import checkpoints. Use `--no-resume` only when deliberately starting a new run.

## 4. Review outputs

Every run writes three files beneath `apps/backend/logs/catalog-import`:

- `.jsonl`: complete event and per-row log
- `.errors.jsonl`: failed rows and asset errors (empty on a clean run)
- `.summary.json`: counts, warnings, missing data, execution time, and database verification

The final verification query checks imported master/child counts, missing category relationships, operational SKU/slug uniqueness, and image/PDF asset status.

## 5. UI verification

Start the backend and frontend, sign in as an administrator, and open the Catalog module. Verify listing, search, category/author/publisher/status filters, sorting, pagination, image preview, product detail, attributes, and the Catalogue PDFs panel. The public `/books` and `/books/[slug]` screens use the same live APIs and expose the corresponding storefront checks.