website/SCHEMA-PRODUCT.md

Payload Schema — Product Collection (Final)

Purpose

Single source of truth for the Product collection in Payload. This is the version that will be implemented in code. All product detail pages (system-rendered layout and project-local HTML templates) depend on this schema.

Collection Slug

products

Localization

• Locales: en, zh
• Each locale can be edited and published independently.
• Fields marked localized below use Payload field-level localization.
• Fields marked shared are global and the same across locales.

Access Control

• Public read: only documents with status = published.
• Write: authenticated editors and above.
• Admin-only fields: seo.noIndex, template, firmware.showOnProductPage, firmware.showInDownloadsCenter.

Status Workflow

• draft
• review
• published
• archived

Fields

1. Identity

• slug — localized — text, required, unique per locale, URL-safe.
• model — shared — text, required. The marketing model name, for example DMP-A10.
• status — shared — select, required, one of draft | review | published | archived.
• order — shared — number, default 0. Used for manual ordering inside category listings.
• category — shared — relationship to productCategories, required.

2. Template Selection

• template — shared — select, required, options dynamically enumerated from valid directories under webroot/Products/. If no templates exist, the UI falls back to the default system-rendered layout.
• templateEnabled — shared — checkbox, default false. When true, the product detail route injects the HTML template into the middle content region. When false, the default system-rendered layout is used even if a template is selected.

3. Marketing Copy (localized)

• name — localized — text, required. Display name shown in cards and headings.
• tagline — localized — text. One-line descriptor used in product cards and hero.
• summary — localized — rich text. Short paragraph used on overview pages.
• overview — localized — rich text. Longer intro used in the system-rendered layout.

4. Media

• heroImage — shared — upload, required. Used in the top of default-rendered product pages and as card image.
• cardImage — shared — upload, optional. Optional override for the featured product card. Horizontal composition preferred to align with homepage visual spec.
• gallery — shared — array of uploads, optional. Ordered product imagery.
• lifestyleImage — shared — upload, optional. Used for lifestyle placement in listings or cross-links.
• heroVideo — shared — group, optional.
  • src — upload or URL.
  • poster — upload.

5. Key Features (localized content, shared structure)

keyFeatures — array, 0 to 8 items. Per item:

• icon — shared — upload, optional.
• image — shared — upload, optional.
• title — localized — text, required.
• description — localized — rich text.

6. Technology Highlights (localized)

technologyHighlights — localized — rich text with blocks. Allowed blocks:

• textBlock
• imageTextBlock
• quoteBlock

7. Specifications

specifications — array of spec groups. Per group:

• groupName — localized — text, required.
• order — shared — number, default 0.
• items — array.
  • label — localized — text, required.
  • value — localized — text, required.
  • note — localized — text, optional.

8. Firmware (display is opt-in)

firmware — group.

• showOnProductPage — shared — checkbox, default false. Controls whether firmware is displayed on the product detail page.
• showInDownloadsCenter — shared — checkbox, default false. Controls whether this product's firmware appears in the site-wide Downloads center.
• displayLabel — localized — text, optional. Overrides the default section title on the product page.
• items — relationship to downloads, filtered to type = firmware, multi-select, ordered.
• notes — localized — rich text, optional. Release notes or compatibility notes rendered above the list.

UI rules:

• The two visibility toggles are independent. Either can be on or off without affecting the other.
• items and notes are edited independently of the toggles; disabling both toggles hides firmware from public UI but preserves data.
• Payload UI should clearly show current visibility status on each product record.

9. Downloads (non-firmware)

downloads — group.

• manuals — relationship to downloads, filtered to type = manual, multi-select.
• software — relationship to downloads, filtered to type = software, multi-select.
• other — relationship to downloads, filtered to type = other, multi-select.

These are always available on the product page when entries exist. The firmware module is separated because its visibility is opt-in.

10. Relations

• relatedProducts — relationship to products, multi-select, up to 4.
• accessories — relationship to products, multi-select, optional.
• featuredDealers — relationship to dealers, multi-select, optional.

11. Awards and Reviews (optional on detail page)

awards — array, optional. Per item:

• logo — shared — upload.
• label — localized — text.
• year — shared — number.
• url — shared — URL, optional.

reviews — array, optional. Per item:

• sourceLogo — shared — upload, optional.
• sourceName — localized — text.
• quote — localized — text, required.
• url — shared — URL, optional.

12. SEO

seo — group, localized.

• title — text, max 70 chars.
• description — textarea, max 160 chars.
• ogImage — upload.
• canonical — text, optional.
• noIndex — checkbox, admin-only, default false.

13. Timestamps (auto)

• createdAt
• updatedAt
• publishedAt

Hooks

• beforeValidate:
  • Normalize slug (lowercase, trim, ASCII fallback, dashes).
• beforeChange:
  • Auto-set publishedAt when status transitions to published for the first time.
  • If template refers to a non-existent directory, reject with a validation error.
• afterChange:
  • Trigger on-demand revalidation for /en/products, /zh/products, /en/products/<slug>, /zh/products/<slug>.
  • Trigger revalidation for Homepage if the product is part of Homepage.featuredProducts.

Admin UI Layout (recommended tabs)

1. Overview — identity, status, template, name, tagline, summary, category, order.
2. Content — overview, keyFeatures, technologyHighlights, specifications.
3. Media — heroImage, cardImage, gallery, lifestyleImage, heroVideo.
4. Firmware — firmware group.
5. Downloads — downloads group.
6. Relations — relatedProducts, accessories, featuredDealers.
7. Recognition — awards, reviews.
8. SEO — seo group.

Rendering Rules (summary)

• If templateEnabled is true and template resolves to a valid directory, render:
  • Header (from main layout)
  • Breadcrumb (from main layout)
  • Optional hero block (from CMS)
  • Middle content region populated by webroot/Products/<template>/<locale>/index.html
  • Firmware module (only if firmware.showOnProductPage)
  • Related downloads, related products, recognition (if present)
  • Footer (from main layout)
• Otherwise, render the default system-rendered layout using the structured fields above.
• The site-wide Downloads center lists firmware entries only for products with firmware.showInDownloadsCenter = true.

Validation Rules

• slug must be unique per locale.
• model required.
• category required.
• heroImage required.
• template required; must reference an existing directory.
• firmware.items must all have type = firmware.
• awards[].year must be between 1990 and current year + 1.
• At least one locale must have status = published before the product is publicly visible.

Open Items

• Whether status should be a per-locale field to allow a product to go live in EN before ZH.
• Whether templateEnabled toggle is visible to all editors or admin-only.
• Whether recognition (awards, reviews) should also live at brand level, not just per product.