- app/root.tsx: ลบ <AppProviders>, DbSyncSetup (useDbSync/useNavigationState/queryClient) เพราะ session gate รอ /_agent-native/auth/session + /status + application-state ซึ่งตอบ 401 บน production build และ 404 บน static host → React ไม่ mount เนื้อหา, ขึ้น AppShellSkeleton + "Configuration error (2 issues)" - คงไว้: AppToolkitProvider (design system), THEME_INIT_SCRIPT, analytics, PWA, ErrorBoundary - sw.js VERSION v2.1.0 - README + DESIGN: บันทึกเหตุผลและกฎ "ห้ามใส่ AppProviders กลับ"
129 lines
15 KiB
Markdown
129 lines
15 KiB
Markdown
# AlterFlixHub
|
|
|
|
ไดเรกทอรีโรงหนังอิสระ/อาร์ตเฮาส์และกลุ่มคนฉายหนังในประเทศไทย — ค้นหาโรงตามชื่อ/สถานที่/หมวดหมู่ ดูรายละเอียดการเดินทาง ที่ตั้ง และช่องทางติดต่อของแต่ละโรง พร้อมหลังบ้านที่แก้เนื้อหาเองได้โดยไม่ต้องแตะโค้ด
|
|
|
|
Stack: **React Router 8 (SSR) + Vite 8 + Tailwind 4 + TypeScript** บน Agent-Native runtime (Node/h3) · ข้อมูลเก็บเป็นไฟล์ JSON ใน `data/` · สถิติแบบ privacy-first (ไม่มีคุกกี้ ไม่เก็บ IP)
|
|
|
|
## เริ่มใช้งาน
|
|
|
|
```bash
|
|
cp .env.example .env # ครั้งแรกเท่านั้น
|
|
pnpm install
|
|
pnpm dev # http://localhost:8080
|
|
```
|
|
|
|
| คำสั่ง | ทำอะไร |
|
|
| --------------------------- | ------------------------------------ |
|
|
| `pnpm typecheck` | ตรวจ TypeScript ทั้งโปรเจกต์ |
|
|
| `pnpm test` | รันสเปกทั้งหมด (vitest) |
|
|
| `pnpm build` / `pnpm start` | build / รันโปรดักชัน |
|
|
| `pnpm agent-native:doctor` | ตรวจสุขภาพโปรเจกต์ตามกฎของ framework |
|
|
|
|
## หน้าเว็บ
|
|
|
|
| Route | หน้า |
|
|
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `/` | หน้าแรก — ฮีโร่ค้นหา, แถบหมวด, กริดการ์ดโรงหนัง (ลำดับการ์ด **สลับเองทุกวัน** ไม่ให้ซ้ำตำแหน่งเดิม 2 วันติดกัน) · รองรับลิงก์ค้นหาตรง `/?q=<คำค้น>` |
|
|
| `/cinema/<slug>` | รายละเอียดโรง — แกลเลอรี (กดลูกศรเลื่อนได้), สรุป, การเดินทาง, สิ่งอำนวยความสะดวก, ที่ตั้ง (แผนที่), ติดต่อ/ชำระเงิน, ปุ่มแชร์ |
|
|
| `/c/<slug>` | ลิงก์ย่อสำหรับแชร์ → **302** ไป `/cinema/<slug>` |
|
|
| `/for-film-lovers` | บทความ "สำหรับคนรักหนัง" (แก้จากหลังบ้าน) |
|
|
| `/for-cinemas` | บทความ "สำหรับคนทำโรงหนัง" (แก้จากหลังบ้าน) |
|
|
| `/about` | เกี่ยวกับเรา (แก้จากหลังบ้าน) |
|
|
| `/admin` · `/admin/login` | หลังบ้าน 7 แท็บ — ดู [docs/admin-guide.md](docs/admin-guide.md) · `noindex` |
|
|
| `/sitemap.xml` · `/robots.txt` · `/ai.txt` | ไฟล์สำหรับ crawler (sitemap/robots สร้างสดตามโดเมนของ request) |
|
|
|
|
รองรับ **ไทย/อังกฤษ** สลับที่ header (ปุ่มเดียว + dropdown) หรือ `?lang=en` (จำค่าใน cookie + localStorage)
|
|
|
|
## คุณสมบัติหลัก
|
|
|
|
- **กรองสองชั้น** — ประเภทโรงหนัง (ท้องถิ่น / อินดี้ / กลุ่มคนฉายหนัง) แล้วต่อด้วยหมวดภาพยนตร์
|
|
- **ค้นหา** — AND หลายคำ เรียงสลับได้ · ค้นทุกอย่างที่เห็นบนการ์ด (`name`, `name_th`, สถานที่, ที่อยู่, การเดินทาง, หมวด/แท็ก, คำอธิบาย) · ตัดวรรณยุกต์/สระบน-ล่าง และ normalize ตัวคั่น → พิมพ์ไม่ครบหรือไม่มีวรรณยุกต์ก็เจอ · เรียงผลตามความตรงของชื่อ
|
|
- **หาโรงใกล้ฉัน** — `navigator.geolocation` + ระยะเส้นตรง และระยะตามถนน (OSRM)
|
|
- **แชร์** — `navigator.share` → clipboard → fallback `<textarea>` · ลิงก์ย่อ `/c/<slug>` บนโดเมนจริงของ request · บอกผลด้วย `aria-live`
|
|
- **PWA** — manifest + service worker (navigate network-first, asset cache-first) + `/offline.html` · ติดตั้งลงจอโฮมได้
|
|
- **แอนิเมชันเบา** — reveal ตอนเลื่อน/โหลด ใช้เฉพาะ `transform`/`opacity` · ตัวอนิเมชันผูกกับ media query `prefers-reduced-motion` (ไม่ผูกคลาสที่ hydration ลบได้) · ผู้ใช้ที่ขอ reduced motion เห็นเนื้อหานิ่งครบทันที
|
|
- **หน้าตาเท่ากันทุกเอนจิน** — Chromium / Firefox / Safari: สกรอลบาร์ (`::-webkit-scrollbar` + `scrollbar-width`), `color-scheme: dark`, `::selection`, ฟอร์ม ≥16px บนมือถือ (iOS ไม่ซูมเอง), `tap-highlight` · ข้อยกเว้นที่ตั้งใจปล่อยไว้ (สกรอลบาร์ hover, ปุ่ม X ของ FF, install prompt, ฟอนต์ไทย) จดไว้ใน [DESIGN.md](DESIGN.md) หัวข้อ "Cross-engine parity"
|
|
- **SEO + กัน AI** — canonical/OG/Twitter/JSON-LD (`WebSite`, `Organization`, `BreadcrumbList`, `MovieTheater`, `Article`), `sitemap.xml` จากข้อมูลจริง, `robots.txt` บล็อก AI crawler 21 ตัว, `ai.txt`
|
|
- **สถิติ** — event `search` / `cinema_select` / `cinema_view` / `near_me` · หมวด "ยอดนิยม" เริ่มจัดอันดับจริงเมื่อข้อมูลครบ 6 เดือน
|
|
|
|
## หลังบ้าน
|
|
|
|
`http://localhost:8080/admin` — ล็อกอินด้วย `ADMIN_USERNAME` / `ADMIN_PASSWORD` (ค่าเริ่มต้น `it is me` / `it is me&it is me`)
|
|
|
|
7 แท็บ: **โรงหนัง** (ชื่อ/slug/หมวด/สิ่งอำนวยความสะดวก/การเดินทาง/ติดต่อ/**รูปภาพ — อัปโหลดจากเครื่อง/ลากวาง/วาง URL**/ที่ตั้ง/คำอธิบาย) · **หน้าเกี่ยวกับเรา** · **สำหรับคนรักหนัง** · **สำหรับคนทำโรงหนัง** · **คำศัพท์หลายภาษา** · **Footer-ไอคอน** · **สถิติการค้นหา**
|
|
|
|
คู่มือทีละงาน: **[docs/admin-guide.md](docs/admin-guide.md)**
|
|
|
|
## โครงสร้าง
|
|
|
|
```
|
|
app/
|
|
routes/ _index · cinema.$slug · c.$slug · about · for-film-lovers · for-cinemas · admin · admin_.login
|
|
components/
|
|
site/ SiteShell · SiteHeader/Footer · NavLink · Logo · CinemaCard · CinemaGrid · Reveal · ShareButton · ArticlePage
|
|
cinema/ Gallery · CinemaSummary · TransportList · FacilitiesSection · LocationPanel · ContactPanel
|
|
admin/ AdminSection · CinemaList · ChipPicker · CommaListInput · SlugInput · PhotosEditor · TransportEditor ·
|
|
ContactsEditor · CinemaFacilitiesEditor · AboutEditor · ArticleEditor · ArticleBlockCard · form-styles
|
|
hooks/ use-reveal · use-near-me · use-navigation-state
|
|
lib/ cinemas (ค้นหา/กรอง) · search · gallery · article · content.* · map-embed · geo · daily-order
|
|
motion · pwa · share · share-origin · seo · site · sitemap · request-origin · page-origin
|
|
analytics.* · popularity.server · i18n/ · design-tokens
|
|
server/
|
|
routes/ [...page].get.ts (SSR) · robots.txt.ts · sitemap.xml.ts
|
|
routes/api/ admin/* (login, session, content, import, analytics) · analytics/collect
|
|
public/ manifest.json · sw.js · offline.html · ai.txt · og/ · icon-*.png
|
|
data/
|
|
content/content.json แหล่งข้อมูลจริงของโรงหนัง/คำศัพท์/บทความ (แก้ผ่านหลังบ้าน)
|
|
analytics/events.jsonl สถิติแบบ append-only
|
|
docs/
|
|
admin-guide.md คู่มือใช้งานหลังบ้าน (ภาษาไทย)
|
|
api.md API reference
|
|
architecture.html แผนผังการทำงาน Frontend/Backend/Data (เปิดด้วยเบราว์เซอร์)
|
|
push-to-gitea.md วิธี push ขึ้น Gitea
|
|
DESIGN.md สัญญาการออกแบบ (บังคับ) — สี ฟอนต์ โลโก้ layout motion SEO กติกาข้อมูล
|
|
AGENTS.md กฎสำหรับ agent/AI ที่แก้โค้ดโปรเจกต์นี้
|
|
```
|
|
|
|
## โดเมนและ env
|
|
|
|
ระบบ**ไม่ฝังโดเมนในโค้ด** — canonical/OG/JSON-LD/sitemap/robots/ลิงก์แชร์ มาจาก origin ของ request (`app/lib/request-origin.ts` รองรับ `x-forwarded-host` / `x-forwarded-proto` ของ reverse proxy)
|
|
|
|
| env | จำเป็น | ใช้ทำอะไร |
|
|
| ------------------------------------------------------------ | ------- | ------------------------------------ |
|
|
| `ADMIN_USERNAME` · `ADMIN_PASSWORD` · `ADMIN_SESSION_SECRET` | แนะนำ | บัญชีหลังบ้าน + กุญแจเซ็น cookie |
|
|
| `ANALYTICS_SALT` | แนะนำ | เกลือ hash ผู้เข้าชม (กันคาดเดา) |
|
|
| `SITE_URL` / `SHARE_ORIGIN` | ไม่ต้อง | บังคับโดเมนเฉพาะกรณี (ปกติปล่อยว่าง) |
|
|
|
|
## Static export (โฮสต์แบบไฟล์นิ่ง / มี `index.html`)
|
|
|
|
แอปนี้เป็น SSR + หลังบ้านเขียนไฟล์ได้ → ค่าปกติรันเป็น Node server (`node .output/server/index.mjs`)
|
|
ถ้าต้องการ **ไฟล์นิ่งที่มี `index.html`** ใช้สคริปต์ export (ดึง HTML ทุกหน้าจากตัว server ที่รันอยู่):
|
|
|
|
> สำคัญ: `app/root.tsx` **ไม่ใช้ `AppProviders` ของ agent-native แล้ว** (ถอด session/navigation/application-state ออก)
|
|
> เพราะ provider นั้นรอ `/_agent-native/auth/session` + `/status` ซึ่งตอบ 401/404 บน production build และบน static host
|
|
> ทำให้ทั้ง prod build และ static export ค้างที่ skeleton + ขึ้น "Configuration error" · **ห้ามใส่กลับ** ถ้าไม่ได้ตั้ง auth+DB จริง
|
|
|
|
```bash
|
|
pnpm build # ได้ .output (preset node)
|
|
PORT=8090 node .output/server/index.mjs # เปิด server ตัวจริง
|
|
pnpm export:static http://127.0.0.1:8090 static-export
|
|
python -m http.server 8091 --directory static-export # ทดสอบแบบ static
|
|
```
|
|
|
|
ผลลัพธ์: `static-export/index.html`, `about/index.html`, `cinema/<slug>/index.html` (ทุกโรงที่ไม่ `hidden`), `c/<slug>/index.html` (redirect), `sitemap.xml`, `robots.txt`, `assets/`, `images/`, `404.html`
|
|
|
|
**ข้อจำกัดที่ตั้งใจ (static ไม่มี backend)**
|
|
|
|
- ไม่มี `/admin` และ `/api/*` — ต้องใช้ Node server ถ้าจะแก้เนื้อห ผมเพิ่ม/แก้ผ่านหลังบ้าน
|
|
- ไม่มี `?_data=` ของ React Router → สคริปต์ inject ตัวดักคลิก (`data-static-export-nav`) ให้ทุก link เป็นการโหลดหน้าเต็ม (ทุกหน้ามี HTML ของตัวเอง) — คลิก/ย้อนกลับ/รีเฟรชทำงานปกติ แต่ไม่มีการเปลี่ยนหน้าแบบ SPA
|
|
- ลิงก์แชร์ `/c/<slug>` กลายเป็นหน้า `meta refresh` + JS redirect (ไม่ใช่ 302 ของ server)
|
|
- canonical/OG ถูกอบตอน export — ตั้ง `SITE_URL` ตอนรัน server ก่อน export ถ้าต้องการโดเมนจริงใน meta
|
|
|
|
## เอกสารอื่น
|
|
|
|
- [DESIGN.md](DESIGN.md) — สัญญาการออกแบบ: พาเลตต์ ฟอนต์ โลโก้ layout motion PWA SEO และกติกากันข้อมูลหาย
|
|
- [docs/api.md](docs/api.md) — endpoint ทั้งหมด (method/path/auth/body)
|
|
- [docs/architecture.html](docs/architecture.html) — แผนผังการทำงาน
|
|
- [docs/push-to-gitea.md](docs/push-to-gitea.md) — วิธี push ขึ้น Gitea
|
|
- [DEVELOPING.md](DEVELOPING.md) — คู่มือ framework ของ starter (ไม่ใช่ของเฉพาะโปรเจกต์นี้)
|