- ลิสต์โรงหนัง: ช่องค้นหา (ไทย/อังกฤษ/slug) + ชิปกรองประเภทพร้อมจำนวน (ทั้งหมด/ท้องถิ่น/อินดี้/กลุ่ม/ยังไม่จัด) - ป้ายประเภทท้ายชื่อทุกแถว (ยังไม่จัด = ป้ายแดง) + empty state - ตั้งประเภททีละกลุ่ม: "ตั้งประเภทให้ N โรงที่กรองอยู่" → เลือกประเภท → ใช้ (แล้วกดบันทึกทั้งหมด) - หัวหลังบ้านสรุปจำนวนต่อประเภท - แท็บคำศัพท์: ปุ่มลัดสร้าง key `venues.<ประเภท>` สำหรับแปลชื่อตัวกรอง - ปิดลากสลับลำดับขณะกรอง + hint อธิบาย - logic ย้ายไป lib: filterAdminCinemas / setVenueForSlugs / venueCounts + unit tests (169 ผ่าน) - DESIGN.md / docs/admin-guide.md อัปเดต
318 lines
59 KiB
Markdown
318 lines
59 KiB
Markdown
# 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 เป็นตัวประกอบเท่านั้น
|