- บทความจากหลังบ้าน: /for-film-lovers, /for-cinemas (ArticlePage + ArticleEditor แบบบล็อกย่อหน้า/รูป) - แชร์: ปุ่มบนการ์ดและท้ายหน้ารายละเอียด · ลิงก์ย่อ /c/<slug> (302) · ธีมแก้วตาม DESIGN.md - PWA: manifest/sw/offline + ถอดการล็อกซูม (WCAG 1.4.4) + touch target ≥44px - แอนิเมชัน reveal: IntersectionObserver + gate ด้วย html.fx-motion · เคารพ prefers-reduced-motion - ค้นหา: normalize/ตัดวรรณยุกต์ + AND หลายคำ + จัดอันดับ · รองรับ /?q= จาก SearchAction - SEO: pageMeta (canonical/OG/Twitter) + JSON-LD (WebSite/Organization/BreadcrumbList/MovieTheater/Article) - ไม่ฝังโดเมนในโค้ด: origin มาจาก request (x-forwarded-host/proto) ทั้ง canonical, sitemap, robots, ลิงก์แชร์ - กัน AI: robots.txt (Nitro route, บล็อก AI 21 ตัว) + ai.txt + OG image 1200x630 - เอกสาร: README สรุปโปรเจกต์, DESIGN.md (motion/PWA/SEO/ข้อมูล), architecture.html, admin-guide - tests: 135 ผ่าน (16 ไฟล์)
44 KiB
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-designskill and itsreferences/visual-direction.md). Do not ship the neutral placeholder theme. - Choose a product-fitting accent family and set it in the
app/global.csstokens 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 (บังคับ)
- อนิเมชันทั้งหมดอยู่ใน
app/global.cssใต้html.fx-motion— คลาสนี้ถูกใส่โดยสคริปต์ใน<head>(MOTION_INIT_SCRIPT,app/lib/motion.ts) เฉพาะเมื่อผู้ใช้ไม่ได้ขอprefers-reduced-motion: reduce→ ปิด JS หรือ reduced motion = ไม่มีอะไรถูกซ่อน (ห้ามเขียนopacity:0นอกขอบเขตนี้) - ใช้
transform/opacityเท่านั้น ห้าม animatewidth/height/top/left· ระยะเวลา: เร็ว 160ms · ปกติ 280ms · เปลี่ยนหน้า 460ms (--fx-page) · reveal 640ms · หน่วงต่อชิ้นไม่เกิน ~240ms - "ค่อย ๆ โผล่เมื่อเลื่อนถึง" ใช้
useReveal(app/hooks/use-reveal.ts) หรือ<Reveal>(app/components/site/Reveal.tsx) — มีกฎกันค้างซ่อน: บล็อกที่เลื่อนผ่านไปแล้ว (หรือถูกข้ามด้วยการกระโดด scroll) ต้องโผล่ทันที - hover ของการ์ดใช้
translate(Tailwindhover:-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):#B3B3B39.27 ·#D472725.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
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, cookielocale)- ข้อความทุกคำใน UI ต้องมาจาก
messagesไม่ hardcode ใน component · หมวดหมู่และ tag เก็บคีย์เป็นภาษาไทยเสมอ (ใช้กรองข้อมูล) แล้วแปลด้วยmessages.categories/messages.tags - ข้อความอังกฤษของเนื้อหาโรงหนังเป็นฟิลด์เสริม
location_label_en/description_en/address_lines_en/value_en— ไม่กรอกก็ fallback ไทย · ชื่อไทยใช้name_th(+ helpercinemaName(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 (รองรับเบราว์เซอร์ที่บล็อกคุกกี้) และซิงก์ข้ามแท็บผ่าน
storageevent 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-*(ไม่ขยายขนาดที่มองเห็น)
- ลิงก์สร้างจาก origin ของ request (root loader คืน
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-18pxleading-[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— เปลี่ยนได้ด้วย envADMIN_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ตัดออกให้)
คอมโพเนนต์หลังบ้าน (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ใช้เป็นพื้นหลังฮีโร่หน้าแรก)
ลำดับการ์ดหน้าแรก (สลับทุกวัน)
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 · ตั้ง envSITE_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 เป็นตัวประกอบเท่านั้น