homaroma/ADMIN_MCP_SECTION_GUIDE.md

DBK Platform Admin Section Guide

Platform scope: This guide describes shared CMS administration capabilities. Product and content examples are tenant-specific; HomAroma is the reference tenant. See docs/PLATFORM_OVERVIEW.md.

This guide explains the dynamic page blocks available in the Page Builder and what each block contains.

Field Shape Legend

• localized string = plain text or { th, en, ja, zh, vi, ko }
• plain string = one string only
• optional = can be omitted

Available Blocks

HERO

• Purpose: Main hero banner for a page
• Contains:
  • tagline localized string
  • title localized string
  • description localized string
  • imageUrl plain string
  • buttonText localized string
  • buttonLink plain string
• Best for: Landing pages, featured campaigns, page introductions

BANNER

• Purpose: Image banner with optional CTA
• Contains:
  • imageUrl plain string
  • linkUrl plain string
  • title localized string optional
  • description localized string optional
  • buttonText localized string optional

TEXT

• Purpose: Simple content block
• Contains:
  • title localized string optional
  • content localized string
  • textAlign plain string optional: left, center, right

ANNOUNCEMENT_BAR

• Purpose: Rotating announcement strip
• Contains:
  • slides array of localized strings
  • backgroundColor plain string optional
  • textColor plain string optional
  • speed number optional

NEWSLETTER

• Purpose: Newsletter signup panel
• Contains:
  • title localized string
  • description localized string
  • buttonText localized string
  • placeholderText plain string optional
  • showPrivacyCheckbox boolean
  • privacyText plain string optional

EDITORIAL_TILE

• Purpose: Side-by-side editorial story tile
• Contains:
  • title localized string
  • description localized string
  • imageUrl plain string
  • imagePosition plain string: left or right
  • buttonText plain string optional
  • buttonLink plain string optional
  • backgroundColor plain string optional
  • textColor plain string optional

EDITORIAL_CAROUSEL

• Purpose: Multi-slide editorial storytelling block
• Contains:
  • title localized string
  • slides array of:
    • category localized string
    • title localized string
    • description localized string
    • imageUrl plain string
    • buttonText plain string optional
    • buttonLink plain string optional

PRODUCTS

• Purpose: Product list/grid section
• Contains:
  • title localized string
  • subtitle localized string optional
  • type plain string: featured, scent, or custom
  • scentId number optional
  • productIds number array optional
  • limit number optional
  • layout plain string optional: grid or carousel
  • enableQuickShop boolean optional

CATEGORIES

• Purpose: Category showcase block
• Contains:
  • title localized string
  • subtitle localized string optional
  • categoryIds number array optional

HERO_ARTICLE

• Purpose: Editorial hero/article header
• Contains:
  • title localized string
  • subtitle localized string optional
  • author localized string optional
  • category localized string optional
  • publishDate plain string optional
  • date plain string optional
  • imageUrl plain string
  • backgroundImageUrl plain string optional
  • overlayColor plain string optional
• Notes:
  • The image is set by entering an image URL in imageUrl
  • In the Admin UI, the image picker stores the URL for you

RICH_TEXT

• Purpose: Flexible HTML/text content block
• Contains:
  • title localized string optional
  • content localized string required
• Notes:
  • HTML is allowed
  • Use language tabs to translate each version

SCENT_NOTES_BREAKDOWN

• Purpose: Fragrance layer breakdown (reference tenant vertical block; pattern for multi-tier attribute breakdowns)
• Contains:
  • title localized string optional
  • description localized string optional
  • topNotes array of strings or localized string objects
  • heartNotes array of strings or localized string objects
  • middleNotes array of strings or localized string objects
  • baseNotes array of strings or localized string objects
• Notes:
  • heartNotes and middleNotes are mirrored together by the backend

QUOTE_CALLOUT

• Purpose: Highlighted quote block
• Contains:
  • quote localized string required
  • author localized string optional
  • role localized string optional

PRODUCT_CAROUSEL

• Purpose: Featured product carousel
• Contains:
  • title localized string optional
  • description localized string optional
  • collectionId plain string optional
  • limit number optional
  • showPrice boolean optional
  • showAddToCart boolean optional
  • products optional explicit product list
• Notes:
  • If products is omitted, the backend can auto-populate products on read-back

ACCORDION

• Purpose: FAQ-style expandable block
• Contains:
  • title localized string optional
  • categories required array
    • each category has:
      • name localized string
      • icon plain string optional
      • questions required array
        • each question has:
          • q localized string
          • a localized string

CONTACT_INFO

• Purpose: Contact details block
• Contains:
  • title localized string optional
  • address localized string required
  • email plain string required
  • line plain string required
  • hours localized string required

CONTACT_FORM

• Purpose: Contact form header block
• Contains:
  • title localized string optional
  • subtitle localized string optional
• Notes:
  • This block has no extra fields beyond title and subtitle

Recommended Admin Workflow

1. Create or open a page.
2. Add blocks in the order you want them rendered.
3. Fill localized fields per language.
4. Use the media picker or image URL fields for image-based blocks.
5. Save the block, then verify the rendered page.

Quick Tips

• Use HERO_ARTICLE for editorial-style stories.
• Use RICH_TEXT for long-form content.
• Use SCENT_NOTES_BREAKDOWN for fragrance layer storytelling.
• Use PRODUCT_CAROUSEL when you want featured products without manually listing each one.
• Use ACCORDION for FAQ content.
• Use CONTACT_INFO and CONTACT_FORM together for contact pages.