Repo comfac-webshop DataModel

Repo:comfac-webshop/DataModel — Data Model and DocTypes

Overview

comfac-webshop contains 11 core DocTypes that handle e-commerce functionality. The app creates a layer between ERPNext's inventory/accounting system and the customer-facing storefront.

Core DocTypes

Product Display

DocType	Purpose	Key Fields	Links To
Website Item	Products visible on storefront	item_code, web_item_name, website_image, published, route	Item (ERPNext), Item Group
Website Item Tabbed Section	Product page tabs (Specs, Reviews, etc.)	label, content	Website Item (child table)
Homepage Featured Product	Products featured on homepage	website_item, description	Website Item

Shopping Experience

DocType	Purpose	Key Fields	Links To
Wishlist	Customer saved items	customer, user	Customer
Wishlist Item	Individual wishlist entries	website_item, item_code	Wishlist, Website Item
Item Review	Product ratings/reviews	website_item, rating, review	Website Item, Customer
Recommended Items	"You may also like" suggestions	website_item, recommended_item	Website Item

Promotions & Settings

DocType	Purpose	Key Fields	Links To
Website Offer	Discounts and promotions	offer_type, discount_type, rate_or_discount	Item Group, Brand
Webshop Settings	Store configuration	enabled, price_list, default_company, show_stock_availability	Price List, Company

ERPNext DocTypes Used

Core Integration

DocType	Purpose in Webshop	Key Data Used
Item	Source product data	item_name, description, stock_uom, image, has_variants
Item Group	Product categories	item_group_name, parent_item_group, route
Quotation	Shopping cart storage	items[], customer, currency, taxes
Sales Order	Confirmed orders	Created from cart at checkout
Price List	Product pricing	item_prices[] with rates
Customer	Registered users	customer_name, customer_group, territory
Address	Shipping/billing	address_type, address_lines, city, country
Payment Request	Payment processing	amount, payment gateway

DocType Details

Website Item

The central DocType for storefront products:

Field	Type	Purpose
item_code	Link → Item	Links to ERPNext Item (source of truth)
web_item_name	Data	Display name on website (can differ from Item)
published	Check	Visibility toggle
route	Data	URL path (e.g., "/item/laptop-dell-xps")
website_image	Attach Image	Main product image
slideshow	Link → Website Slideshow	Multiple product images
short_description	Text	Brief summary
web_long_description	Text Editor	Full description (HTML)
website_specifications	Table	Key-value specs
tabs	Table → Website Item Tabbed Section	Tabbed content sections
on_backorder	Check	Stock availability messaging
website_warehouse	Link → Warehouse	Stock source location

Webshop Settings

Critical configuration DocType (single record):

Field	Type	Purpose
enabled	Check	Master on/off switch
price_list	Link → Price List	Pricing source
default_shopping_cart_company	Link → Company	For quotations
default_currency	Link → Currency	Display currency
show_quantity_in_website	Check	Show stock quantity
show_stock_availability	Check	Show "In Stock" badge
enable_wishlist	Check	Feature toggle
redirect_to_checkout_on_add_to_cart	Check	Behavior setting

Wishlist

Field	Type	Purpose
customer	Link → Customer	Associated customer
user	Data	User ID (for guest/anonymous tracking)
items	Table → Wishlist Item	Saved products

Item Review

Field	Type	Purpose
website_item	Link → Website Item	Product being reviewed
customer	Link → Customer	Reviewer
rating	Rating (1-5)	Star rating
review	Text	Written review
published	Check	Moderation status

Data Flow

Item → Website Item Sync

When an ERPNext Item is created/updated:

1. Event Trigger: doc_events.Item.on_update in hooks.py
2. Handler: webshop.webshop.crud_events.item.update_website_item.execute
3. Sync Logic: Creates or updates corresponding Website Item
4. Field Mapping: Item.item_name → Website Item.web_item_name (if empty)
5. Cache Invalidation: Clears product search cache

Cart Data Flow

Stage	Data Structure	Storage
Browse	Website Item	Database
Add to Cart	Quotation (Draft)	Database
View Cart	Quotation + Items	Quotation DocType
Checkout	Quotation + Address + Shipping	Quotation DocType
Place Order	Sales Order	Sales Order DocType
Payment	Payment Request + Entry	Payment DocTypes

Where DocType Definitions Live

File Path Pattern

webshop/webshop/doctype/[doctype_name]/[doctype_name].json

Example: webshop/webshop/doctype/website_item/website_item.json

Override DocTypes

Located at: webshop/webshop/doctype/override_doctype/

• item.py — Extends ERPNext Item with webshop-related methods
• item_group.py — Extends Item Group for website navigation
• payment_request.py — Custom payment flow handling

Common Query Examples

Get Published Website Items

items = frappe.get_all("Website Item",
    filters={"published": 1},
    fields=["name", "web_item_name", "website_image", "route"]
)

Get Cart Quotation for User

cart = frappe.get_all("Quotation",
    filters={
        "party_name": customer_name,
        "docstatus": 0,  # Draft
        "status": "Draft",
        "order_type": "Shopping Cart"
    },
    fields=["name"],
    limit=1
)

Get Product Reviews

reviews = frappe.get_all("Item Review",
    filters={
        "website_item": "ITEM-001",
        "published": 1
    },
    fields=["customer", "rating", "review", "creation"]
)

# Calculate average rating
avg_rating = sum(r.rating for r in reviews) / len(reviews) if reviews else 0

Get Wishlist Items

wishlist = frappe.get_doc("Wishlist", {"customer": customer_name})
items = [item.website_item for item in wishlist.items]

Database Conventions =

Table Naming

Frappe auto-generates:

• tabWebsite Item
• tabWebshop Settings
• tabWishlist

Stock Availability

Stock is checked via webshop.webshop.utils.product.get_web_item_qty_in_stock() which queries:

• tabBin (ERPNext stock levels)
• Respects website_warehouse filter if set

Pricing

Prices are fetched from ERPNext Price List:

• Uses tabItem Price
• Respects price_list in Webshop Settings
• Supports variant pricing

Related Pages

• Repo_comfac-webshop_Overview — Project overview
• Repo_comfac-webshop_DirectoryMap — Directory structure and key files
• Repo_comfac-webshop_EntryPoints — How the app starts
• Repo_comfac-webshop_ExtensionPoints — Hooks and customization points
• Repo_comfac-webshop_CommonEdits — Common edit recipes