# MDS-PRODUCT-001 — Final Product Master & Product Intelligence Specification

Status: FROZEN FOR IMPLEMENTATION
Target platform: Retail / Restaurant / Light Production SaaS
Backend: Laravel + PostgreSQL
Frontend: React + TypeScript
Date: 2026-09-05

---

## 1. Objective

The Product domain must stop behaving like a simple catalog row. It must become a full Product Master that can support:

- Retail
- Fashion / footwear
- Grocery
- Cosmetics / supplements
- Furniture
- Electronics
- Restaurants
- Bundles / kits
- Light production / recipes

The same Catalog Core must be reused by Retail POS and Restaurant POS. Restaurant-specific user experience is a separate presentation layer, not a second product database.

The Product Master must answer two kinds of questions:

1. Operational:
   - What exactly is this product / variant?
   - Which barcode belongs to which color / size / unit?
   - Where is each variant currently available?
   - Which unit is sold or purchased?
   - What are the current price, cost, stock, images and suppliers?

2. Analytical:
   - Is this product profitable?
   - Is it growing or declining?
   - Which branch / variant / color / size is performing best?
   - Did a price change or promotion improve sales or only reduce margin?
   - Did stockouts cause sales decline?
   - How has cost, price, margin and inventory changed over time?

---

# 2. Non-negotiable UX rules

## 2.1 One page = one primary job

The Product Master is a dedicated product workspace, not one giant form.

Internal product navigation:

1. Overview
2. Media
3. Attributes & Variants
4. Barcodes & Labels
5. Units & Conversions
6. Pricing
7. Inventory
8. Purchasing
9. Batches / Expiry
10. Composition / Recipe
11. Promotions
12. Analytics
13. History

## 2.2 Easy creation first

Normal users must be able to create a basic product quickly.

### Quick Product Wizard

Step 1 — Basic data
- Name
- Code
- Category
- Brand
- Product type

Step 2 — Product structure
- Simple product
- Product with variants
- Bundle / kit
- Recipe / manufactured product
- Service

Step 3 — Images
- Main image
- Optional additional images

Step 4 — Variants
Only shown when needed:
- Color
- Size
- other attributes

Step 5 — Barcode / SKU
- Generate or enter SKU
- Generate / enter barcode
- Multiple barcodes allowed

Step 6 — Units / size
- Base unit
- Selling unit
- Purchasing unit
- conversion factor

Step 7 — Price
- Selling price
- optional cost
- optional price list

Step 8 — Opening stock
Optional:
- Warehouse
- quantity
- batch / expiry when required

Advanced sections remain optional.

## 2.3 Progressive disclosure

Fields that do not apply to the selected product type must not be shown.

Examples:
- A service does not need stock fields.
- A simple grocery item does not need a size matrix.
- A fashion item can use colors / sizes.
- A restaurant item can use sizes + modifiers.
- An expiry-tracked item exposes batch / expiry fields.

---

# 3. Product types

Catalog Product Family must support a normalized product type / behavior model.

## 3.1 Standard
One main sellable product / default variant.

## 3.2 Variant Product
Product family with one or more variant-generating attributes.

Example:
T-Shirt
- Black / M
- Black / L
- White / M
- White / L

## 3.3 Bundle / Kit
A commercial item composed of other sellable products.

Example:
Gift Box
- Shampoo x1
- Serum x1
- Cream x1

A bundle can:
- have its own selling price
- optionally explode stock consumption to components
- preserve component quantities
- support start/end validity if needed

## 3.4 Manufactured / Recipe Product
A product produced from ingredients / materials.

Example:
Large Margherita Pizza:
- Dough
- Sauce
- Cheese
- toppings

Must integrate with the existing Production / Restaurant recipe foundation rather than creating an unrelated recipe engine.

## 3.5 Service
Sellable, normally non-stock-managed.

---

# 4. Attributes

Attributes are not the same as variants.

Examples:
- Color
- Size
- Material
- Flavor
- Capacity
- Strength
- Pack size
- Length
- Width
- Height
- Depth
- Diameter
- Gender
- Fit
- Finish

Each Attribute definition needs:

- public_id
- tenant_id
- name
- code
- data_type
  - text
  - number
  - boolean
  - select
  - color
  - measurement
- variant_axis boolean
- filterable boolean
- required boolean
- sort_order
- status

---

# 5. Attribute values

A Select / Color attribute has reusable values.

Examples:

Color:
- Black
- White
- Navy

Size:
- M
- L
- XL

Value fields:

- value
- display_name
- code
- sort_order
- status
- metadata

For color:

- hex_code
- optional second_hex_code
- optional swatch image / texture
- optional display pattern metadata

The UI must display color as a visual swatch, not only as text.

---

# 6. Attribute sets

Reusable attribute groups based on product category.

Examples:

## Fashion
- Color
- Size
- Material
- Fit

## Shoes
- Color
- Shoe size
- Material
- Gender

## Furniture
- Color / finish
- Material
- Width
- Depth
- Height

## Cosmetics / supplements
- Size / volume
- Pack size
- Flavor
- Strength

## Restaurant
- Size
- Portion
- Flavor when relevant

A Category can have a default Attribute Set.

---

# 7. Variant generation

The user must not manually create every combination unless they choose to.

Example:

Color:
- Black
- White

Size:
- M
- L
- XL

Generator creates:
- Black / M
- Black / L
- Black / XL
- White / M
- White / L
- White / XL

The user can disable unwanted combinations before creation.

---

# 8. Variant Matrix

A dedicated visual matrix is required.

Example:

| Color / Size | S | M | L | XL |
|---|---:|---:|---:|---:|
| Black | ✓ | ✓ | ✓ | ✓ |
| White | ✓ | ✓ | ✓ | ✕ |
| Blue | ✕ | ✓ | ✓ | ✓ |

For inventory view, the same matrix can show current quantity:

| Color / Size | S | M | L | XL |
|---|---:|---:|---:|---:|
| Black | 5 | 12 | 3 | 0 |
| White | 2 | 8 | 6 | 4 |

Clicking a cell drills into warehouse / branch availability.

---

# 9. Variant-level data

Each Variant can independently have:

- Name
- SKU
- status
- attribute values
- images
- one or more barcodes
- selling price override
- cost
- units
- stock
- reorder rules
- dimensions / weight
- supplier references
- batch / expiry behavior
- restaurant recipe / modifier behavior where relevant

---

# 10. Size systems

Size is not just a text attribute.

Support Size Systems:

- Clothing: XS / S / M / L / XL
- Shoes EU
- Shoes UK
- Shoes US
- Kids
- Furniture / mattress dimensions
- Custom tenant-defined systems

A Product / Category / Brand may select a Size System.

---

# 11. Size Guide

A Size Guide is separate from SKU inventory.

Example:

| Size | Chest | Waist | Length |
|---|---:|---:|---:|
| M | 98 cm | 82 cm | 70 cm |
| L | 104 cm | 88 cm | 72 cm |

Fields:
- name
- scope: category / brand / product
- measurement unit
- audience / gender optional
- fit note optional
- rows and measurement columns
- active dates optional

---

# 12. Physical dimensions

Informational / logistics dimensions are separate from size labels:

- length
- width
- height
- depth
- diameter
- net weight
- gross weight
- volume

They may exist at family or variant level.

The system must distinguish:
- informational attributes
- variant-generating attributes

---

# 13. Barcodes

Barcode is not a single product field.

A Barcode can identify:

Product Variant + Unit

Examples:

Black / M / Piece -> Barcode 622...
Black / L / Piece -> Barcode 622...
Black / M / Box -> another Barcode

Required functions:

- Add barcode
- Edit barcode
- Activate / deactivate
- Remove when business rules permit
- Barcode type
- Mark primary barcode if useful
- Prevent duplicate active barcode within tenant
- Search / scan by barcode
- open exact variant directly
- print barcode labels

Supported label flow:

Barcode row:
- Print 1
- Print 5
- Print 10
- Custom quantity
- Choose label template
- Choose printer when needed

Printing must use the existing Printing / Local Agent infrastructure, not `window.print()`.

Existing Code128 / raster / thermal work should be reused.

---

# 14. Variant availability search

Inventory needs a fast Variant Availability Explorer.

Search by:

- barcode
- SKU
- product
- category
- brand
- color
- size
- any variant attribute
- branch
- warehouse

Examples:

"Black shoes size 42 available in Zagazig warehouse"

"White XL shirts with available stock below 3"

Results must show:

- product
- image
- variant attributes
- SKU
- barcode
- available
- on hand
- reserved
- incoming
- branch
- warehouse

---

# 15. POS variant behavior

## Retail POS

Scanning a variant barcode must select the exact variant.

Searching by product name can show:
- visual color swatches
- size options
- availability
- out-of-stock state

The cashier must not select the same color / size again after scanning the exact barcode.

---

# 16. Units of Measure

Already established domain must become first-class Product Master UX.

Examples:
- Piece
- Box
- Carton
- Kg
- Gram
- Liter
- Bottle

Variant-unit relation:

- unit
- conversion factor
- base unit
- sellable
- purchasable
- optional unit barcode

Example:
Piece = base = 1
Box = 12 pieces
Carton = 144 pieces

Inventory truth remains in a normalized base quantity.

---

# 17. Product Media

Family-level and variant-level images.

Capabilities:

- multiple images
- one main image
- order / sort
- upload progress
- local preview
- replace
- delete
- variant-specific images
- optional swatch / texture assets

Restaurant and Retail POS use the same stored media.

Object storage compatible.

---

# 18. Batches / production / expiry

Production date and expiry date must NOT be static product fields.

They belong to stock Lots / Batches.

A batch needs:

- batch / lot number
- variant
- warehouse
- production_date
- expiry_date
- received_at / produced_at
- quantity
- remaining quantity
- supplier / production reference when relevant
- status

Stock allocation can support FEFO for expiry-controlled items.

Product configuration indicates:
- lot tracking required
- expiry tracking required
- production date required
- shelf-life default optional

---

# 19. Composition / Bundle / Recipe

Product composition must be available before the Restaurant UI is finished.

## Bundle
Commercial kit made from other products / variants.

Fields:
- component variant
- quantity
- unit
- optional substitutions
- active dates

## Recipe / Manufactured
Uses Production / Restaurant recipe structures.

Fields may include:
- ingredient variant
- unit
- quantity
- waste %
- yield
- preparation / production metadata

Do not create duplicate recipe systems.

---

# 20. Restaurant Catalog Presentation

The Catalog core must expose presentation metadata now so Restaurant POS can use it later.

Restaurant POS layout:

Category
→ Product cards with image
→ Size / quantity
→ Modifiers
→ Add to order

Example:

Pizza
→ Margherita image
→ Small / Medium / Large
→ Extra cheese / olives / mushrooms
→ quantity
→ add

Required catalog metadata:

Category:
- display image/icon optional
- POS sort order
- visible_on_pos

Product:
- POS display name
- image
- POS sort order
- visible_on_pos
- quick color / badge metadata optional

Variant:
- size / portion
- restaurant price
- recipe link where needed
- image override optional

Modifiers remain a Restaurant domain concept but reference Catalog variants / ingredients when necessary.

---

# 21. Pricing

Product page Pricing section must show:

- active price lists
- current selling prices
- variant override
- unit-specific price where supported
- cost
- effective dates
- scheduled price changes
- tax profile when applicable

---

# 22. Price History

Immutable / auditable price history.

Every meaningful price change needs:

- old price
- new price
- price list
- variant
- unit if applicable
- effective_from
- effective_to
- reason / source
- user / automation
- promotion reference when applicable

---

# 23. Price vs Sales analytics

Product Analytics must support combined trend analysis:

- Selling price
- Units sold
- Revenue
- Gross profit
- Margin %

Goal:
answer whether a price change increased or reduced sales / profit.

---

# 24. Product Promotions Analysis

For each promotion:

- promotion period
- pre-promotion period
- during promotion
- post-promotion period

Measures:

- quantity lift
- revenue lift
- profit lift
- margin change
- discount value
- average selling price
- return rate
- new / repeat customers when available

Sales growth alone must never be considered enough to declare a promotion successful.

---

# 25. Product Analytics workspace

Dedicated route / view.

Recommended internal route:

`/products/:productId/analytics`

Time filters:
- Today
- 7 days
- 30 days
- 3 months
- 6 months
- 1 year
- custom

Comparison:
- previous equivalent period
- optional same period last year when data exists

---

# 26. Product KPI cards

Required:

- Net Sales
- Units Sold
- Gross Profit
- Gross Margin %
- Average Selling Price
- Invoice Count
- Return Quantity
- Return Rate
- Discount Amount
- Current Stock
- Inventory Value
- Average Daily Sales
- Days of Inventory
- Last Sale
- Last Purchase

---

# 27. Product profitability

At minimum:

Net Sales
- COGS
= Gross Profit

Also track:
- discounts
- returns
- promotion effects

Product classification:

## Star
High sales + high profit

## Volume
High sales + low margin

## Hidden Gem
Low sales + high margin

## Weak
Low sales + low margin

Thresholds must be configurable / period-sensitive, not hard-coded forever.

---

# 28. Product Performance Matrix

Global report:

X axis = sales volume
Y axis = profit margin

Products appear as points.

Clicking a product drills into its Product Analytics page.

---

# 29. Best / worst product reports

Reports Center requires:

- top by quantity
- top by revenue
- top by gross profit
- top by margin
- lowest sales
- lowest profit
- highest return rate
- highest discounts
- fastest stock turnover
- slowest stock turnover
- no movement for X days
- growing products
- declining products

---

# 30. Branch performance

Per product:

Company
→ Branch
→ Warehouse / Register
→ Cashier when useful

Measures:
- units
- sales
- gross profit
- margin
- return rate
- stock
- stockout time

---

# 31. Variant analytics

Required:

- best variant
- worst variant
- sales by color
- sales by size
- profit by variant
- returns by variant
- stock by variant
- stockout by variant

---

# 32. Unit analytics

Sales by unit:

Example:
- Piece 64%
- Box 28%
- Carton 8%

Useful for purchasing and pricing.

---

# 33. Inventory analytics

Per product / variant:

- on hand
- available
- reserved
- incoming
- stock value
- average daily sales
- days of inventory
- stock turnover
- last stock movement
- last sale
- last purchase

Chart:
Stock Level Over Time

---

# 34. Stockout impact

Sales analytics must mark out-of-stock periods.

The system must avoid interpreting sales decline as demand decline when the product was unavailable.

Measures:
- stockout hours / days
- estimated lost-sales opportunity where methodology is defined
- stockout by branch / variant

---

# 35. Purchase / cost analytics

Per product:

- suppliers
- last purchase cost
- weighted / relevant average cost
- min cost
- max cost
- cost trend
- purchase quantity
- purchase frequency
- supplier lead time where available

Chart:
Purchase Cost History

---

# 36. Cost vs Price vs Margin

Combined time analysis:

- purchase cost
- selling price
- margin %

Use this to identify margin erosion.

---

# 37. Customer analytics

When customer linkage exists:

- unique customers
- repeat buyers
- new buyers
- repeat purchase rate
- average days between purchases
- customer sales value

Future:
Frequently Bought Together / cross-sell recommendations.

---

# 38. Time analytics

Per product:

- sales by hour
- sales by day of week
- sales by week
- sales by month

Useful for:
- staffing
- promotions
- replenishment
- restaurant dayparts

---

# 39. Returns analytics

- quantity
- value
- return rate
- reason
- branch
- variant
- color / size

---

# 40. Product Health Score

Advanced feature, not first implementation gate.

0–100 score can use:

- sales trend
- margin
- stock turnover
- return rate
- stockout rate
- discount dependency
- promotion dependency

The score must always include an explanation, not just a number.

---

# 41. Product History / audit

History page aggregates:

- master data changes
- status changes
- attribute changes
- variant creation / edits
- barcode changes
- image changes
- unit changes
- price changes
- supplier changes
- recipe / composition changes

Posted business history must not be silently rewritten.

---

# 42. Product search

Global and module search should support:

- name
- code
- SKU
- barcode
- category
- brand
- attribute values
- supplier reference where available

Search result should identify exact variant when match is variant-specific.

---

# 43. Technical domain boundaries

Catalog owns:
- product families
- variants
- categories
- brands
- attributes
- attribute values
- size systems / guides
- media metadata
- units and variant-unit relations
- barcode identity
- product presentation metadata

Pricing owns:
- price lists
- price rules / history / effective price semantics

Inventory owns:
- stock truth
- lots / batches
- availability
- stock movements
- reorder

Purchasing owns:
- purchase orders
- supplier invoices
- supplier references / purchase history

Production owns:
- manufactured recipe / BOM semantics

Restaurant owns:
- modifiers
- long-running restaurant order behavior
- KDS
- restaurant-specific fulfillment

Printing owns:
- barcode / label print jobs and templates

Reporting owns:
- aggregates / analytics / drilldowns

Audit owns:
- audit events

Cross-domain write rule remains:
use public contracts / actions rather than direct uncontrolled writes.

---

# 44. Proposed implementation sequence

The complete scope is intentionally split into large coherent sprints, not tiny patches.

## v70 — Product Information & Variant Core

Implement together:

- Product Master internal navigation
- Attribute definitions
- Attribute values
- colors / swatches
- Attribute Sets
- Size Systems
- Size Guide foundation
- Variant generator
- Variant Matrix
- create / edit variants
- variant attribute assignment
- variant images
- barcode CRUD
- barcode per variant + unit
- barcode printing integration foundation
- Product search improvements
- preserve v69 image upload UX repair

## v71 — Inventory Identity + Composition + Restaurant Catalog

Implement together:

- Variant Availability Explorer
- matrix stock by color / size
- branch / warehouse drilldown
- batch / lot model
- production date
- expiry date
- FEFO readiness
- bundle / kit composition
- recipe / production linkage
- restaurant POS presentation metadata
- category / product POS image and ordering metadata
- Restaurant Catalog API:
  Category → Products → Size/Variant → Modifiers-ready payload

## v72 — Product Intelligence

Implement together:

- Product analytics route
- KPI engine
- sales trends
- product profitability
- variant/color/size analytics
- price history
- price vs sales
- promotion lift
- cost trend
- cost vs price vs margin
- branch performance
- inventory trend
- stockout overlays
- best / worst product reports
- performance matrix
- product history aggregation
- exports

After v72 the Product domain should be considered commercial-grade baseline.

---

# 45. Acceptance criteria

Product Master is NOT complete unless all of the following are true:

- Basic product can be added quickly.
- Complex product can be configured without manual database work.
- User can visually manage colors and sizes.
- Variant matrix is understandable.
- Every required variant can have its own SKU.
- Every variant / unit can have its own barcode.
- Barcode can be printed from the system.
- Product / variant images work immediately without refresh.
- User can search exact variant by barcode.
- User can see exact stock by color / size / branch / warehouse.
- Units and conversion are manageable.
- Batch production / expiry is tracked at lot level.
- Bundle / recipe product can be represented.
- Restaurant catalog can show Category → Product image → Size/Variant.
- Product analytics can explain profitability and trend, not only totals.
- Price history is auditable.
- Promotion analysis compares sales AND profit.
- Arabic UI is fully Arabic / RTL.
- English UI is fully English / LTR.
- Business data is not auto-translated.
- Desktop, tablet and mobile layouts remain usable.