Develop Jewellery module for Prestashop

Project Title: Jewellery Pricing Module – “TheJeweller”

1. Project Overview

Develop a fully functional PrestaShop 9.1.0 module that allows a jewellery store to calculate the final product price based on:

· Metal type and weight
· Making charges (in percentage)
· Diamonds (multiple, by quality and weight)
· Gemstones (by type and weight)
· Normal stones (by type and weight)

The shop admin will set all base prices (price per gram, price per carat/unit for stones) from the module configuration. When creating a product, the admin assigns a metal type, enters the product weight and making charges, and adds diamonds/stones/gemstones with their respective weights. The module will dynamically override the product’s displayed price using a custom formula and show a detailed price breakdown on the frontend (product page, cart, checkout).

Important: The module must not modify any core PrestaShop file. It must use only hooks and the standard override system for pricing.

---

2. Functional Requirements

2.1 Back‑End Global Configuration

A single configuration page accessible from the module list (“Configure”) with the following sections:

A. Metal Prices (per gram)

· Gold 24kt
· Gold 22kt
· Gold 18kt
· Gold 14kt
· Gold 9kt
· Silver
· Platinum

All fields accept decimal numbers (float). Values are stored in ps_configuration.

B. Diamond Prices (per carat)
The admin can define diamond qualities as key-value pairs (e.g. “VVS1”, “VS1”, “SI1”). There must be a way to add, edit, and remove qualities. Each quality has a price per carat (float).

C. Gemstone Prices (per ratti or per carat)
Same as diamonds: admin can manage gemstone types (e.g. “Ruby”, “Emerald”, “Sapphire”) with a price per unit (admin‑defined unit – e.g. price per ratti). The unit can be fixed (e.g. carat) or configurable. We’ll assume price per ratti for simplicity unless you specify otherwise.

D. Stone Prices (per gram)
Admin can manage normal stone types (e.g. “Cubic Zirconia”, “Moissanite”) with price per gram.

All these lists must be maintainable from the module’s configuration interface (add, edit, delete). The module should provide sensible default values.

2.2 Product‑Level Custom Data

When creating or editing a product (in the back office), the module adds a new tab or a section on the product page (preferably a new tab via displayAdminProductsExtra or inside the “Prices” tab) with the following fields:

1. Enable custom pricing for this product – a checkbox. If not checked, the product uses standard PrestaShop pricing.
2. Metal Type – a dropdown populated from the metals configured (Gold 24kt, Gold 22kt, etc.).
3. Product Weight (grams) – numeric field, required.
4. Making Charges – numeric field ( in percentage).
5. Diamond entries – a repeatable group of fields (like a table) where the admin can add multiple diamonds:
· Diamond Quality (dropdown from the configured diamond qualities)
· Weight in carats (numeric)
· The system calculates cost = weight × price per carat of that quality.
· Option to delete a row.
· At least one row visible by default; admin can add more rows dynamically (or via a simple “Add diamond” button that reloads with an extra row).
6. Gemstone entries – similar repeatable group:
· Gemstone Type (dropdown)
· Weight in grams (numeric)
· Calculated cost = weight × price per ratti
7. Stone entries – similar repeatable group:
· Stone Type (dropdown)
· Weight in grams (numeric)
· Calculated cost = weight × price per gram

All this data must be saved in custom database tables linked to id_product. The data must be loaded back when editing the product.

2.3 Dynamic Price Calculation

The final product price (before tax) must be calculated as:

Total Price = (Product Weight × Metal Price per Gram)
+ Making Charges
+ Sum(Diamond Weight × Diamond Price per Carat)
+ Sum(Gemstone Weight × Gemstone Price per ratti)
+ Sum(Stone Weight × Stone Price per Gram)

· The module must use the actionProductPriceCalculation hook to override the product price on the fly.
· It must respect the shop’s currency, customer group discounts, specific prices, and tax settings.
· If a product is not enabled for custom pricing, the hook must not change the standard price.
· Prices must be calculated in the default currency and converted automatically for other currencies.
· Rounding must follow PrestaShop’s standard rounding rules (configurable by the shop).

2.4 Front‑End Price Breakdown Display

A. Product Page
Below or beside the main price, show a detailed price breakdown. The breakdown must be displayed via the displayProductPriceBlock hook (type after_price or similar). It should list:

· Metal Cost (Weight × Metal price/g) – amount
· Making Charges – amount
· Diamond Cost (if any) – with subtotal and optionally per‑diamond details
· Gemstone Cost (if any)
· Stone Cost (if any)
· Total Price – matches the displayed price

The breakdown must be styled cleanly and be mobile‑friendly.

B. Cart / Checkout
When a product with custom pricing is in the cart, use the displayCartExtraProductInfo hook to show the same price breakdown (or a condensed version) under each product line. The total in the cart must match the custom price.

C. Order Details & Emails
Ensure that the price breakdown is stored as part of the order (e.g. in a custom order detail table or as product attributes) so that it can be displayed in the order confirmation, email, and admin order view.

2.5 Compatibility & Constraints

· The module must work with PrestaShop 9.1.0 (Symfony‑based back office, classic or hummingbird theme on front).
· No core file modifications.
· Use Symfony controllers for the module’s configuration page if possible, following PrestaShop 9 standards.
· Must not break the standard product save process, combination generation, or other modules.
· Must support multi‑language (all labels translatable).
· Must support multi‑store if the PrestaShop instance has multiple shops (store configuration and product data per shop or globally – please specify: ideally product‑level data per shop, global metal/stone prices per shop group or per shop).

---

3. Technical Implementation Notes

3.1 Hooks to Register

· actionProductPriceCalculation – to override the product price.
· displayProductPriceBlock – for the breakdown on the product page.
· displayCartExtraProductInfo – for the breakdown in the cart.
· displayAdminProductsExtra – to add the custom fields tab on the product edit page.
· actionProductSave – to save the custom product data from the POST.
· displayOrderDetail – to show breakdown in order history.

3.2 Database Schema

Provide at minimum the following tables (names prefixed with module identifier):

· <prefix>thejeweller_metals – id_metal, name, price_per_gram, active
· <prefix>thejeweller_diamond_qualities – id_quality, name, price_per_carat, active
· <prefix>thejeweller_gemstone_types – id_type, name, price_per_gram, active
· <prefix>thejeweller_stone_types – id_type, name, price_per_gram, active
· <prefix>thejeweller_product_config – id_product, id_shop, enable, id_metal, product_weight, making_charges
· <prefix>thejeweller_product_component – id_component, id_product, type (diamond/gemstone/stone), id_quality_or_type (foreign key to the respective table), weight, price_per_unit, total (or calculate on the fly)

3.3 Price Calculation Logic

In hookActionProductPriceCalculation, retrieve product config and components, compute the total, and set $params['price']. Take care of:

· Checking if custom pricing is enabled.
· Applying currency conversion.
· Handling $params['specific_price_reduction'] if needed.
· Performance: cache metal/stone prices in static variable to avoid repeated DB queries.

3.4 Front‑End Template

The module must include its own template files (.tpl for legacy, or Twig if hooks support it) and a minimal CSS file. The breakdown box should be a clean list or table, with classes that can be easily restyled by the theme.

---

4. Deliverables

1. Complete, well‑commented module source code, following PrestaShop coding standards.
2. A ZIP file ready for installation via the PrestaShop back office.
3. Installation instructions and a brief user manual (PDF) explaining:
· How to configure base prices.
· How to set up a product with jewellery pricing.
· How the frontend breakdown works.
4. SQL scripts for creating the required tables (should run automatically on module install) and for uninstall (optionally removing tables).
5. The module must be tested on a clean PrestaShop 9.1.0 installation with sample data.

---

5. Acceptance Criteria

1. Admin can add/edit/delete metal, diamond, gemstone, and stone prices.
2. When editing a product, the custom fields are present and data is saved correctly.
3. The product price on the frontend (catalog, product page, cart, checkout) reflects the jewellery formula, including metal + making charges + stones.
4. A price breakdown is displayed on the product page and in the cart.
5. All prices are correctly converted for multi‑currency setups.
6. The module does not cause any errors or warnings in PrestaShop debug mode.
7. No core file has been modified.