chore: baseline import

2026-04-23 01:08:18 +08:00
commit c8ddfdf660
260 changed files with 117643 additions and 0 deletions
@@ -0,0 +1,88 @@
+# Product Templates
+
+## Intent
+Product detail pages support customizable templates. Editors should be able to pick a template per product. The site pulls template options by enumerating the directories under `webroot/Products/`.
+
+This lets product marketing teams build visually distinct product pages without rebuilding the platform each time, while still staying inside the brand visual system.
+
+## Template Directory Structure
+Each template lives under:
+
+```
+webroot/Products/<template-id>/
+```
+
+Each template directory must contain exactly three subdirectories:
+
+```
+webroot/Products/<template-id>/
+  assets/
+  zh/
+    index.html
+  en/
+    index.html
+```
+
+### Folder Roles
+- `assets/` — shared static resources for this template (images, videos, stylesheets, scripts).
+- `zh/index.html` — Chinese version of the rendered product page for this template.
+- `en/index.html` — English version of the rendered product page for this template.
+
+### Rules
+- The three folders `assets`, `zh`, `en` are required.
+- A template is considered valid only if both `zh/index.html` and `en/index.html` exist.
+- Asset references inside `index.html` should use paths relative to the template root, for example `./assets/hero.jpg`.
+- Template IDs are the directory names; they are used as the value stored in CMS.
+- Template IDs should be URL-safe (letters, digits, dashes, underscores).
+
+## Template Discovery Rule
+The build / CMS layer must enumerate `webroot/Products/*` inside this project and produce a list of valid template IDs. Product content entries in Payload reference one of these template IDs through a `template` field.
+
+### Validation
+- If a product references a template ID that no longer exists, the build should fail loudly rather than silently fall back.
+- If a template directory is missing `assets`, `zh/index.html`, or `en/index.html`, it must not be exposed as a selectable option.
+
+## CMS Field
+Each Product record in Payload has a `template` field:
+- Type: select
+- Source: dynamic enumeration of valid template directories under `webroot/Products/`
+- Required: true
+
+If the template list is empty, product pages fall back to the default system-rendered product layout.
+
+## Rendering Strategy
+When rendering a product detail page:
+1. Look up the product entry in Payload by slug.
+2. Read the `template` field.
+3. If a matching template exists in `webroot/Products/<template-id>/<locale>/index.html`, inject that HTML into the central product-body region inside the Next.js product route.
+4. Serve template assets from `/products-tmp/<template-id>/assets/...`.
+
+### Chrome Rules
+- Header, footer, language switch, and breadcrumb are always rendered by the main Next.js layout.
+- The template only owns the middle content region of the product detail page.
+- Templates do not need to include header or footer markup.
+- Templates must not override global navigation, language switch, cookie banner, or footer.
+
+### SEO
+- Page metadata (title, description, OG image, canonical, hreflang) comes from Payload, not from the template HTML.
+- Any `<head>` content inside the template HTML is ignored.
+- `h1` tags inside the template should stay unique per product.
+
+## Content Ownership
+- Template HTML and assets: created by design / marketing team.
+- Template selection: owned in CMS per product.
+- Product metadata (title, slug, hero image, summary, downloads, videos, reviews, SEO, related products): always managed in CMS, never hardcoded inside the template.
+- Product detail pages must continue to render CMS-managed downloads, videos, and reviews outside the template-owned middle body region.
+
+## Naming Guidance
+- `template-id` should describe the layout intent, not a specific product. Good examples: `editorial-01`, `immersive-hero`, `split-feature`. Avoid product-specific names like `a10-page`.
+
+## Workflow
+1. Designer or marketing team adds a new template directory into this project's `webroot/Products/`.
+2. Build pipeline enumerates available templates and updates the CMS select options.
+3. Editor picks the template on a Product entry.
+4. Page publishes with the selected template.
+
+## Open Questions
+- Whether templates can depend on external CDN assets, or must be fully self-contained within `assets/`.
+- Whether templates support a lightweight preview environment in CMS.