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

318 lines
59 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 เป็นตัวประกอบเท่านั้น