VINLAB Product Content Import Guide
===================================

Purpose
-------
Use this file as the master format and operating guide for adding products to the VINLAB website from a .txt file.

If a product batch follows this structure, products can be imported from the command line without developer help.

Importer Command
----------------
Run all commands from the Laravel project folder:

C:\xampp\htdocs\vinlab-laravel

Dry run first. This checks the file and shows what would be created or updated without saving:

php artisan vinlab:import-products "C:\Users\UMS\Downloads\your-product-file.txt" --dry-run

Import the products:

php artisan vinlab:import-products "C:\Users\UMS\Downloads\your-product-file.txt"

Example:

php artisan vinlab:import-products "C:\Users\UMS\Downloads\vinlab_educational_charts_maps_batch_2.txt" --dry-run
php artisan vinlab:import-products "C:\Users\UMS\Downloads\vinlab_educational_charts_maps_batch_2.txt"
-------------------------------
copy/paste
{php artisan vinlab:import-products "C:\Users\UMS\Downloads\your-product-file.txt" --dry-run
php artisan vinlab:import-products "C:\Users\UMS\Downloads\your-product-file.txt"
}
-------------------------------
How Import Updates Work
-----------------------
The importer uses Slug as the unique product key.

If the slug does not exist:
- A new product is created.

If the slug already exists:
- The existing product is updated with the new content.

This means you can safely correct a product by keeping the same slug and importing again.

Important Product Rules
-----------------------
Every product must belong to one of these main parent categories:
1. Nursing and Medical
2. Laboratory
3. Education Maps and Charts

The importer also recognizes existing category names such as "Nursing & Medical" and "Education Maps & Charts" as the same category style.

Every product must also have a child category under the selected parent category.

If the child category does not already exist, the importer will create it under the parent category.

Category slug note:
- Category slugs must be unique across the whole database.
- If a child category name already exists under another parent, the importer creates the new child category with a parent-specific slug.
- Example: Mathematical Instruments may become mathematical-instruments-education-maps-and-charts if mathematical-instruments already exists elsewhere.
- This is normal and prevents duplicate slug database errors.

Product Types
-------------
Every product must use one of these product types:
- E-commerce
- Inquiry
- Catalog

Database mapping:
- E-commerce = type1
- Inquiry = type2
- Catalog = type3

Required Fields for Every Product
---------------------------------
Product Type:
Product Name:
Slug:
Main Parent Category:
Child Category:
Status:
Featured:
Short Description:
Full Description:
Images:
Meta Title:
Meta Description:

Allowed Values
--------------
Status:
- active
- draft

Featured:
- yes
- no

Enable Cart:
- yes
- no

Gallery Display:
- grid
- list

Image Rules
-----------
Images can be written as:
- A public URL
- A full website path beginning with /
- A file name already available in admin media or public product images

Examples:

Images:
- https://example.com/product-image.jpg
- /assets/uploads/products/product-image.jpg
- product-image.jpg

If an image file name is not found, the importer automatically uses:

/assets/images/products/chart-collection.svg

This prevents broken product images on the website.

Recommended placeholder image line:

Images:
- vinlab-demo-product-image.jpg

Even if this file is not uploaded yet, the importer will safely replace it with the default chart placeholder.

Field Mapping
-------------
Product Name -> products.name
Slug -> products.slug
Main Parent Category -> parent category
Child Category -> products.category_id
Product Type -> products.product_type
Status -> products.status
Featured -> products.is_featured
Short Description -> products.short_description
Full Description -> products.description
Images -> products.images
Meta Title -> products.meta_title
Meta Description -> products.meta_description
Features -> products.features and fallback use cases text
Specifications -> products.specification_pairs and fallback specifications text
FAQ -> products.faq
Price -> products.price
Stock -> products.stock
Enable Cart -> products.enable_cart
Gallery Display -> products.gallery_type
Catalog Items -> products.catalog_items
Brochure URL -> products.brochure_url
Use Cases -> products.use_cases
Legacy Specifications -> products.specifications

General Bulk File Format
------------------------
For multiple products, repeat PRODUCT START and PRODUCT END blocks.

PRODUCT START
Product Type:
Product Name:
Slug:
Main Parent Category:
Child Category:
Status:
Featured:
Short Description:
Full Description:
Images:
- image-1.jpg
Meta Title:
Meta Description:
PRODUCT END

PRODUCT START
...
PRODUCT END

Product Type 1: E-commerce Format
---------------------------------
Use this for products that should show price, stock, quantity, add to cart, buy now, and request quote options.

Required E-commerce fields:
Price:
Stock:
Enable Cart:
Features:
Specifications:

Template:

PRODUCT START
Product Type: E-commerce
Product Name:
Slug:
Main Parent Category:
Child Category:
Status: active
Featured: no
Price:
Stock:
Enable Cart: yes
Short Description:
Full Description:
Features:
- Feature 1
- Feature 2
- Feature 3
Specifications:
- Label: Value
- Label: Value
- Label: Value
Images:
- image-1.jpg
- image-2.jpg
Meta Title:
Meta Description:
PRODUCT END

E-commerce Example:

PRODUCT START
Product Type: E-commerce
Product Name: Advanced Nursing Training Manikin
Slug: advanced-nursing-training-manikin
Main Parent Category: Nursing and Medical
Child Category: Nursing Manikins
Status: active
Featured: yes
Price: 45000
Stock: 12
Enable Cart: yes
Short Description: Full-body training manikin for nursing colleges and clinical skill labs.
Full Description: This manikin supports practical nursing demonstrations, patient care training, and skill-based classroom learning.
Features:
- Full-body patient care practice
- Suitable for nursing colleges and skill labs
- Durable washable surface
- Supports repeated classroom demonstrations
Specifications:
- Material: Medical-grade PVC
- Application: Nursing training
- Warranty: As per configuration
Images:
- nursing-manikin-front.jpg
- nursing-manikin-lab-training.jpg
Meta Title: Advanced Nursing Training Manikin
Meta Description: Nursing training manikin for institutions, hospitals, and medical skill labs.
PRODUCT END

Product Type 2: Inquiry Format
------------------------------
Use this for products where users should request a quote instead of buying directly.

Required Inquiry fields:
Features:
Specifications:
FAQ:

Template:

PRODUCT START
Product Type: Inquiry
Product Name:
Slug:
Main Parent Category:
Child Category:
Status: active
Featured: no
Short Description:
Full Description:
Features:
- Feature 1
- Feature 2
- Feature 3
Specifications:
- Label: Value
- Label: Value
FAQ:
- Question: Answer
- Question: Answer
Images:
- image-1.jpg
- image-2.jpg
Meta Title:
Meta Description:
PRODUCT END

Inquiry Example:

PRODUCT START
Product Type: Inquiry
Product Name: Educational Political World Map
Slug: educational-political-world-map
Main Parent Category: Education Maps and Charts
Child Category: Educational Maps
Status: active
Featured: yes
Short Description: Classroom wall map designed for schools, colleges, and geography labs.
Full Description: A clear educational map for classroom teaching, visual learning, and geography reference.
Features:
- High readability for classroom display
- Suitable for schools and educational institutions
- Available in multiple sizes
Specifications:
- Format: Wall map
- Usage: Geography education
- Customization: Available
FAQ:
- Can this be customized?: Yes, custom size and format can be discussed.
- Is bulk supply available?: Yes, bulk institutional supply is available.
Images:
- classroom-world-map.jpg
- educational-map-detail.jpg
Meta Title: Educational Political World Map
Meta Description: Educational world map for schools, colleges, and geography classrooms.
PRODUCT END

Product Type 3: Catalog Format
------------------------------
Use this for grouped visual catalog products where one product contains multiple catalog items.

Required Catalog fields:
Gallery Display:
Catalog Items:

Catalog item line format:

- Group: Group Name | Code: Item Code | Title: Item Title | Image: image-name.jpg

Template:

PRODUCT START
Product Type: Catalog
Product Name:
Slug:
Main Parent Category:
Child Category:
Status: active
Featured: no
Gallery Display: grid
Short Description:
Full Description:
Images:
- main-image.jpg
- secondary-image.jpg
Catalog Items:
- Group: Group Name | Code: Item Code | Title: Item Title | Image: image-name.jpg
- Group: Group Name | Code: Item Code | Title: Item Title | Image: image-name.jpg
Meta Title:
Meta Description:
PRODUCT END

Catalog Example:

PRODUCT START
Product Type: Catalog
Product Name: Biology Educational Charts Collection
Slug: biology-educational-charts-collection
Main Parent Category: Education Maps and Charts
Child Category: Educational Charts
Status: active
Featured: no
Gallery Display: grid
Short Description: Visual chart collection for schools, biology labs, and teaching institutions.
Full Description: A grouped catalog of biology charts for classroom teaching, revision, and practical learning support.
Images:
- biology-chart-wall-display.jpg
- biology-chart-classroom.jpg
Catalog Items:
- Group: Human Biology | Code: BIO-01 | Title: Human Digestive System Chart | Image: digestive-system-chart.jpg
- Group: Human Biology | Code: BIO-02 | Title: Human Heart Chart | Image: heart-chart.jpg
- Group: Botany | Code: BOT-01 | Title: Plant Cell Structure Chart | Image: plant-cell-chart.jpg
Meta Title: Biology Educational Charts Collection
Meta Description: Biology charts collection for schools, colleges, and educational institutions.
PRODUCT END

Optional Fields
---------------
These fields are supported by the importer, but they are not required:

Brochure URL:
Use Cases:
- Use case 1
- Use case 2
Legacy Specifications:
- Specification text line 1
- Specification text line 2
SEO Keywords:
Notes for Admin:

Notes:
- Brochure URL is saved.
- Use Cases is saved as product use case text.
- Legacy Specifications is saved as old specifications text.
- SEO Keywords and Notes for Admin are accepted in the file so they do not break imports, but they are not displayed on the website by default.

Best Practices
--------------
Use readable, unique slugs:
- good: advanced-nursing-training-manikin
- avoid: product-1

Keep the same slug when updating an existing product.

Use exact field labels shown in this guide.

Use one product per PRODUCT START / PRODUCT END block.

Use hyphen lines for lists:
- Feature
- Label: Value

Run dry-run before every import.

Review the website after import:
- /products
- /products/product-slug

Common Commands
---------------
Check the importer without saving:

php artisan vinlab:import-products "C:\Users\UMS\Downloads\your-product-file.txt" --dry-run

Import products:

php artisan vinlab:import-products "C:\Users\UMS\Downloads\your-product-file.txt"

Clear Laravel cache if pages look stale:

php artisan optimize:clear

Preview empty categories that can be cleaned:

php artisan vinlab:cleanup-empty-categories --dry-run

Delete categories that have no products and no child categories:

php artisan vinlab:cleanup-empty-categories

Start local Laravel server if needed:

php artisan serve --host=127.0.0.1 --port=8090

Then open:

http://127.0.0.1:8090/products

Troubleshooting
---------------
Message: No PRODUCT START / PRODUCT END blocks were found.
Fix: Make sure every product starts with PRODUCT START and ends with PRODUCT END.

Message: Skipped one product block because name or category was missing.
Fix: Add Product Name, Main Parent Category, and Child Category.

Product updated instead of created.
Reason: The slug already exists. This is expected when correcting or replacing content.

Image is showing the default chart placeholder.
Reason: The image file name was not found in public product images or admin uploads. Upload the image later or use a public URL.

Product does not show on public listing.
Fix: Make sure Status is active.

Error: Duplicate entry for key slug while creating a category.
Fix: The importer now prevents this by creating a parent-specific category slug when needed. Run the same import command again after updating the project code.

Demo Data Marker
----------------
Some old demo products may be marked with DEMO_DATA in meta_title.

Find demo products:

SELECT id, name, slug, meta_title
FROM products
WHERE meta_title LIKE '%DEMO_DATA%';

Move demo products to trash:

UPDATE products
SET deleted_at = NOW()
WHERE meta_title LIKE '%DEMO_DATA%';

Permanently delete demo products:

DELETE FROM products
WHERE meta_title LIKE '%DEMO_DATA%';

Remove demo marker but keep products:

UPDATE products
SET meta_title = TRIM(REPLACE(meta_title, '[DEMO_DATA]', ''))
WHERE meta_title LIKE '%DEMO_DATA%';