x

ADMIN_MCP_SECTION_GUIDE.md

@@ -0,0 +1,220 @@
+# HomAroma Admin Section Guide
+
+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
+- 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.