Files
web-alterflixhub/DESIGN.md
T
Bkk1234 1cf1398ba4 feat(admin): รองรับตัวกรองประเภทโรงหนังเต็มรูปแบบ
- ลิสต์โรงหนัง: ช่องค้นหา (ไทย/อังกฤษ/slug) + ชิปกรองประเภทพร้อมจำนวน (ทั้งหมด/ท้องถิ่น/อินดี้/กลุ่ม/ยังไม่จัด)
- ป้ายประเภทท้ายชื่อทุกแถว (ยังไม่จัด = ป้ายแดง) + empty state
- ตั้งประเภททีละกลุ่ม: "ตั้งประเภทให้ N โรงที่กรองอยู่" → เลือกประเภท → ใช้ (แล้วกดบันทึกทั้งหมด)
- หัวหลังบ้านสรุปจำนวนต่อประเภท
- แท็บคำศัพท์: ปุ่มลัดสร้าง key `venues.<ประเภท>` สำหรับแปลชื่อตัวกรอง
- ปิดลากสลับลำดับขณะกรอง + hint อธิบาย
- logic ย้ายไป lib: filterAdminCinemas / setVenueForSlugs / venueCounts + unit tests (169 ผ่าน)
- DESIGN.md / docs/admin-guide.md อัปเดต
2026-11-16 01:54:15 +07:00

59 KiB
Raw Blame History

Visual Design Contract

AGENTS.md is the canonical statement of the blank-canvas rule — check app/routes/_index.tsx and app/global.css, preserve any real UI/brand already there, and only treat the canvas as blank when those files still show the starter's placeholder. This file does not restate that rule; it records this app's visual direction. The fields below are the source of truth for that direction: once filled in, read and preserve them on every build; while they are still empty, the first substantial UI pass fills them in.

Non-negotiable: impress by default

When this app is still a blank canvas, every app generated from this template must look spectacular on first load, even when the build prompt gives no design direction. "Looks like a clean, intentional product" is the floor, not the goal. When no direction is supplied, you still commit to one — do not default to safe gray SaaS:

  • Commit to one concrete visual world (see the frontend-design skill and its references/visual-direction.md). Do not ship the neutral placeholder theme.
  • Choose a product-fitting accent family and set it in the app/global.css tokens for both light and dark. Never leave the 0%-saturation default as the shipped palette.
  • Establish a clear type hierarchy, a consistent spacing rhythm, and one signature detail (a considered empty state, a distinctive header, a crafted primary action) that makes the surface feel designed for its domain.
  • Get focus, hover, empty, loading, and dark-mode states right — that polish is the difference between an AI demo and a product.

Pick a direction and execute it fully; never average toward generic SaaS. Once a direction is established and recorded below, preserve and extend it rather than starting over unless otherwise directed to.

Fill in before building the first surface

Once the fields below are filled in, they describe this app's established visual direction — read and preserve them on every subsequent build; do not re-derive a new direction. The first UI pass must fill these fields in as part of that build, not leave them as an empty template.

  • Product mode: experience
  • Audience and cadence: Thai moviegoers browsing independent cinemas; occasional discovery.
  • Visual world (name + the feeling it creates): Dim indie screening room — friendly, warm, a little playful (pixel-style logo, rounded chips and cards).
  • Palette family + neutral undertone: Cinema crimson (#8F0808 / #A92626 / #D47272) on near-black neutrals (#0D0D0D, #1B1B1B, #242424) with a slight warm cast.
  • Type treatment: Inter + Noto Sans Thai; Jersey 15 pixel face for the AlterFlixHub wordmark only. เนื้อความยาว (บทความ/ย่อหน้าอ่านต่อเนื่อง เช่นหน้า /about) ใช้ font-content = IBM Plex Sans Thai Looped (มีหัว, 400/500) — หัวข้อและ UI ยังเป็น Inter + Noto Sans Thai ตามเดิม
  • Composition: Full-bleed hero with crimson glow, centered glass search box, 4-column card grid at 1224px max.
  • Shape language: Soft radii (8px controls, 18px pills, 16-20px cards), frosted-glass panels.
  • Anti-references (defaults this app must not drift toward): Gray SaaS dashboards, light themes, neon gradients, heavy chrome.

โลโก้ (ห้ามเปลี่ยนแปลง — ห้ามตีความใหม่)

สเปกนี้เป็นข้อบังคับ ใช้กับทุกหน้าและทุกภาษาที่รองรับ:

หัวข้อ ค่าที่กำหนด
คำ AlterFlixHub — ตัวสะกด/ตัวพิมพ์นี้เท่านั้น (ไม่ ALL CAPS, ไม่เว้นวรรค, ไม่แปล)
ฟอนต์ Jersey 15 เท่านั้น ห้ามใช้ Inter หรือฟอนต์อื่นแทน
น้ำหนัก/สไตล์ ตามฟอนต์ดั้งเดิม — ห้ามใส่ bold/italic/uppercase/letter-spacing/เงา/ไล่สี
สี #8F0808 เท่านั้น (ทุกสถานะ รวม hover/active)
ขนาด header (navbar) text-4xl = 36px
ขนาด footer text-2xl = 24px
ตำแหน่ง header: element แรก ชิดซ้ายสุด และคลิกกลับหน้าแรกได้ · footer: ซ้ายสุดของแถว
  • ไม่อนุญาตให้เพิ่มขนาดที่สาม หรือเปลี่ยนสี/ฟอนต์แม้ในสถานะ hover/active
  • ใช้ Logo เป็นข้อความแทนช่องรูปที่ยังไม่มีในแกลเลอรีหน้าโรงหนัง (Gallery) — ช่องหลัก size="md" (36px), ช่องย่อย size="sm" (24px) เท่านั้น; ข้อความ alt ยังใช้ gallery.main/second/third เพื่อการเข้าถึง
  • การเปลี่ยนใด ๆ ต้องได้อนุมัติจากเจ้าของโปรเจกต์ก่อน แล้วอัปเดตพร้อมกันทั้งตารางนี้, LOGO_SPEC (app/lib/design-tokens.ts) และ app/components/site/Logo.spec.ts
  • ตัวบังคับเชิงโค้ด: Logo อ่านค่าจาก LOGO_SPEC ผ่าน logoClasses() — ถ้ามีคนแก้สเปก เทสต์ Logo.spec.ts จะพังทันที

Layout contract (บังคับ)

  • หน้าเว็บจบที่ footer เสมอ: SiteShell เป็น flex flex-col min-h-dvh + เนื้อหาอยู่ใน flex-1 (block ไม่ใช่ flex-col เพื่อไม่ให้ main ที่มี mx-auto หดเป็น max-content)
  • ของตกแต่งพื้นหลัง (รูปฮีโร่, gradient, glow) ต้องอยู่ใน BackdropFrame = absolute inset-0 overflow-hidden เสมอ — ถ้าปล่อยเป็น absolute ลอย ๆ ที่ใช้ top-[…px]/bottom ค่าเยอะ ๆ จะยืด scrollHeight ให้ยาวเกินเนื้อหา ทำให้มีพื้นที่ว่างเลื่อนได้ใต้ footer
  • แสงที่ต้องอยู่ช่วงล่างของหน้าให้ยึด bottom-* ไม่ใช่ top-[px] ตายตัว เพราะความสูงหน้าเปลี่ยนตามจำนวนการ์ดที่แสดง

Motion contract (บังคับ)

  • ทุกอนิเมชันใช้ transform / opacity เท่านั้น (ห้าม width/height/top/left) · ตัวแปร: --fx-fast 160ms, --fx-base 280ms, --fx-page 460ms, --fx-slow 640ms, --fx-ease-out cubic-bezier(0.16,1,0.3,1) · หน่วงต่อชิ้นไม่เกิน ~240ms

  • การเปิด/ปิดอนิเมชันมีสองชั้น — ต้องมีทั้งคู่:

    1. สถานะ "ซ่อนก่อน reveal" ผูกกับ html.fx-motion [data-reveal]{opacity:0} — คลาสนี้ใส่โดยสคริปต์ใน <head> (MOTION_INIT_SCRIPT) และเติมซ้ำโดย <MotionBootstrap/> (effect ฝั่ง client) เพราะพบว่า hydration เขียนทับ class ของ <html> ทำให้คลาสหลุด
    2. ตัวอนิเมชัน ผูกกับ @media (prefers-reduced-motion: no-preference) ไม่ใช่คลาส → ถ้าคลาสหลุดอีก อนิเมชันก็ยังทำงาน และถ้าผู้ใช้ขอ reduced motion ทุกอย่างนิ่ง+เห็นครบ
  • ห้ามย้ายตัวอนิเมชันกลับไปผูกกับ html.fx-motion อย่างเดียว (เคสจริง: อนิเมชันหายทั้งเว็บหลัง hydration ลบคลาส)

  • hover ของการ์ดใช้ translate (Tailwind hover:-translate-y-1) ไม่ใช้ transform เพราะชนกับ keyframe ของ reveal · .fx-swap (แกลเลอรี) ใช้ @keyframes fx-swap-in — ห้ามลบ keyframes นี้

  • สรุปตำแหน่งโค้ด: @keyframes + สถานะซ่อน + media query อยู่ใน app/global.css ท้ายไฟล์ (fx-*) · สคริปต์ตั้งต้นอยู่ app/lib/motion.ts · ตัวเติมคลาสซ้ำคือ <MotionBootstrap/> ใน app/root.tsx

  • "ค่อย ๆ โผล่เมื่อเลื่อนถึง" ใช้ useReveal (app/hooks/use-reveal.ts) หรือ <Reveal> (app/components/site/Reveal.tsx) — มีกฎกันค้างซ่อน: บล็อกที่เลื่อนผ่านไปแล้ว (หรือถูกข้ามด้วยการกระโดด scroll) ต้องโผล่ทันที

  • hover ของการ์ดใช้ translate (Tailwind hover:-translate-y-1) ไม่ใช้ transform เพราะชนกับ keyframe ของ reveal · ทุกอนิเมชันต้องมีคู่มือปิดใน @media (prefers-reduced-motion: reduce)

PWA & accessibility contract (บังคับ)

  • ติดตั้งได้: <link rel="manifest"> อยู่ใน app/root.tsx (ห้ามลบ) · public/manifest.json ต้องมี display: standalone, id, scope, start_url: "/", lang และไอคอน PNG 192/512 + maskable 512 (Chrome ไม่รับ SVG, iOS ไม่รับ SVG) · apple-touch-icon ต้องชี้ icon-180.png
  • ไอคอน: ไฟล์จริงคือ public/icon-192.png / icon-512.png / icon-maskable-512.png / icon-180.png (สร้างจาก PNG 1024 ที่ฝังอยู่ใน icon-512.svg) — SVG เดิมเหลือไว้เป็น favicon เท่านั้น
  • service worker: public/sw.js — หน้าเว็บ network-first (ออฟไลน์ → แคชหน้า → offline.html), static cache-first + revalidate เบื้องหลัง, ไม่แคช /api/* และไม่แตะ /app/* /node_modules/* /@* (โมดูล dev) · ลงทะเบียนผ่าน app/lib/pwa.ts + <ServiceWorkerSetup/> ใน root.tsx
  • ทุกครั้งที่ปล่อยเวอร์ชัน ให้ bump VERSION ใน public/sw.js — activate จะลบแคชที่ไม่ตรงเวอร์ชัน (เคสจริง: แคช alterflixhub-v1.2.0 ค้างหลังลบไฟล์ sw ออก ทำให้หน้าเว็บเสิร์ฟของเก่า)
  • ห้ามปิดการซูม: viewport ต้องเป็น width=device-width, initial-scale=1 เท่านั้น (WCAG 1.4.4)
  • contrast ที่วัดจริง (พื้น #0D0D0D): #B3B3B3 9.27 · #D47272 5.97 · #A92626 = 2.77 → ห้ามใช้กับตัวอักษร (ใช้ได้เฉพาะเส้นขอบ/พื้น) · placeholder ช่องค้นหาใช้ #8A8A8A (4.77 บน #1F1F1F) ไม่ใช่ #454545 (1.72)
  • hit area ≥ 44px: ปุ่มที่หน้าตาเล็กกว่า (ใกล้ฉัน 20px, TH/EN 26px, chip 38px, ลูกศรแกลเลอรี 40px) ขยายด้วย after:absolute after:-inset-* — ห้ามเปลี่ยนความสูงที่มองเห็นเพื่อเพิ่ม hit area

Cross-engine parity (Chromium / Firefox / Safari) — บังคับ

เป้าหมาย: Firefox และ Safari ต้องดู/รู้สึกใกล้ Chromium ที่สุด โดยไม่ต้องมี build แยก · กฎทั้งหมดอยู่ใน app/global.css หัวข้อ "ความเท่ากันข้ามเอนจิน"

  • สำคัญ: ต้องอยู่ใน @layer base — CSS ที่ไม่ใส่ layer จะชนะ utility ของ Tailwind ทั้งหมด (เคสจริง: input { font-size: 16px } แบบ unlayered ทับ text-sm ทำให้ desktop กลายเป็น 16px)
  • สกรอลบาร์: Chromium/Safari ใช้ ::-webkit-scrollbar (5px, --muted-foreground/0.22) · Firefox ไม่รู้จัก → ต้องมี scrollbar-width: thin + scrollbar-color คู่กันเสมอ · ห้ามลบฝั่งใดฝั่งหนึ่ง
  • color-scheme: dark บน <html> — ทำให้ select/scrollbar/ฟอร์มเนทีฟ/autofill เป็นโทนเข้มทุกเอนจิน
  • ::selection ต้องประกาศเอง (#A92626 พื้น, ตัวอักษรขาว) — ไม่งั้นได้สีฟ้าตาม OS ซึ่งคนละเฉดในแต่ละเอนจิน
  • ::-moz-focus-inner reset (border:0; padding:0) สำหรับ button/input
  • mask-image ต้องมีทั้ง -webkit-mask-image (Safari) และ mask-image (Firefox/Chromium)
  • <details>/<summary>: ซ่อน marker ด้วย list-none (Firefox) และ [&::-webkit-details-marker]:hidden (Chromium/Safari)
  • backdrop-blur: งบไม่เกิน 24px ต่อชั้น (hero เดิม 32px) · -webkit-backdrop-filter มาจาก Tailwind เอง ไม่ต้องเขียนเพิ่ม · ระวัง position: sticky + blur บน iOS (อาจกระพริบ)
  • iOS Safari: ฟอร์มทุกช่องต้อง ≥16px บนมือถือ (text-base sm:text-sm) ไม่งั้นเบราว์เซอร์ซูมหน้าเองเมื่อโฟกัส — ห้ามแก้ด้วย user-scalable=no (ผิด WCAG 1.4.4) · input[type=search] ต้อง appearance: none (iOS ใส่กรอบ/มุมโค้งเอง) · -webkit-tap-highlight-color: transparent และ -webkit-text-size-adjust: 100%
  • ห้ามใส่ -webkit-font-smoothing — ไม่มีผลใน Firefox และทำให้ความต่างชัดขึ้น
  • สิ่งที่ต่างโดยธรรมชาติ ไม่ต้องแก้: Firefox ไม่มี navigator.share / install prompt · Safari ไม่มี install prompt (beforeinstallprompt ไม่มี แต่ display: standalone ใน manifest ทำให้ติดตั้งจากเมนูแชร์ได้) · iOS ล้าง cache ของ SW เมื่อไม่ใช้งาน 7 วัน (ITP) · inertia การเลื่อนต่างกัน
  • ทดสอบ: /, /cinema/<slug>, /for-cinemas, /admin ในทั้งสามเอนจิน — สกรอลบาร์/select/<details>/ปุ่ม/ขนาดช่องค้นหาต้องเท่ากัน (มือถือ 16px, เดสก์ท็อป 14px)

ข้อยกเว้นต่อเบราว์เซอร์ (exception list — ตั้งใจปล่อยไว้)

เรื่อง Chromium Firefox Safari สิ่งที่ทำ
ความกว้างสกรอลบาร์ 5px (::-webkit-scrollbar) ได้แค่ thin (~8px) — scrollbar-width ไม่รับ px overlay (ไม่แสดงถ้าไม่เลื่อน) ยอมรับความต่างเล็กน้อย
สีสกรอลบาร์ตอน hover เปลี่ยนได้ (::-webkit-scrollbar-thumb:hover) ไม่ได้ (ไม่มี pseudo-element ของ scrollbar) ไม่ได้ ปล่อย
ปุ่ม X ในช่องค้นหา ซ่อนได้ (::-webkit-search-cancel-button) ซ่อนไม่ได้ → FF แสดง X เอง แสดง X เอง ปล่อย (เป็น UI ของเบราว์เซอร์)
navigator.share ✅ (Windows/Android) ❌ เดสก์ท็อป ✅ ดีที่สุด fallback คัดลอกลิงก์
PWA install prompt ✅ beforeinstallprompt ❌ ❌ (ติดตั้งผ่านเมนูแชร์) ไม่พึ่ง event นี้
backdrop-filter เร็ว ช้ากว่ามาก กลาง จำกัด blur ≤ 24px
ฟอนต์ไทย (shaping) ต่างจาก FF เล็กน้อย ต่างจาก Chromium เล็กน้อย ต่างที่สุดถ้าไม่มี Noto ยอมรับ — ทางแก้คือ self-host subset
dvh ✅ 101+ 15.4+ ใช้ได้ แต่ถ้าต้องรองรับเก่ากว่านี้ต้องมี 100vh สำรอง
cache ของ SW คงอยู่จน bump VERSION คงอยู่ ถูกล้างหลังไม่ใช้งาน 7 วัน (ITP) ยอมรับ

Agent-Native is structural, not visual

This shell already meets the Agent-Native contract: data in SQL, actions as the single source of truth, application state for navigation/selection, and real-time sync. Chat and the agent rail are opt-in, not default. Build the product UI first. Add an AgentSidebar, a full-page chat route, or sendToAgentChat handoffs only when the user asks for agent interaction — and when you do, follow agent-native-toolkit and frontend-design → Agent Surface And Page Boundaries so the surfaces are wired correctly.

Guardrails

  • Keep semantic token names and shared component seams intact; express the direction through token values, type, spacing, and composition — not by forking the design system.
  • Density comes from data, not prose. Subtract explanatory chrome; never subtract the visual craft that makes the app impressive.
  • Compare against real products in the chosen mode, not against the starter.

Code map

Single source of truth per concern — do not duplicate these:

  • app/lib/cinemas.ts — ข้อมูลโรงหนัง + ฟังก์ชันกรอง/ค้นหา (filterCinemas, matchesQuery, findCinemaBySlug, formatDistance)
    • การค้นหา (filterCinemas) เป็นแบบ ทุกคำต้องเจอ (AND) เรียงสลับได้ และค้นทุกอย่างที่ผู้ใช้เห็นบนการ์ด: name / name_th / slug / location_label(+_en) / address_lines(+_en) / ทางเดินทาง / tag + ป้ายหมวดตามภาษา / คำอธิบาย — ต้องส่ง tagLabels: messages.tags เข้ามาด้วย ไม่งั้นค้นคำหมวดภาษาอังกฤษไม่เจอ
    • ข้อความผ่าน normalizeSearchText (NFKC, ตัดอักขระล่องหน, ตัวพิมพ์เล็ก, แปลงตัวคั่นเป็นช่องว่าง) และ foldSearchText (ตัดวรรณยุกต์/สระบน-ล่าง) → "Française" = "francaise", "เฮ้าส์" = "เฮาส", พิมพ์ไม่ครบก็เจอ
    • ผลลัพธ์เรียงตามความตรง: ชื่อเท่ากัน 3 · ชื่อขึ้นต้นด้วยคำ 2 · ชื่อมีคำอยู่ข้างใน 1.2 · หมวด/สถานที่/รายละเอียดน้ำหนักต่ำกว่า (คะแนนเท่ากันคงลำดับเดิม)
    • ปุ่ม "ค้นหา"/Enter ไม่ได้ทำหน้าที่กรอง (กรองสดทุกคีย์อยู่แล้วใน onChange) — อยู่ใน <form role="search"> เพื่อ preventDefault (กันหน้าโหลดใหม่) + blur() ปิดคีย์บอร์ดมือถือ + scrollIntoView() ไปที่หัวข้อผลลัพธ์ (scroll-mt-[88px], เคารพ prefers-reduced-motion) · ห้ามเปลี่ยนปุ่มนี้เป็น type="button" เฉย ๆ (จะกลับไปเป็นปุ่มหลอก)
  • app/lib/design-tokens.ts — ค่าสีจาก Figma สำหรับ inline style (Tailwind class ยังเป็น literal เสมอ)
  • app/lib/i18n/ — messages.ts (ข้อความ TH/EN ทั้งหมด คีย์หมวดหมู่/tag/ชำระเงิน/สิ่งอำนวยความสะดวก), index.tsx (LocaleProvider, useI18n, cookie locale)
  • ข้อความทุกคำใน UI ต้องมาจาก messages ไม่ hardcode ใน component · หมวดหมู่และ tag เก็บคีย์เป็นภาษาไทยเสมอ (ใช้กรองข้อมูล) แล้วแปลด้วย messages.categories / messages.tags
  • ระวัง: ข้อความอาจถูก override จากหลังบ้าน — data/content/content.json → site.terms[] เก็บ { key, values: { th, en } } (dot path เช่น list.showMore) และ ทับค่าใน messages.ts · แก้คำบนหน้าเว็บแล้วไม่เปลี่ยน → ตรวจ term ตัวนั้นก่อน (แท็บ "คำศัพท์หลายภาษา") · เวลาเปลี่ยนข้อความตั้งต้นให้แก้ทั้ง messages.ts และ term ที่มีอยู่ (หรือลบ term ทิ้งเพื่อให้ใช้ค่า defaults)
  • ข้อความอังกฤษของเนื้อหาโรงหนังเป็นฟิลด์เสริม location_label_en / description_en / address_lines_en / value_en — ไม่กรอกก็ fallback ไทย · ชื่อไทยใช้ name_th (+ helper cinemaName(cinema, locale)), ไม่กรอกก็แสดงชื่ออังกฤษ
  • <title> ของหน้ารายละเอียดสร้างจาก loader ของ route เอง (meta({ loaderData }) — เวอร์ชันนี้ส่ง loaderData ไม่ใช่ data)
  • <head> (title/description) ไม่เปลี่ยนตามภาษา; ภาษาเริ่มต้นเลือกตามลำดับ ?lang= → localStorage → cookie → ไทย (resolveInitialLocale) — ตั้งใจไม่ใช้ navigator.language เพราะเว็บไทย-first
  • สลับภาษาได้ 2 ทาง: ปุ่มภาษาที่ header (ปุ่มเดียว + dropdown TH/EN — ดูหัวข้อตัวสลับภาษาด้านล่าง) หรือลิงก์ ?lang=en ที่บังคับภาษาและ SSR ใส่ <html lang> ถูกต้อง
  • การเลือกถูกเก็บทั้ง cookie และ localStorage (รองรับเบราว์เซอร์ที่บล็อกคุกกี้) และซิงก์ข้ามแท็บผ่าน storage event
  • app/components/site/ — โครงร่วม: SiteShell (flex column + min-h-screen, เนื้อหา flex-1 เพื่อดัน footer ไปท้ายจอ), SiteHeader, SiteFooter (ความกว้างเนื้อหา cap ที่ 1016px เท่าคอลัมน์ฮีโร่ ไม่ยืดตามกริดการ์ด), Logo, CinemaCard, CinemaGrid + CategoryFilter
  • ปุ่มแชร์ (app/components/site/ShareButton.tsx + app/lib/share.ts)
    • ลิงก์สร้างจาก origin ของ request (root loader คืน siteUrl → ShareOriginProvider) + พาธย่อ /c/<slug> — ไม่ฝังโดเมนในโค้ด และไม่ต้องตั้ง env
    • /c/<slug> (app/routes/c.$slug.tsx) เป็น 302 redirect ไป /cinema/<slug> — ลิงก์สั้นพอแปะในแชท แต่ไม่มีเนื้อหาสอง URL ให้ SEO ปวดหัว
    • ลำดับการแชร์: navigator.share (ถ้ามี) → navigator.clipboard.writeText → <textarea> + execCommand (origin ที่ไม่ใช่ HTTPS) → failed · คัดลอกสำรองเสมอเพื่อให้เดสก์ท็อปได้อะไรกลับไป
    • แสดงผลด้วย role="status" aria-live="polite" (การ์ด = sr-only, ท้ายหน้า = ข้อความข้างปุ่ม) และรีเซ็ตใน 2.5 วิ
    • ตำแหน่ง: การ์ดหน้าแรก = ปุ่มกลมมุมขวาบน (variant="icon", size-9) · ท้ายหน้ารายละเอียด = แถบ "แชร์หน้านี้" (variant="wide", min-h-11) หลังส่วน "โรงหนังอิสระอื่นๆ"
    • หน้าตาตามธีม (ห้ามเปลี่ยนเป็นสีอื่น): การ์ด = ชิปแก้ว rounded-xl + bg-[#1B1B1B]/80 + backdrop-blur-xl + border-white/10 (สูตรเดียวกับแผงข้อมูลบนการ์ด) ไอคอนขาว → hover #D47272 + ขอบ #A92626/60 · แถบท้ายหน้า = rounded-lg + bg-[#1B1B1B]/80 + border-[#332B2B] · สถานะสำเร็จ (คัดลอก/แชร์แล้ว) = ไอคอน IconCheck สี #D47272 + ขอบ #D47272/50 · hit area 44–48px ด้วย after:-inset-* (ไม่ขยายขนาดที่มองเห็น)
  • app/components/home/ — ส่วนของหน้าแรก (HeroSection)
  • app/components/cinema/ — ส่วนของหน้ารายละเอียด (Gallery, CinemaSummary, TransportList, ContactPanel, FacilitiesSection, LocationPanel, CinemaNotFound)
  • app/routes/about.tsx — หน้า "เกี่ยวกับเรา" (route /about, เมนูอยู่ทั้ง header และ footer, ใช้ <Link> ของ react-router จึงสลับหน้าแบบ SPA ไม่โหลดเอกสารใหม่) · เนื้อความเป็น font-content (มีหัว) ขนาด 17-18px leading-[1.95], นำ 19-21px, หัวข้อยังเป็น Inter ตามเดิม
  • docs/architecture.html — แผนผังการทำงาน Frontend / Backend / Data (เอกสารประกอบ ไม่ถูก build เข้าแอป) เปิดด้วยเบราว์เซอร์ได้ตรง ๆ
  • app/routes/_index.tsx (หน้าแรก) และ app/routes/cinema.$slug.tsx (รายละเอียด) — ประกอบ component + จัดการ state ของ route เท่านั้น ข้อมูลมาจาก useContent()
  • app/routes/admin_.login.tsx (หน้า login) และ app/routes/admin.tsx (แดชบอร์ด 7 แท็บ: โรงหนัง / หน้าเกี่ยวกับเรา / สำหรับคนรักหนัง / สำหรับคนทำโรงหนัง / คำศัพท์หลายภาษา / Footer-ไอคอน / สถิติการค้นหา) — ใช้ admin_.login เพื่อให้เป็น route พี่น้องของ /admin (ถ้าตั้งชื่อ admin.login จะกลายเป็น route ลูกที่ไม่มี <Outlet/> แล้วหน้าว่าง)
    • ฟอร์มโรงหนังแบ่งเป็น หมวดพับได้ (app/components/admin/AdminSection.tsx ใช้ <details>/<summary> เนทีฟ) เปิดไว้เฉพาะ "ข้อมูลหลัก" — เพิ่มหมวดใหม่ให้ใช้คอมโพเนนต์นี้เสมอ อย่าเรียงช่องยาวรวดเดียว
    • ช่อง slug (SlugInput.tsx): ดึงจากชื่ออังกฤษอัตโนมัติ (suggestSlug) จนกว่าจะแก้เอง · กันค่าว่าง/ซ้ำ · เตือนว่าลิงก์เดิมจะใช้ไม่ได้

หลังบ้าน (admin)

  • ข้อมูลที่แก้ได้เก็บที่ data/content/content.json (สร้างจาก seed อัตโนมัติครั้งแรก) — หน้าเว็บอ่านผ่าน readContent() ใน loader ของ app/root.tsx แล้วกระจายด้วย ContentProvider
  • API: POST /api/admin/login · POST /api/admin/logout · GET /api/admin/session · GET|PUT /api/admin/content · POST /api/admin/cinemas/import (วาง JSON ทับตาม slug)
  • ล็อกอินเริ่มต้น: ผู้ใช้ it is me / รหัส it is me&it is me — เปลี่ยนได้ด้วย env ADMIN_USERNAME, ADMIN_PASSWORD, ADMIN_SESSION_SECRET; session เป็น cookie HttpOnly ที่เซ็น HMAC (8 ชั่วโมง)
  • คำศัพท์ในหลังบ้านคือ dot path ของข้อความในหน้าเว็บ (hero.subtitle) ต่อภาษา — ค่าว่างแปลว่าใช้ค่าเดิมจาก messages.ts
  • Footer เก็บเป็นรายการ {icon_name, label, href} — ไอคอนที่เลือกได้อยู่ใน app/components/site/footer-icons.ts
  • หน้า "เกี่ยวกับเรา" แก้ได้ที่แท็บ หน้าเกี่ยวกับเรา (app/components/admin/AboutEditor.tsx) — เก็บเป็น about: { th, en } ใน content.json แต่ละภาษามี title, lead, sections[], contactHeading, contactNote
    • ฟิลด์ที่เว้นว่างจะถูกเติมด้วยค่าเริ่มต้นจาก MESSAGES[locale].about ตอน sanitize (sanitizeAbout) — ไฟล์เก่าที่ไม่มีคีย์ about จึงยังใช้งานได้
    • app/routes/about.tsx อ่านจาก useContent().about[locale] เท่านั้น ไม่ผูกกับข้อความใน messages.ts อีก
    • ตัวแก้ไขมีแท็บภาษา + ตัวอย่างหน้าเว็บสด และปุ่ม "คืนค่าตั้งต้น" ต่อภาษา
  • หน้า "สำหรับคนทำโรงหนัง" (/for-cinemas) และ "สำหรับคนรักหนัง" (/for-film-lovers) — บทความแบบ บล็อก ที่แก้ได้จากหลังบ้าน (ArticleEditor คนละแท็บ) และเรนเดอร์ผ่าน component ร่วม app/components/site/ArticlePage.tsx
    • ข้อมูล: forCinemas: { th, en } และ forFilmLovers: { th, en } ใน content.json แต่ละภาษา = { title, lead, blocks[], contactHeading, contactNote }
    • blocks[] มี 2 ชนิด: { type: "paragraph", text } และ { type: "image", src, alt, caption } — เรียงตามลำดับในอาร์เรย์เท่านั้น (มีปุ่ม ↑ ↓ / ลบ ในหลังบ้าน)
    • ตัวช่วยบริสุทธิ์อยู่ที่ app/lib/article.ts (sanitizeArticleBlocks, moveBlock, removeBlock, createParagraphBlock, createImageBlock) — ตัวตรวจฝั่งเซิร์ฟเวอร์คือ sanitizeForCinemas / sanitizeForFilmLovers ซึ่งใช้ตัวกลาง sanitizeArticlePage (ทิ้งบล็อกว่าง/ผิดชนิด, เติมค่าเริ่มต้นจาก seedForCinemas() / seedForFilmLovers())
    • ภาษาภาพเดียวกับ /about: กรอบ 1440 + px-[108px], font-content (IBM Plex Sans Thai Looped), การ์ดติดต่อไล่แดงขอบ rgba(169,38,38,0.45) + ไอคอนโซเชียลชุดเดียวกับ footer · มีลิงก์ใน header และ footer
    • header: มือถือ (< sm) ยุบเมนูทั้งสามหน้าไว้ใน <details> (native, คีย์บอร์ด/Esc ใช้ได้) เพราะป้ายภาษาไทยยาวและโลโก้มีขนาดตายตัวตามสเปก — อย่าเพิ่มลิงก์ตรงบนมือถืออีก
    • ตัวสลับภาษา (LocaleSwitcher) เป็น ปุ่มเดียว + dropdown (ไม่ใช่ปุ่ม TH/EN สองปุ่ม) — ต้องมี aria-haspopup="menu" / aria-expanded, ตัวเลือกเป็น role="menuitemradio" + aria-checked, เลื่อนด้วยลูกศรขึ้น/ลงได้ และปิดด้วย Esc/คลิกนอกเมนู
  • ลำดับโรงหนังในหลังบ้าน (app/components/admin/CinemaList.tsx) — ลำดับในอาร์เรย์ cinemas = ลำดับที่หน้าเว็บแสดง
    • โหมด ลำดับที่จัดไว้ (ค่าเริ่มต้น): ลากวางสลับที่ได้ หรือกด ↑ ↓ ทีละขั้น (คีย์บอร์ดใช้ได้) · เมื่อลำดับต่างจากที่บันทึกจะมีปุ่ม บันทึกลำดับใหม่ (PUT /api/admin/content ส่งเฉพาะ cinemas) หรือจะกด บันทึกทั้งหมด ในฟอร์มก็ได้
    • โหมด ก-ฮ: เรียงชื่อไทยด้วย Intl.Collator("th") — เป็นเพียงมุมมอง ลากสลับไม่ได้จนกว่าจะกด ใช้ลำดับ ก-ฮ นี้
    • ฟังก์ชันบริสุทธิ์ที่ใช้ซ้ำได้: sortCinemasByName · moveCinema · shiftCinema · hasSameOrder
  • ช่องกรอกหลายค่าในหลังบ้าน (app/components/admin/CommaListInput.tsx) — หมวด/ชำระเงินแก้เป็น CommaListInput
    • เก็บข้อความดิบใน draft ระหว่างพิมพ์ จึงพิมพ์ , คั่นได้จริง (ถ้าผูก array เข้า value ตรง ๆ ตัวคั่นจะถูกตัดทิ้งทุกคีย์)
    • ตอนออกจากช่อง (blur) ค่อย normalize เป็น ", " · รับ , และ 、 เป็นตัวคั่นด้วย · parseCommaList ใช้ซ้ำได้
  • สิ่งอำนวยความสะดวก ผูกกับโรงหนังแต่ละโรง (ไม่มีแท็บส่วนกลางแล้ว) — cinema.facilities = หัวข้อที่มีจริง, cinema.facility_details[key] = { label?, sub_th?, sub_en? } = ข้อความเฉพาะโรง
    • ในฟอร์มโรงหนัง: ชิปเลือกหัวข้อ → ด้านล่างมีช่อง "ชื่อหัวข้อ" (ช่องเดียว ใช้ทั้ง TH/EN)
    • ช่องคำอธิบาย TH/EN แสดงเฉพาะ slug house-cinema-samyan (ข้อมูลครบแล้ว) — โรงอื่นไม่ต้องกรอก
    • หน้าเว็บแสดงคำอธิบายเฉพาะที่มีค่าใน facility_details (ไม่กรอก = ไม่แสดงบรรทัดคำอธิบาย) · ไม่เลือกหัวข้อเลย → "ไม่มีข้อมูล"
    • ฟังก์ชันที่เกี่ยวข้อง: cinemaFacilities() (เรียงตาม FACILITY_KEYS) · UI หลังบ้าน app/components/admin/CinemaFacilitiesEditor.tsx
  • ที่ตั้ง (app/lib/map-embed.ts) — ลำดับ: map_url (Google Maps) → coordinates (0,0 ถือว่าไม่กรอก) → "ไม่มีข้อมูล"; iframe ใช้ maps.google.com/maps?q=…&output=embed (ไม่ต้องมี API key)
  • การเดินทาง (app/components/admin/TransportEditor.tsx) — แก้ transport[] (icon/TH/EN) ต่อโรง; แถวที่ยังไม่กรอกจะไม่แสดงบนหน้าเว็บ
  • ช่องทางติดต่อ (app/components/admin/ContactsEditor.tsx) — แก้ contacts[] = { label, value, href } ต่อโรง (ป้ายชื่อมี datalist แนะนำ Website/Facebook/Call ฯลฯ) · หัวข้อการ์ดใช้ contact_heading ต่อโรง ไม่กรอก = detail.contactTitle

กติกาข้อมูล (บังคับ — กันข้อมูลหาย)

  • readContent() เขียน seed เฉพาะกรณีไฟล์ไม่มี (ENOENT) เท่านั้น — ถ้าไฟล์ parse/sanitize ไม่ผ่านให้ โยน error ห้ามเขียนทับด้วย seed (เคสจริง: เคยทำให้ข้อมูล 20 โรงหายระหว่างแก้โค้ด)
  • ก่อนแก้ data/content/content.json ด้วยสคริปต์ ให้ cp สำรองไว้ที่ .output/content.json.bakN ทุกครั้ง
  • ฟิลด์ใหม่ใน Cinema ต้องมีค่าเริ่มต้นที่ปลอดภัยเมื่อข้อมูลเก่าไม่มีฟิลด์นั้น (เช่น facilities → [], facility_details → {}) และต้องผ่าน sanitizeCinemas()
  • โรงที่ hidden: true ต้องถูกกรองด้วย publiclyVisible() ก่อนแสดง/จัดอันดับ

หมวดหมู่ (categories)

  • ลำดับ/รายการทั้งหมดอยู่ใน CINEMA_CATEGORIES (app/lib/cinemas.ts) — แถบกรองหน้าแรกและชิปในหลังบ้านอ่านจากที่เดียวกัน
  • ชื่อที่แสดงมาจาก messages.categories + messages.tags (TH/EN) และ override ได้ผ่าน site.terms (categories.<คีย์>)
  • เพิ่มหมวดใหม่ = แก้ 3 ที่พร้อมกัน: CINEMA_CATEGORIES → categories (TH/EN) → เพิ่ม term ใน content.json (ถ้าต้องการให้แก้คำแปลในหลังบ้านได้)
  • หมวดที่เพิ่มล่าสุด: กลุ่มคนฉายหนัง (Film collectives) · หนังไทย (Thai films)
  • ทั้งหมด ใช้เป็น "ไม่กรอง" และไม่ถูกเสนอในชิปของหลังบ้าน (ASSIGNABLE_CATEGORIES ตัดออกให้)

ชั้นกรองที่ 1 — ประเภทโรงหนัง (venue type) — บังคับ

แถบกรองหน้าแรกมี สองชั้นในแถวเดียว เรียงเป็น ทั้งหมด → [3 ประเภท] │ หมวดภาพยนตร์…

  • ชั้นที่ 1 = VENUE_TYPES (app/lib/cinemas.ts): โรงภาพยนตร์ท้องถิ่น · โรงภาพยนตร์อินดี้ · กลุ่มคนฉายหนัง — เก็บที่ฟิลด์เดี่ยว cinema.venue_type (โรงหนึ่งเป็นได้ประเภทเดียว จึงไม่ใช้ tags ที่เป็นหลายค่า)
  • ชั้นที่ 2 = CINEMA_CATEGORIES เดิม (genre/ที่มา) — ห้ามมีค่าซ้ำกับ VENUE_TYPES (ตอนนี้ กลุ่มคนฉายหนัง ถูกย้ายขึ้นชั้น 1 แล้ว จึงไม่ปรากฏใน categories/messages.categories อีก แต่ tag ยังคงอยู่ในข้อมูลและยังค้นหาเจอ)
  • เลือกได้ทีละชั้น: กดประเภท → ล้างหมวดเป็น ทั้งหมด; กดหมวด → ล้างประเภทเป็น null; ทั้งหมด ล้างทั้งสอง (กันการกรองซ้อนที่คนใช้คาดไม่ถึง)
  • ตัวกรองจริงอยู่ใน filterCinemas(..., { venue }) ทำงานแบบ AND กับหมวดและคำค้น (เผื่ออนาคตจะเปิดให้ซ้อน) — venue = null คือไม่กรอง
  • โรงที่ยังไม่ตั้ง venue_type จะไม่โผล่เมื่อกรองด้วยประเภทใด ๆ · ตั้งค่าได้ที่หลังบ้าน → แท็บโรงหนัง → ข้อมูลหลัก → ประเภทโรงหนัง (sanitize ใน content.server.ts เท่านั้น)
  • หลังบ้านต้องรองรับพร้อมกัน: ลิสต์ซ้ายมีช่องค้นหา + ชิปกรอง ทั้งหมด/ท้องถิ่น/อินดี้/กลุ่ม/ยังไม่จัด พร้อมจำนวน, ป้ายประเภทท้ายชื่อทุกแถว, กล่อง ตั้งประเภททีละกลุ่ม (setVenueForSlugs) และสรุปจำนวนในหัวหลังบ้าน · logic อยู่ใน filterAdminCinemas / venueCounts (app/lib/cinemas.ts) ไม่ใช่ใน component (มี unit test)
  • ลากสลับลำดับถูกปิดเมื่อกรองอยู่ (draggable={mode === "manual" && !isFiltered}) เพราะลำดับของผลที่กรองแล้วไม่มีความหมาย
  • venue_type เป็นข้อมูล ไม่ใช่ข้อความ: ห้าม hardcode ป้ายใน component ต้องอ่าน messages.venues (คีย์ไทย) และ override ได้ผ่าน site.terms (venues.<คีย์>)
  • Popularity path (category === "ยอดนิยม") ถูกปิดเมื่อมี venue — กันการจัดอันดับข้ามประเภท

คอมโพเนนต์หลังบ้าน (app/components/admin/)

ไฟล์ ใช้ทำอะไร
AdminSection.tsx การ์ดหมวดพับได้ (details/summary + badge + description)
CinemaList.tsx รายชื่อโรง: เรียง ก-ฮ (Intl.Collator("th")) + ลากวาง/↑↓ สลับตำแหน่ง
ChipPicker.tsx ชิปเลือกหลายค่า (หมวด/สิ่งอำนวยความสะดวก) + toggleValue()
CommaListInput.tsx ช่องหลายค่าคั่น , (เก็บ draft กันตัวคั่นถูกกลืน) + parseCommaList()
SlugInput.tsx slug: normalizeSlug() · suggestSlug() · slugProblem()
PhotosEditor.tsx รูปโรงหนัง (photos[]) — รูปแรกเป็นปกการ์ดหน้าแรก
TransportEditor.tsx วิธีเดินทาง (transport[])
ContactsEditor.tsx ช่องทางติดต่อ (contacts[])
CinemaFacilitiesEditor.tsx ข้อความสิ่งอำนวยความสะดวกต่อโรง (facility_details)
AboutEditor.tsx เนื้อหาหน้า "เกี่ยวกับเรา"

รูปภาพ

  • cinema.photos[0] = รูปปกการ์ดหน้าแรก (CinemaCard) — ไม่มีรูป = ใช้ gradient 4 แบบ (CARD_GRADIENTS)
  • หน้า detail ใช้ Gallery: มีไม่ครบ 3 รูป ช่องที่ว่างแสดง โลโก้ AlterFlixHub (ดูหัวข้อโลโก้)
  • รูปในเครื่องวางที่ public/images/… แล้วใส่ path /images/… (ไฟล์ hero.png ใช้เป็นพื้นหลังฮีโร่หน้าแรก)
  • ห้ามใช้ลิงก์ hotlink จากภายนอกใน photos[] (Google Maps/googleusercontent/fbcdn/gstatic ฯลฯ) — ลิงก์มีอายุ จำกัด rate และตอบ 200 แต่ 0 ไบต์ ทำให้รูปแตกโดยไม่มี error ให้จับ
    • เก็บสำเนาลง public/images/cinemas/<slug>[-n].<ext> ด้วย node scripts/mirror-photos.mjs (สำรอง content.json ให้เอง · --dry = ดูเฉย ๆ) แล้ว photos[] ชี้ path ในโปรเจกต์
    • ตรวจรูปเสียก่อน commit: node scripts/audit-photos.mjs (exit 1 = มีรูปพัง)
    • ขนาดรูป: กว้างไม่เกิน 1600px และบีบอัด (JPEG q82 / WebP q82) — โฟลเดอร์ public/images/cinemas ควรอยู่ราว ≤ 3 MB
  • ทุก <img> ของโรงหนังต้องใช้ <PhotoImage> (app/components/site/PhotoImage.tsx) — มี onError สลับไปโลโก้แทนรูปแตก และจำ src ที่พังเพื่อให้เปลี่ยนรูปใหม่แล้วโหลดได้อีก (ห้ามเขียน <img src={photo}> ตรง ๆ ใน component ใหม่)
  • อัปโหลดจากหลังบ้าน: PhotosEditor → POST /api/admin/uploads (multipart, ≤ 8 MB, ตรวจ magic bytes) → เก็บ data/uploads/cinemas/ → คืน /uploads/cinemas/<slug>-<random>-<ts>.<ext> (gitignored) เสิร์ฟผ่าน Nitro route server/routes/uploads/[...path].get.ts — ห้ามย้ายไปเขียนใน public/ เพราะตอน production โฟลเดอร์นั้นถูก copy ตอน build (เขียน runtime ไม่ติด)
  • ช่องทางติดต่อ (contacts) — href ต้องใช้ได้จริง และถูกคำนวณใหม่ทุกครั้งที่บันทึกผ่าน contactHref() (app/lib/contact-link.ts): เบอร์ → tel:+66…, อีเมล → mailto:, เว็บ/โซเชียล → https:// (ตัด fbclid/_rdc/utm_*, เปลี่ยน web.facebook.com → www.facebook.com), LINE ID @x → line.me/R/ti/p/~x · หน้าเว็บใช้ resolveContact() ตัวเดียวกัน — ห้าม hardcode href ใน component และห้ามแสดง <a> ที่ไม่มี href (ให้แสดงเป็นข้อความแทน) · ตรวจ/ซ่อมทั้งไฟล์: node scripts/audit-contacts.mjs [--fix]
  • app/lib/upload.ts คือกติกากลาง (เพดานขนาด · ชนิดที่รับ · sanitize ชื่อ · กัน path traversal) — ใช้ทั้ง client และ server ห้ามประกาศซ้ำ

ลำดับการ์ดหน้าแรก (สลับทุกวัน)

  • app/lib/daily-order.ts — dailyOrder(items, idOf, key) คำนวณลำดับจาก "วันที่" ล้วน ๆ (ไม่เก็บ state)
  • เงื่อนไขบังคับ: โรงหนึ่งต้องไม่ได้อยู่ตำแหน่งการ์ดเดิม 2 วันติดกัน
    • permutation ฐาน = seeded shuffle (Fisher–Yates + mulberry32) จากลำดับที่แอดมินจัดไว้ → คงที่ทุกวัน
    • หมุน (rotate) ด้วย offset รายวันในช่วง 1..n-1 และ offset วันติดกันไม่เท่ากัน → ทุกโรงเลื่อนตำแหน่งแน่นอน
    • n = 2 สลับวันละครั้ง · รายการ < 2 คงเดิม
  • ทุกคนเห็นลำดับเดียวกันในวันเดียวกัน (คีย์วันที่แบบ UTC จาก loader → ไม่มี hydration mismatch)
  • ลำดับนี้ทำงาน ก่อน ตัวกรองหมวด/คำค้น — ผลกรองจึงสลับตามไปด้วย; ถ้าผู้ใช้กด "ใกล้ฉัน" การเรียงตามระยะทางยังชนะเสมอ
  • ตรวจด้วยสเปก app/lib/daily-order.spec.ts (n = 2..40 × 10 วัน, ไม่มีตำแหน่งซ้ำวันติดกัน)

สถิติการค้นหา (privacy-first, แนว Umami)

  • เก็บ event แบบ append-only ที่ data/analytics/events.jsonl (หมุนไฟล์เมื่อเกิน 8 MB, เก็บล่าสุด 50k event)
  • ตัวรับ event: POST /api/analytics/collect (สาธารณะ) — ไม่ใช้คุกกี้ ไม่เก็บ IP/User-Agent ดิบ ระบุผู้เข้าชมด้วย sha256(เกลือรายวัน | ip | ua) 16 ตัวอักษร
  • ชนิด event: search (query/category/result_count) · cinema_select (slug/source/position) · cinema_view · near_me
  • ฝั่งเว็บเรียกผ่าน trackEvent() (app/lib/analytics-client.ts) — กลืน error, กัน event ซ้ำใน 1.5 วินาที, ค้นหาจะถูกบันทึกหลังผู้ใช้หยุดพิมพ์ 900 ms และต้องมี ≥ 2 ตัวอักษร
  • สรุปผล: summarize(events, days) (app/lib/analytics.server.ts) → คำค้นยอดนิยม, คำค้นที่ไม่พบผล, CTR, ผลลัพธ์เฉลี่ย, หมวดที่ถูกใช้, โรงหนังที่ถูกเปิด/คลิก, การค้นหารายวัน
  • ดูได้ที่หลังบ้าน แท็บ สถิติการค้นหา (GET /api/admin/analytics?days=1|7|30|90, ต้องล็อกอิน)
  • ตั้ง ANALYTICS_SALT ใน env เพื่อไม่ให้ hash ผู้เข้าชมคาดเดาได้ข้าม deployment

SEO และการป้องกัน AI (บังคับ)

  • ไม่ฝังโดเมนในโค้ด (บังคับ): ทุกที่ที่ต้องใช้ URL เต็ม (canonical, OG, JSON-LD, sitemap, robots, ลิงก์แชร์) ต้องมาจาก origin ของ request จริง ผ่าน originFromRequest() / originFromHeaders() (app/lib/request-origin.ts) — รองรับ x-forwarded-host/x-forwarded-proto ของ reverse proxy · ตั้ง env SITE_URL เฉพาะเวลาต้องบังคับโดเมน (ปกติไม่ต้อง)
  • meta() ไม่มี access ต่อ request → route ที่มี meta ต้องมี loader คืน { origin } ด้วย (resolvePageOrigin() ใน app/lib/page-origin.ts) แล้วอ่าน loaderData.origin · root loader คืน siteUrl ให้ปุ่มแชร์ใช้ผ่าน ShareOriginProvider
  • ทุกหน้าใช้ pageMeta() (app/lib/seo.ts) — ได้ title, description, canonical, robots, OG, Twitter ครบชุด · route ห้ามเขียน { title } / <meta> เอง
  • JSON-LD: WebSite + Organization (+ SearchAction) ที่หน้าแรก · BreadcrumbList ทุกหน้าย่อย · MovieTheater หน้าโรงหนัง · Article หน้าบทความ
  • SearchAction ชี้ไป /?q=<คำค้น> — หน้าแรกจึงต้องอ่าน q จาก URL มาเป็นค่าเริ่มต้นของช่องค้นหา (ถ้าเปลี่ยนกลไกค้นหา ต้องแก้ทั้งคู่)
  • ห้ามใส่ hreflang: เว็บเดียวสลับภาษาได้ด้วย toggle (ไม่แยก URL) — ใส่แล้วจะกลายเป็นสัญญาณเนื้อหาซ้ำ
  • หน้า /admin, /admin/login = noindex, nofollow (หน้าโรงที่ไม่พบก็ noindex)
  • server/routes/robots.txt.ts — เปิด search engine หลัก, ปิด /api/, /admin, /_agent-native/, /c/ (ลิงก์ย่อ), และบล็อก AI crawler 21 ตัว · บรรทัด Sitemap: ต่อจาก origin ของ request (ห้ามเปลี่ยนกลับเป็นไฟล์ static)
  • public/ai.txt — ประกาศไม่ให้นำเนื้อหาไปฝึกโมเดล (ไฟล์ static, ไม่มีโดเมนอยู่ในเนื้อหา)
  • /sitemap.xml เป็น Nitro route (server/routes/sitemap.xml.ts) ไม่ใช่ React Router route — เพราะ SSR handler ของ framework ตอบ 404 ให้พาธที่ลงท้ายด้วยนามสกุลไฟล์ · ตัวสร้าง XML แยกอยู่ที่ app/lib/sitemap.ts (มี unit test) และต้องข้ามโรงที่ hidden
  • OG image: public/og/alterflixhub-1200x630.png (1200×630, โลโก้ Jersey 15 สี #8F0808 ตามสเปกโลโก้) — ห้ามพิมพ์โดเมนลงบนภาพ (ภาพเป็น static แก้ตาม request ไม่ได้) · เปลี่ยนคำบนภาพแล้วต้องสร้างใหม่ ไม่ใช้ภาพ placeholder

หมวด "ยอดนิยม" (จากสถิติ ไม่ใช่ป้ายมือ)

  • app/lib/popularity.server.ts — computePopularity() อ่าน events.jsonl แล้วให้สถานะ + อันดับ (memo 5 นาที)
  • เงื่อนไขเปิดใช้: ต้องมีประวัติข้อมูล ≥ 180 วัน (6 เดือน) — ready=false จนกว่าจะครบ เพื่อไม่ให้ฐานผู้ชมเล็ก ๆ ครองอันดับ
    • ระหว่างยังไม่ครบ: หมวด "ยอดนิยม" ใช้ tags ที่ตั้งไว้ (พฤติกรรมเดิม) โดยไม่แสดงข้อความแจ้งบนหน้าเว็บ — สถานะ/วันเหลือดูได้จาก computePopularity() หรือหลังบ้านเท่านั้น (ผู้ใช้สั่งลบข้อความออกจากหน้าแรก)
  • คะแนนเมื่อพร้อมใช้: cinema_view = 1 · cinema_select = 1.5 (เจตนาชัดกว่า) × decay ครึ่งชีวิต 30 วัน · นับเฉพาะ 90 วันล่าสุด · เอา top 8
  • โรงที่ถูกซ่อน (hidden) ไม่ถูกจัดอันดับ/แสดง
  • ค่าคงที่: POPULARITY_MIN_HISTORY_DAYS · POPULARITY_WINDOW_DAYS · POPULARITY_TOP_N

เพิ่มหน้าใหม่: ใส่ component ที่ app/components/<domain>/ แล้วให้ route เป็นตัวประกอบเท่านั้น