Files
web-alterflixhub/docs/architecture.html
T
2026-11-01 17:24:44 +07:00

775 lines
30 KiB
HTML

<!doctype html>
<html lang="th">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>AlterFlixHub — แผนผังการทำงาน Frontend / Backend</title>
<style>
:root {
--bg: #0d0d0d;
--panel: #1b1b1b;
--panel-2: #161616;
--border: #332b2b;
--border-strong: #a92626;
--text: #f2f2f2;
--muted: #b3b3b3;
--crimson: #8f0808;
--crimson-soft: #d47272;
--line: #4a3a3a;
--front: #17222b;
--front-border: #2f4a5c;
--back: #241619;
--back-border: #5c2f38;
--data: #1c1f18;
--data-border: #3f4a30;
--ext: #1f1c26;
--ext-border: #423a58;
}
* {
box-sizing: border-box;
}
body {
margin: 0;
padding: 40px 32px 64px;
background: var(--bg);
color: var(--text);
font-family: "Noto Sans Thai", "IBM Plex Sans Thai Looped", system-ui,
-apple-system, "Segoe UI", sans-serif;
font-size: 14px;
line-height: 1.6;
}
.wrap {
max-width: 1440px;
margin: 0 auto;
}
header.page {
display: flex;
flex-wrap: wrap;
align-items: flex-end;
justify-content: space-between;
gap: 16px;
padding-bottom: 18px;
border-bottom: 1px solid var(--border);
margin-bottom: 28px;
}
h1 {
margin: 0;
font-size: 26px;
font-weight: 700;
letter-spacing: -0.01em;
}
.sub {
margin: 6px 0 0;
color: var(--muted);
font-size: 14px;
max-width: 720px;
}
.legend {
display: flex;
flex-wrap: wrap;
gap: 14px;
font-size: 12px;
color: var(--muted);
}
.legend span {
display: inline-flex;
align-items: center;
gap: 6px;
}
.dot {
width: 10px;
height: 10px;
border-radius: 3px;
display: inline-block;
}
.dot.f {
background: var(--front);
border: 1px solid var(--front-border);
}
.dot.b {
background: var(--back);
border: 1px solid var(--back-border);
}
.dot.d {
background: var(--data);
border: 1px solid var(--data-border);
}
.dot.e {
background: var(--ext);
border: 1px solid var(--ext-border);
}
/* ---------- lanes ---------- */
.lanes {
display: grid;
grid-template-columns: minmax(0, 1fr) 56px minmax(0, 1fr) 56px minmax(0, 0.62fr);
gap: 0 8px;
align-items: start;
}
.lane {
border: 1px solid var(--border);
border-radius: 14px;
background: var(--panel-2);
overflow: hidden;
}
.lane > h2 {
margin: 0;
padding: 10px 14px;
font-size: 13px;
font-weight: 600;
letter-spacing: 0.08em;
text-transform: uppercase;
border-bottom: 1px solid var(--border);
color: var(--muted);
}
.lane .stack {
display: flex;
flex-direction: column;
gap: 10px;
padding: 14px;
}
.lane.front > h2 {
color: #9fc6df;
}
.lane.back > h2 {
color: #e0a0a8;
}
.lane.data > h2 {
color: #bccf9c;
}
.lane.ext > h2 {
color: #bdb3dc;
}
/* ---------- node ---------- */
.node {
border-radius: 10px;
padding: 10px 12px;
border: 1px solid var(--border);
background: var(--panel);
}
.node .name {
font-weight: 600;
font-size: 14px;
display: block;
}
.node .desc {
display: block;
margin-top: 3px;
font-size: 12px;
line-height: 1.55;
color: var(--muted);
}
.node code,
code {
font-family: "JetBrains Mono", "Cascadia Code", ui-monospace, Menlo,
Consolas, monospace;
font-size: 11.5px;
color: #c9c9c9;
background: rgba(255, 255, 255, 0.05);
padding: 1px 5px;
border-radius: 4px;
}
.node.f {
background: var(--front);
border-color: var(--front-border);
}
.node.b {
background: var(--back);
border-color: var(--back-border);
}
.node.d {
background: var(--data);
border-color: var(--data-border);
}
.node.e {
background: var(--ext);
border-color: var(--ext-border);
}
.node.accent {
border-color: var(--border-strong);
box-shadow: inset 3px 0 0 var(--crimson);
}
.group {
border: 1px dashed var(--line);
border-radius: 10px;
padding: 10px;
}
.group > .title {
font-size: 11px;
letter-spacing: 0.06em;
text-transform: uppercase;
color: #8d8d8d;
margin-bottom: 8px;
display: block;
}
.group .row {
display: grid;
gap: 8px;
grid-template-columns: 1fr 1fr;
}
/* ---------- arrows ---------- */
.arrow {
position: relative;
display: flex;
align-items: center;
justify-content: center;
padding-top: 46px;
}
.arrow::before {
content: "";
position: absolute;
left: 50%;
top: 12px;
bottom: 12px;
width: 1px;
background: linear-gradient(
to bottom,
transparent,
var(--line) 12%,
var(--line) 88%,
transparent
);
}
.arrow::after {
content: "";
position: absolute;
left: 50%;
bottom: 12px;
transform: translateX(-50%);
border-left: 6px solid transparent;
border-right: 6px solid transparent;
border-top: 8px solid var(--line);
}
.arrow .label {
position: relative;
z-index: 1;
background: var(--bg);
border: 1px solid var(--border);
border-radius: 999px;
padding: 4px 9px;
font-size: 11px;
color: var(--muted);
text-align: center;
line-height: 1.35;
}
/* ---------- data band ---------- */
.band {
margin-top: 14px;
display: grid;
gap: 14px;
grid-template-columns: minmax(0, 1fr);
}
/* ---------- flow list ---------- */
section.flows {
margin-top: 34px;
}
section.flows h3 {
margin: 0 0 4px;
font-size: 18px;
}
section.flows > p.lead {
margin: 0 0 16px;
color: var(--muted);
font-size: 13px;
}
.flow {
border: 1px solid var(--border);
border-radius: 14px;
background: var(--panel-2);
padding: 16px 18px;
margin-bottom: 12px;
}
.flow h4 {
margin: 0 0 12px;
font-size: 14px;
font-weight: 600;
}
.flow ol {
margin: 0;
padding: 0;
list-style: none;
display: flex;
flex-wrap: wrap;
gap: 8px;
}
.flow li {
position: relative;
flex: 1 1 160px;
min-width: 140px;
padding: 9px 12px 9px 34px;
border: 1px solid var(--border);
border-radius: 9px;
background: var(--panel);
font-size: 12px;
line-height: 1.5;
color: #e4e4e4;
}
.flow li .n {
position: absolute;
left: 9px;
top: 9px;
width: 18px;
height: 18px;
border-radius: 50%;
display: flex;
align-items: center;
justify-content: center;
font-size: 10px;
font-weight: 700;
color: var(--crimson-soft);
border: 1px solid rgba(169, 38, 38, 0.55);
background: rgba(143, 8, 8, 0.18);
}
.flow li b {
display: block;
font-weight: 600;
font-size: 12.5px;
}
.flow li em {
font-style: normal;
color: var(--muted);
font-size: 11.5px;
}
.note {
margin-top: 18px;
border-left: 3px solid var(--border-strong);
background: rgba(143, 8, 8, 0.09);
padding: 12px 16px;
border-radius: 0 10px 10px 0;
font-size: 12.5px;
color: #d9d9d9;
}
.note b {
color: #fff;
}
footer.page {
margin-top: 30px;
padding-top: 14px;
border-top: 1px solid var(--border);
font-size: 11.5px;
color: #7d7d7d;
}
@media (max-width: 1100px) {
.lanes {
grid-template-columns: minmax(0, 1fr);
gap: 14px;
}
.arrow {
padding: 0;
height: 34px;
}
.arrow::before {
left: 50%;
top: 0;
bottom: 0;
}
.arrow::after {
bottom: 0;
}
}
</style>
</head>
<body>
<div class="wrap">
<header class="page">
<div>
<h1>AlterFlixHub — แผนผังการทำงาน</h1>
<p class="sub">
เว็บรวมโรงหนังอิสระและอาร์ตเฮาส์ · React Router 8 (SSR) ฝั่งหน้าเว็บ
+ Node/h3 (agent-native) ฝั่งหลังบ้าน · ข้อมูลโรงหนังเก็บเป็นไฟล์ JSON
ใน <code>data/</code> และสถิติแบบ append-only
</p>
</div>
<div class="legend">
<span><i class="dot f"></i>Frontend (browser)</span>
<span><i class="dot b"></i>Backend (server)</span>
<span><i class="dot d"></i>Data (ดิสก์/SQL)</span>
<span><i class="dot e"></i>บริการภายนอก</span>
</div>
</header>
<div class="lanes">
<!-- ================= FRONTEND ================= -->
<div class="lane front">
<h2>Frontend — เบราว์เซอร์</h2>
<div class="stack">
<div class="node f accent">
<span class="name">User / เบราว์เซอร์</span>
<span class="desc"
>เปิดหน้าแรก · ค้นหา/กรอง · กด “ใกล้ฉัน” · สลับภาษา TH/EN</span
>
</div>
<div class="group">
<span class="title">Routes — app/routes/</span>
<div class="row">
<div class="node f">
<span class="name"><code>/</code></span>
<span class="desc">HeroSection + CinemaGrid</span>
</div>
<div class="node f">
<span class="name"><code>/cinema/:slug</code></span>
<span class="desc">Gallery, Summary, Transport, Location</span>
</div>
<div class="node f">
<span class="name"><code>/about</code></span>
<span class="desc">เนื้อหาจาก data/content</span>
</div>
<div class="node f">
<span class="name"><code>/admin</code></span>
<span class="desc">login + แดชบอร์ด 4 แท็บ</span>
</div>
</div>
</div>
<div class="node f">
<span class="name">SiteShell + SiteHeader / SiteFooter</span>
<span class="desc"
>กรอบหน้า: BackdropFrame (glow) · Logo (Jersey 15) · nav หน้าแรก/เกี่ยวกับเรา
· ปุ่มภาษา</span
>
</div>
<div class="group">
<span class="title">Providers — app/root.tsx</span>
<div class="row">
<div class="node f">
<span class="name">ContentProvider</span>
<span class="desc">useContent() → cinemas / about / terms / footer</span>
</div>
<div class="node f">
<span class="name">LocaleProvider</span>
<span class="desc">?lang → localStorage → cookie → ไทย</span>
</div>
<div class="node f">
<span class="name">NearMeProvider</span>
<span class="desc">Geolocation API → ระยะทางต่อ slug</span>
</div>
<div class="node f">
<span class="name">AppProviders / DbSync</span>
<span class="desc">query client + useDbSync (real-time)</span>
</div>
</div>
</div>
<div class="group">
<span class="title">Client libs — app/lib/</span>
<div class="row">
<div class="node f">
<span class="name">cinemas.ts</span>
<span class="desc">filterCinemas · findCinemaBySlug · formatDistance</span>
</div>
<div class="node f">
<span class="name">geo.ts</span>
<span class="desc">ระยะเส้นตรง + เรียก OSRM ตามถนน</span>
</div>
<div class="node f">
<span class="name">analytics-client.ts</span>
<span class="desc">trackEvent() · debounce 900 ms · กัน event ซ้ำ</span>
</div>
<div class="node f">
<span class="name">i18n/messages.ts</span>
<span class="desc">ข้อความ TH/EN ทุกคำใน UI</span>
</div>
<div class="node f">
<span class="name">map-embed.ts</span>
<span class="desc">URL แผนที่: map_url → พิกัด → null (แสดง "ไม่มีข้อมูล")</span>
</div>
</div>
</div>
<div class="node f">
<span class="name">หลังบ้าน /admin</span>
<span class="desc">AdminSection (หมวดพับ) · CinemaList (ก-ฮ + ลากสลับ) · SlugInput · ChipPicker · CommaListInput · PhotosEditor · TransportEditor · ContactsEditor · CinemaFacilitiesEditor</span>
</div>
</div>
</div>
<!-- arrow -->
<div class="arrow">
<span class="label">HTTP<br />/ JSON</span>
</div>
<!-- ================= BACKEND ================= -->
<div class="lane back">
<h2>Backend — Node / h3 (agent-native)</h2>
<div class="stack">
<div class="node b accent">
<span class="name">root loader — <code>readContent()</code></span>
<span class="desc"
>ทำงานตอน SSR ทุกคำขอ: อ่าน store → ส่งเข้า ContentProvider พร้อม HTML
แรก (cache ตาม mtime ของไฟล์)</span
>
</div>
<div class="group">
<span class="title">API routes — server/routes/api/</span>
<div class="row">
<div class="node b">
<span class="name"><code>admin/login</code> · <code>logout</code> · <code>session</code></span>
<span class="desc">cookie HttpOnly เซ็น HMAC · 8 ชม. · env ADMIN_*</span>
</div>
<div class="node b">
<span class="name"><code>admin/content</code> GET/PUT</span>
<span class="desc">อ่าน/บันทึก cinemas · terms · footer · about</span>
</div>
<div class="node b">
<span class="name"><code>admin/cinemas/import</code></span>
<span class="desc">วาง JSON ทับตาม slug</span>
</div>
<div class="node b">
<span class="name"><code>admin/analytics</code></span>
<span class="desc">สรุปสถิติ 1/7/30/90 วัน</span>
</div>
<div class="node b">
<span class="name"><code>analytics/collect</code> (สาธารณะ)</span>
<span class="desc">รับ event · ไม่ใช้คุกกี้ · ไม่เก็บ IP/UA ดิบ</span>
</div>
<div class="node b">
<span class="name">middleware/auth.ts</span>
<span class="desc">runAuthGuard() คุมทุก path /admin</span>
</div>
</div>
</div>
<div class="group">
<span class="title">Server libs</span>
<div class="row">
<div class="node b">
<span class="name">content.server.ts</span>
<span class="desc">sanitize ทุกฟิลด์ · เขียนแบบ atomic (temp → rename) · seed เฉพาะเมื่อไฟล์ไม่มี (ห้ามทับของจริง)</span>
</div>
<div class="node b">
<span class="name">popularity.server.ts</span>
<span class="desc">อันดับ "ยอดนิยม" จาก events · ต้องมีประวัติ ≥ 180 วัน · decay ครึ่งชีวิต 30 วัน · top 8 · memo 5 นาที</span>
</div>
<div class="node b">
<span class="name">analytics.server.ts</span>
<span class="desc">summarize() · หมุนไฟล์ 8 MB · เก็บ 50k event</span>
</div>
<div class="node b">
<span class="name">actions/</span>
<span class="desc">navigate · view-screen · provider-api-request (เครื่องมือ agent)</span>
</div>
<div class="node b">
<span class="name">server/db.ts</span>
<span class="desc">Drizzle + pglite (ยังไม่เปิดใช้ตาราง)</span>
</div>
</div>
</div>
<div class="node b">
<span class="name">plugins/config.ts</span>
<span class="desc"
>homePath <code>/</code> · ปิด integrations / terminal / sentry ·
email-branding อ่าน app.name</span
>
</div>
</div>
</div>
<!-- arrow -->
<div class="arrow">
<span class="label">อ่าน/เขียน<br />ไฟล์</span>
</div>
<!-- ================= EXTERNAL ================= -->
<div class="lane ext">
<h2>บริการภายนอก</h2>
<div class="stack">
<div class="node e">
<span class="name">OSRM</span>
<span class="desc">ระยะทาง/เวลาเดินทางตามถนนจริง (ปุ่ม “ใกล้ฉัน”)</span>
</div>
<div class="node e">
<span class="name">OpenStreetMap</span>
<span class="desc">พิกัดอ้างอิงของโรงหนัง + แผนที่</span>
</div>
<div class="node e">
<span class="name">Google Fonts</span>
<span class="desc">Jersey 15 · Noto Sans Thai (Inter + IBM Plex Thai Looped ฝังในโปรเจกต์)</span>
</div>
<div class="node e">
<span class="name">AI SDK providers</span>
<span class="desc">OpenAI / Anthropic / Google ฯลฯ สำหรับ actions ของ agent</span>
</div>
</div>
</div>
</div>
<!-- ================= DATA BAND ================= -->
<div class="band">
<div class="lane data">
<h2>Data layer — data/ (ไฟล์บนดิสก์ + SQL)</h2>
<div class="stack">
<div class="group">
<span class="title">แหล่งข้อมูลจริง</span>
<div class="row">
<div class="node d">
<span class="name">data/content/content.json</span>
<span class="desc"
>แหล่งเดียวของ cinemas · site.terms · footer · about{th,en} —
หน้าเว็บอ่านผ่าน readContent() เท่านั้น</span
>
</div>
<div class="node d">
<span class="name">data/analytics/events.jsonl</span>
<span class="desc">append-only: search / cinema_select / cinema_view / near_me</span>
</div>
<div class="node d">
<span class="name">data/pglite/</span>
<span class="desc">SQL ฝังในเครื่อง (Drizzle) — ยังว่าง รอตารางแรก</span>
</div>
<div class="node d">
<span class="name">app/lib/content-seed.ts</span>
<span class="desc">ค่าเริ่มต้น: CINEMAS + ข้อความ i18n → สร้าง content.json ครั้งแรก</span>
</div>
</div>
</div>
</div>
</div>
</div>
<!-- ================= FLOWS ================= -->
<section class="flows">
<h3>เส้นทางการทำงานหลัก</h3>
<p class="lead">
ทุกเส้นเริ่มจากเบราว์เซอร์ เว้นแต่ระบุไว้เป็นอย่างอื่น — ลำดับเลขคือลำดับที่เกิดจริง
</p>
<div class="flow">
<h4>1 · เปิดหน้า (SSR + hydration)</h4>
<ol>
<li><span class="n">1</span><b>GET / หรือ /about</b><em>เบราว์เซอร์ขอเอกสาร</em></li>
<li><span class="n">2</span><b>root loader</b><em>readContent() อ่าน content.json</em></li>
<li><span class="n">3</span><b>SSR HTML</b><em>ส่งเนื้อหาพร้อมหน้าแรก</em></li>
<li><span class="n">4</span><b>Hydrate</b><em>ContentProvider + LocaleProvider</em></li>
<li><span class="n">5</span><b>Client nav</b><em>Link เปลี่ยนหน้าโดยไม่โหลดใหม่</em></li>
</ol>
</div>
<div class="flow">
<h4>2 · ค้นหา / กรอง / ใกล้ฉัน</h4>
<ol>
<li><span class="n">1</span><b>พิมพ์ค้นหา</b><em>filterCinemas() ในหน่วยความจำ</em></li>
<li><span class="n">2</span><b>กด “ใกล้ฉัน”</b><em>Geolocation API (ขอเมื่อกดเท่านั้น)</em></li>
<li><span class="n">3</span><b>เรียก OSRM</b><em>ระยะทางตามถนน · ล้มเหลวใช้เส้นตรง</em></li>
<li><span class="n">4</span><b>เรียงผล</b><em>NearMeProvider แจก distances</em></li>
<li><span class="n">5</span><b>trackEvent("near_me")</b><em>ไม่บล็อก UI</em></li>
</ol>
</div>
<div class="flow">
<h4>3 · บันทึกสถิติ (privacy-first)</h4>
<ol>
<li><span class="n">1</span><b>หยุดพิมพ์ 900 ms</b><em>ต้องมี ≥ 2 ตัวอักษร</em></li>
<li><span class="n">2</span><b>POST /api/analytics/collect</b><em>ไม่แนบคุกกี้</em></li>
<li><span class="n">3</span><b>hash ผู้เข้าชม</b><em>sha256(salt รายวัน | ip | ua) 16 ตัว</em></li>
<li><span class="n">4</span><b>append events.jsonl</b><em>หมุนไฟล์ 8 MB · เก็บ 50k</em></li>
<li><span class="n">5</span><b>admin/analytics</b><em>summarize() → การ์ดสถิติ</em></li>
</ol>
</div>
<div class="flow">
<h4>4 · แก้เนื้อหาผ่านหลังบ้าน</h4>
<ol>
<li><span class="n">1</span><b>POST admin/login</b><em>ตรวจ env ADMIN_USERNAME/PASSWORD</em></li>
<li><span class="n">2</span><b>cookie HMAC</b><em>HttpOnly · 8 ชม.</em></li>
<li><span class="n">3</span><b>แก้ใน AboutEditor / แท็บอื่น</b><em>ตัวอย่างหน้าเว็บสด</em></li>
<li><span class="n">4</span><b>PUT admin/content</b><em>sanitize ก่อนบันทึก</em></li>
<li><span class="n">5</span><b>atomic write</b><em>temp → rename · cache ใหม่ตาม mtime</em></li>
</ol>
</div>
<div class="flow">
<h4>5 · หมวด "ยอดนิยม" (สถิติจริง ต้องครบ 6 เดือน)</h4>
<ol>
<li><span class="n">1</span><b>ผู้ใช้กด "ยอดนิยม"</b><em>หน้าแรกขอข้อมูลจาก loader</em></li>
<li><span class="n">2</span><b>computePopularity()</b><em>อ่าน events.jsonl (memo 5 นาที)</em></li>
<li><span class="n">3</span><b>เช็กประวัติ ≥ 180 วัน</b><em>ยังไม่ครบ → ไม่จัดอันดับ</em></li>
<li><span class="n">4</span><b>ยังไม่ครบ</b><em>ใช้ป้าย tags เงียบ ๆ ไม่มีข้อความบนหน้าเว็บ</em></li>
<li><span class="n">5</span><b>ครบแล้ว</b><em>view=1 · select=1.5 · decay 30 วัน · top 8 (ตัด hidden)</em></li>
</ol>
</div>
<div class="flow">
<h4>6 · แก้ข้อมูลผ่านหลังบ้าน (5 แท็บ · ฟอร์มเป็นหมวดพับ)</h4>
<ol>
<li><span class="n">1</span><b>เลือกโรงจากรายการซ้าย</b><em>เรียง ก-ฮ หรือลากสลับลำดับ</em></li>
<li><span class="n">2</span><b>กางหมวดที่ต้องการ</b><em>AdminSection (details/summary)</em></li>
<li><span class="n">3</span><b>แก้ช่อง</b><em>slug อัตโนมัติ · ชิปหมวด/สิ่งอำนวยความสะดวก · การเดินทาง · ติดต่อ · รูป · ที่ตั้ง</em></li>
<li><span class="n">4</span><b>บันทึกทั้งหมด</b><em>PUT /api/admin/content (เฉพาะ অংশที่ส่ง)</em></li>
<li><span class="n">5</span><b>sanitize + atomic write</b><em>แล้ว loader รอบถัดไปอ่านค่าใหม่</em></li>
</ol>
</div>
<div class="flow">
<h4>7 · ลำดับการ์ดหน้าแรก (สลับทุกวัน · ห้ามซ้ำตำแหน่งเดิม)</h4>
<ol>
<li><span class="n">1</span><b>loader ส่ง orderKey</b><em>วันที่แบบ UTC (YYYY-MM-DD)</em></li>
<li><span class="n">2</span><b>dailyOrder()</b><em>seeded shuffle จากลำดับที่แอดมินจัด</em></li>
<li><span class="n">3</span><b>rotate ตาม offset รายวัน</b><em>offset 1..n-1 · วันติดกันไม่เท่ากัน</em></li>
<li><span class="n">4</span><b>ทุกโรงเลื่อนตำแหน่ง</b><em>ไม่มีใครอยู่ช่องเดิม 2 วันติดกัน</em></li>
<li><span class="n">5</span><b>กรองหมวด/คำค้น</b><em>หรือเรียงตามระยะทางถ้ากด "ใกล้ฉัน"</em></li>
</ol>
</div>
<div class="note">
<b>กฎที่ยึดทั้งระบบ:</b> หน้าเว็บอ่านข้อมูลผ่าน <code>useContent()</code> เท่านั้น
ไม่ import ข้อมูลดิบ · ข้อความทุกคำมาจาก <code>messages.ts</code> + ส่วนที่แก้ได้จาก
<code>terms</code>/<code>about</code> · ฟอนต์: หัวข้อ Inter + Noto Sans Thai,
เนื้อหายาว IBM Plex Sans Thai Looped (<code>font-content</code>), โลโก้ Jersey 15
</div>
</section>
<footer class="page">
ไฟล์นี้เป็นเอกสารประกอบ (ไม่ถูก build เข้าแอป) — อ้างอิงโค้ดจริง ณ
<code>app/routes/about.tsx</code>, <code>app/root.tsx</code>,
<code>server/routes/api/</code>, <code>app/lib/content.server.ts</code>
</footer>
</div>
</body>
</html>