Kikomiko/IMPORTER-UPGRADE.md

Catalog importer/exporter repair

This patch is based on your uploaded kikomiko-main.zip. It has NOT been deployed. Copy the supplied files into the matching paths in the project containing docker-compose.yml. The patch does not include or replace your database, media, secrets or catalog JSON.

Install safely

1. Back up the project and use SQLite's backup API to take a consistent backup of the running database (not a plain copy of an active WAL database). Retain the original code for rollback.
2. Test this patch on a staging copy first. Apply only these files; retain admin/data, the Docker admin_data volume, dist/data and images. Never run docker compose down -v.
3. Rebuild/restart the admin: docker compose up -d --build admin. Startup adds products.content_json and catalog_metadata without replacing existing tables. On a non-Docker install restart the existing Python service.
4. Deploy the included dist JS and product template. Purge any cached copies of /products/* and the changed JS files. No CSS or unrelated page templates are changed.
5. Back up before importing. Start with sample-catalog-v2.json in staging; its example product is inactive and its prices are TEST DATA.

Import / export

• Admin JSON upload accepts { "products": [...] } and a bare product array. Each parent accepts colorVariants (preferred), variants, or color_variants. Export consistently uses colorVariants.
• A new dashboard button downloads the complete JSON interchange file, including inactive products, categories and image mappings. It uses authenticated GET /api/export/json.
• The existing publish button writes the active storefront catalog, now retaining descriptions, SEO, variant galleries and details. Writes use atomic replacement so readers never see a half-written file.
• Local file import avoids HTTP size limits: from admin/, run python3 import_catalog.py /private/path/catalog.json --export.
• Private backup export: python3 export_catalog.py /private/path/new-backup.json. It refuses to overwrite an existing file. Docker: docker compose exec admin python3 export_catalog.py /app/data/catalog-backup-v2.json, then docker compose cp admin:/app/data/catalog-backup-v2.json ./catalog-backup-v2.json.
• Browser upload size limits are unchanged. Use the CLI for large files. Exported files can be larger because they now include complete details.

Content contract

Product and each colorVariant support: id, slug, official name, nameFa, description, descriptionIntro, seoTitle, seoDescription, details, specifications, blocks, images, heroImage, source identifiers and pricing/stock. Unknown JSON fields are preserved for future extensions; this is not permission to insert secrets into a public catalog.

Use details: [{"key":"finish","label":"فینیش","value":"مات"}] or specifications with the same format. A key/value object is also accepted. Prefer stable keys for finish, texture, coverage, shade, usage, skinType, benefits, collection, size, madeIn, howToUse. Do not invent unverified values.

Product details are shared defaults; variant rows override matching keys and add other rows. An explicit empty value suppresses an inherited row. Empty variant descriptions/SEO fall back to the parent. Full blocks are retained as structured data, but arbitrary legacy block layouts are NOT rendered by the simple detail-table component: supply details/specifications for the table.

The admin editor has Persian description, SEO and JSON detail-table controls for both product and variants. Saving preserves additional imported fields. On the dynamic product page, selecting a shade updates the description and table, alongside the existing price, gallery and stock controls. Direct variant URLs resolve the parent and select the corresponding shade. Metadata updates are client-side; this patch does not implement static SEO prerendering or repair existing canonical/JSON-LD templates.

Image arrays remain ordered references. Top-level images mappings are retained and merged across batches, but image binaries are NOT uploaded/downloaded by this patch. Put media files on the server and use reachable URLs in heroImage/images. Missing media remains missing; /i/ proxy links still rely on the existing proxy unless you rewrite them to local paths.

Existing imported shade rows

Upserts match an existing product by ID, then slug, retaining its database ID. Re-importing a family does not duplicate that family. Previously imported standalone shade rows are NOT automatically deleted/merged: use the prior migration-map.json to reconcile them after reviewing orders and links, or validate a fresh staging catalog first. Do not remove the live database to solve duplicates.

This patch accepts already grouped parent/variant JSON; it does NOT infer families from names. Use the supplied earlier nested family export, not the old flat shade list. Review catalog drift before importing old prices: no live price refresh or KIKO scraping is performed.

Important: the earlier data/site.json snapshot has empty blocks and no structured details for many/all records. Import support cannot recover content that was never exported. Supply reviewed details from the old renderer or fresh verified source data. Existing values are preserved, not fabricated.

Verification

From admin/: python3 -m unittest -v test_catalog_roundtrip.py. Tests use disposable databases: schema upgrade, Persian/variant/details/galleries round trip, repeat imports, inactive records, invalid variants and merged image manifests. Browser QA additionally checks admin save/reopen, authenticated JSON download, publish, variant description/table switching, sold-out state and mobile width.

No changes to login policy, currency conversion, scraping, or stock-sync matching are included. Existing stock-sync code still targets parent rows; per-variant scheduled stock sync remains separate work.