- ARCHITECTURE.md: end-to-end system doc (no-backend model, file map, boot sequence, routing, JSON data layer, shared engines, cache/update pipeline, analytics privacy model, failure modes, extension recipes, test checklist) - README: doc map + 6-line how-it-works + release/verification commands - AGENTS: doc index, analytics rules, auto-update rule; drop the outdated 'ask users to press Ctrl+Shift+R' instruction
26 KiB
ARCHITECTURE.md — สถาปัตยกรรม Atroute (web-at-transit-mock)
เอกสารนี้ตอบคำถาม "ระบบนี้ทำงานยังไง" ทั้งฝั่งที่รันในเบราว์เซอร์ (frontend) และฝั่งเซิร์ฟเวอร์/ข้อมูล (ที่ repo นี้เรียกว่า backend แต่จริง ๆ ไม่มีโค้ดเซิร์ฟเวอร์) อ่านคู่กับ
AGENTS.md(กฎการแก้โค้ด) และDESIGN.md(กฎการออกแบบ)
0. อ่านอะไรก่อน
| อยากทำอะไร | อ่าน |
|---|---|
| แก้หน้าเว็บ/เพิ่ม view | AGENTS.md → §โครงสร้าง, §การเคลื่อนไหว, เอกสารนี้ §4–§6 |
| เปลี่ยนสี/ฟอนต์/สไตล์ | DESIGN.md (เป็นรัฐธรรมนูญ — แก้ก่อนเขียนโค้ด) |
| เพิ่ม/แก้ข้อมูลเส้นทาง | เอกสารนี้ §5 + resource/data/QGIS Project/GeoJSON-2/README.md |
| ปล่อยเวอร์ชันใหม่ | เอกสารนี้ §7 (bump-version.py) |
| ตรวจว่างานไม่พัง | เอกสารนี้ §12 (checklist) |
1. ภาพรวม — "backend" ของโปรเจกต์นี้คืออะไร
repo นี้เป็น static site: ไม่มี Node/PHP/DB ไม่มี build step สิ่งที่ทำหน้าที่แทน backend แบ่งเป็น 4 อย่าง:
┌──────────────────────────── เบราว์เซอร์ผู้ใช้ ────────────────────────────┐
│ index.html (shell) │
│ └─ router.js ─ fetch partials/*.html ─┐ │
│ └─ <script> ใน partial (init) │ │
│ └─ fetch ../resource/data/*.json │
│ localStorage: at_stats_v1 · at_route_hits · at_reload_for │
│ Service Worker (sw.js): cache precache + network-first │
└───────────────▲──────────────────────────────────────────▲──────────────┘
│ HTTP GET (static files) │ (ถ้าตั้ง Umami)
┌───────────────┴───────────────┐ ┌────────────┴─────────────┐
│ static host / `make serve` │ │ Umami (ไม่บังคับ) │
│ ui/** resource/data/** │ │ POST /api/send │
└───────────────▲───────────────┘ └──────────────────────────┘
│ git push (Gitea)
┌───────────────┴──────────────────────────────────────────────────────────┐
│ offline pipeline: resource/tools/*.py (QGIS → geojson, km, version, i18n)│
│ inputs: resource/data/QGIS Project/*.shp|gpkg, scheduleslist/*.json │
└──────────────────────────────────────────────────────────────────────────┘
| หน้าที่ของ backend ปกติ | อะไรทำแทนใน repo นี้ |
|---|---|
| routing / template | ui/router.js (hash router) + ui/partials/*.html |
| API / query | fetch() ไฟล์ JSON ตรง ๆ (resource/data/) |
| session / บัญชีผู้ใช้ | ไม่มีเลย — ไม่มีล็อกอิน ไม่มีคุกกี้ |
| ฐานข้อมูล | ไฟล์ JSON ใน git (เจ้าของแก้มือ + เครื่องมือ Python ช่วย) |
| cache/CDN | Service Worker (ui/sw.js) + ?v= cache busting |
| analytics | ui/analytics.js (local-first, ไม่มีเซิร์ฟเวอร์ — §8) |
| cron / batch | รันมือ: python resource/tools/*.py |
| deploy | git push ขึ้น Gitea แล้ว serve โฟลเดอร์เดิม |
ผลที่ตามมา (สำคัญต่อการออกแบบ): ทุกอย่างที่ปกติเก็บใน DB ต้องอยู่ใน JSON หรือ localStorage และทุกฟีเจอร์ต้องทำงานได้แม้ไม่มีเน็ต (SW cache) — นี่คือเหตุผลของ pattern หลายอย่างในเอกสารนี้
2. แผนที่ไฟล์และหน้าที่
ui/
├── index.html shell เดียวของทั้งเว็บ: topbar/footer + <div id="view">
├── router.js hash router: VIEWS + parseHash + inject partial + exec script
├── partials/ view ละไฟล์ (HTML + <style> + <script src> ของตัวเอง)
│ ├── home.html / home.init.js #/ หน้าแรก + marquee + route selector
│ ├── busStop.html / busStop.init.js #/stops รายการป้าย + รูป + ชิปสาย
│ │ busStop.search.js โหมดค้นหา (รหัส/ชื่อ/ใกล้ฉัน)
│ ├── busDetail.html / busDetail.init.js #/routes รายละเอียดสาย + แผนที่ + QR
│ ├── checkSchedule.html / checkSchedule.init.js #/check ตารางเวลาตามจุดจอด
│ ├── stopDetail.html / stopDetail.init.js #/stops/:code ป้ายเดียว + เวลารถ + แผนที่
│ ├── blog.html / blog.init.js #/blog, #/blog/:id
│ ├── about.html / about.init.js #/about
│ ├── credits.html #/credits
│ ├── stats.html / stats.init.js #/stats (สถิติในเครื่อง — §8)
│ ├── schedules.js ★ ท่อกลางอ่านตารางเดินรถ (ทุกหน้าเรียกตัวนี้)
│ ├── otherStop.js ท่อกลาง "จุดขึ้นรถประจำทางอื่นๆ" (station_id 8)
│ └── icons-sprite.svg Lucide sprite (<symbol id="ic-*">)
├── _shared.css สไตล์ร่วมทุกหน้า + motion + toast
├── responsive.css mobile-first layer (base 375px, ขยายที่ 480/640/768/1024/1280/1600)
├── map.css / map.js Leaflet wrapper (ATMap) — ห้ามให้ CSS ภายนอกคุมขนาด svg
├── i18n.js + locales/ ระบบภาษา (th = base, en) — §6
├── motion.js page enter + scroll reveal + loading bar
├── analytics.js สถิติการค้นหาแบบไม่ระบุตัวตน
├── popular.js อันดับ "สายที่เปิดดูบ่อย" (footer)
├── imageurl.js ImgURL.of(url) → เติม ?v=<app-version>
├── pwa.js SW register + auto-update (version.json)
├── sw.js Service Worker: precache + network-first/cache-first
├── version.json เวอร์ชันฝั่งเซิร์ฟเวอร์ (ให้ pwa.js เทียบ)
└── manifest.json PWA manifest
resource/data/ ← "ฐานข้อมูล" ของเว็บ (ดู §5)
resource/tools/ ← สคริปต์ดูแลข้อมูล/เวอร์ชัน (รันมือ ไม่ใช่ build step)
.image/ ← รูปทั้งหมด (ไม่อยู่ใน git; มาจาก resource/images.zip)
3. Boot sequence — เปิดหน้าแรกเกิดอะไรขึ้น
1. GET /ui/index.html
└─ <link> k2d.css, _shared.css, leaflet.css, map.css, responsive.css
└─ inline <script> window.AT_ANALYTICS = {...}
└─ <script defer> imageurl → pwa → i18n → analytics → popular → leaflet
→ map → schedules.js → otherStop → motion → router
2. router.js (defer) รอ I18N.ready → render()
3. render(): parseHash() → VIEWS[name]
├─ fetch('partials/<view>.html', {cache:'no-store'})
├─ view.innerHTML = html
├─ execScripts(view) ← <script> ที่ inject ต้องสร้าง element ใหม่
├─ I18N.apply() ← แปลทุก [data-i18n]
├─ setNavActive() · document.title · scrollTo(0,0)
└─ Motion.enter(#view) ← page enter + เริ่ม scan reveal
4. <script> ของ partial (init) รัน → fetch JSON → วาดการ์ด
└─ MutationObserver ใน motion.js เห็น node ใหม่ → scan reveal อีกครั้ง
จุดที่พลาดบ่อย: สคริปต์ใน partial ทำงานก่อน I18N.apply() ของรอบนั้นเสมอ — ถ้าจะสร้างข้อความ
ต้องใช้ I18N.t() ตั้งแต่ต้น (หรือฟัง event langchange — router จะ re-render ให้อยู่แล้ว)
4. Routing
| hash | view | params | ไฟล์ |
|---|---|---|---|
#/ |
home | — | partials/home.html |
#/stops |
stops | — | partials/busStop.html |
#/stops/:code |
stop | {code}, query ?route=<id> |
partials/stopDetail.html |
#/routes |
routes | — | partials/busDetail.html |
#/routes/:id |
routes | {routeId} |
partials/busDetail.html |
#/check, #/check/:id |
check | {routeId} |
partials/checkSchedule.html |
#/blog, #/blog/:id |
blog | {postId} |
partials/blog.html |
#/about · #/credits · #/stats |
— | — | ตามชื่อ |
กติกา:
- ลิงก์ภายในทั้งหมดเป็น
href="#/..."— ห้าม./x.html(จะโหลดหน้าใหม่) - พารามิเตอร์อ่านจาก
window.__route(router ตั้งให้ก่อนสคริปต์รัน) lastKeyกัน render ซ้ำ hash เดิม —langchangeจะล้างlastKeyแล้ว render ใหม่- เพิ่มหน้าใหม่ = สร้าง
partials/<view>.html+ เพิ่มในVIEWS+parseHash()
5. Data layer — JSON คือฐานข้อมูล
| ไฟล์ | โครงสร้าง | ใช้ที่ |
|---|---|---|
routes.json |
{routes:[{route_id, route_name_th, route_group, web_url, …}]} |
home, busDetail, check, popular |
stations.json |
{stations:[{station_id, station_code, station_name_th, lat, lng, photo?, facilities?, landmarks?}]} |
stopDetail, check, map |
schedules.json |
schema 2: {schema:2, index:true, routes:[{route_id, file}]} → ไฟล์จริง scheduleslist/schedules<id>.json |
partials/schedules.js (ท่อกลาง) |
scheduleslist/schedules<id>.json |
{route_id, directions:[{direction_id, direction_label, service?, days?, stops:[{station_id, km, times[], derive?, groups?}]}]} |
同上 |
busstop_list.json |
array 154 รายการ ป้ายริมทาง (kilometer, latitude, …) |
busStop (รูป + ระยะ) |
stop-km.json |
{route_id: {station_id: km}} (generated) |
autoTimes / check |
holidays.json |
{holidays:[{date, name}]} — เจ้าของกรอกเอง ห้ามเดา |
engine วัน |
route_groups.json |
นิยามหมวดเส้นทาง (สี chip) | busDetail |
provinces.json · affiliates.json · captions/ |
ตัวช่วยแสดงผล/สปอนเซอร์/แคปชัน | home, credits |
geojson-web/*.geojson |
เส้นทางจริง (WGS84) — generated จาก QGIS | ui/map.js |
ท่อข้อมูล (แก้ที่ต้นทางเสมอ):
QGIS Project/*.shp|gpkg ──(qgis-to-web.py)──▶ geojson-web/*.geojson
scheduleslist/*.json ──(merge-schedules.py / schedules-to-grouped.py)──▶ schedules.json (schema 2)
geojson-web/*.geojson ──(stop-km.py)──▶ stop-km.json
derive-times.csv ──(derive-times.py)──▶ เติม derive{} ในไฟล์สาย
กฎเหล็ก: ห้ามแก้ไฟล์ที่ขึ้น "(generated)" ด้วยมือ — แก้ input แล้วรันสคริปต์ซ้ำ
(สคริปต์ทุกตัวมี --check / --list ให้ดูก่อนเขียน)
5.1 เครื่องยนต์วัน (day engine) — อยู่ใน schedules.js ที่เดียว
ลำดับตัดสิน: days[] → service: weekday|holiday → ตรวจคำใน label/note → ไม่ระบุ = แสดงทุกวัน
ถ้ากรองแล้วไม่มีทิศเหลือ → ถอยไปแสดงทั้งหมด + ธง fallback (หน้าเว็บห้ามว่าง)
นักขัตฤกษ์อ่านจาก holidays.json เท่านั้น
5.2 autoTimes / derive — เวลาที่ไม่ได้กรอก
autoTimes: true+speedKmh→ คำนวณจากจุดที่มีเวลาจริง + ระยะทาง (stop-km.json)derive: {from_station_id, offset_min}→ เวลาจุดนั้น = เวลาจุดอ้างอิง ± n นาที- ทั้งคู่ ไม่ถูกเขียนกลับลง JSON — คำนวณสดทุกครั้ง และแสดงด้วยกรอบเส้นประ + ข้อความ "ประมาณ"
6. Shared engines (frontend modules)
| module | ไฟล์ | API หลัก | ใครเรียก |
|---|---|---|---|
| Router | ui/router.js |
render(), window.__route |
shell |
| i18n | ui/i18n.js |
t(key, vars) · apply() · setLang() · ready |
ทุกหน้า |
| Schedules | partials/schedules.js |
records/route/directions/times/countTrips/dayInfo/serviceOf/… |
check, busDetail, home, stopDetail |
| OtherStop | partials/otherStop.js |
load() · forRoute() · allStops() · forStation() (รองรับรหัสเพี้ยนสลับหลัก) |
schedules, checkSchedule, stopDetail |
| Map | ui/map.js (ATMap) |
route(id) · forStop(el, code) · proposal(el, spec, onPick) · nearMe |
busDetail, stopDetail, blog, busStop |
| Motion | ui/motion.js |
enter(el) · scan() · loading(bool) |
router, ทุกหน้า (auto) |
| Analytics | ui/analytics.js |
search({q,scope,results}) · pageview() · view() · report() · optOut() |
busStop.search, stopDetail, pwa(hashchange) |
| Popular | ui/popular.js |
hit(id) · ranked(n) · mount(ul, routes) |
router (footer) |
| ImgURL | ui/imageurl.js |
of(url) → เติม ?v= |
ทุกที่ที่แสดงรูป |
| PWA | ui/pwa.js |
SW register + ATUpdate.check() |
shell |
หลักการ: ตรรกะที่ใช้ร่วมกันต้องอยู่ในไฟล์กลางไฟล์เดียว (Schedules/OtherStop/ATMap) ห้าม copy ไปไว้ในหน้า — จะทำให้หน้าต่าง ๆ แสดงผลไม่ตรงกัน
7. Cache & การปล่อยเวอร์ชันใหม่ (ไม่มีใครต้องกด Ctrl+Shift+R)
ผู้ใช้เปิดเว็บ
├─ 1. index.html โหลด shell ด้วย ?v=<version> → HTTP cache เห็นเป็นไฟล์ใหม่
│ (bump-version.py เติมให้ทุกครั้งที่ปล่อยเวอร์ชัน)
├─ 2. SW: HTML/CSS/JS/JSON = network-first (cache:"no-store")
│ รูป/ฟอนต์ = cache-first · ออฟไลน์ fallback = offline.html
├─ 3. pwa.js: reg.update() ทุกเปิดหน้า + ทุก 30 นาที
└─ 4. pwa.js: fetch version.json ทุก 5 นาที / กลับมาที่แท็บ / เน็ตกลับมา
└─ version ≠ meta app-version → toast "กำลังอัปเดต…" → reload ครั้งเดียว/เวอร์ชัน
ขั้นตอนปล่อยเวอร์ชัน (คำสั่งเดียว):
python resource/tools/bump-version.py # sw.js VERSION + meta + ?v= (รูป/shell) + version.json
python resource/tools/bump-version.py --check # ต้องขึ้น ✓ ทุกบรรทัด
กติกา: แก้ sw.js เอง → ต้อง bump · เพิ่ม/ลบไฟล์ใน PRECACHE → ต้อง bump
· แก้รูปทับชื่อเดิม → ต้อง bump (ไม่งั้น cache-first คืนของเก่า)
8. สถิติ (analytics) — privacy-first แบบ Umami
ผู้ใช้ค้นหา → Analytics.search({q, scope, results})
├─ cleanTerm(): ตัดอีเมล · @handle · เลข ≥5 หลัก · cap 60 ตัวอักษร · คำ <2 ตัวไม่เก็บ
├─ debounce 900ms → 1 คำต่อการพิมพ์หนึ่งครั้ง
├─ localStorage at_stats_v1: days{pv,q,nores} · terms{q:[n,ts]} · empty · views{kind:id:[n,ts]}
└─ ถ้าตั้ง window.AT_ANALYTICS = {endpoint, siteId} → POST <endpoint>/api/send (สเปก Umami)
เกตความเป็นส่วนตัว: DNT · Global Privacy Control · สวิตช์ opt-out (at_stats_optout)
- ค่าเริ่มต้น ไม่ส่งออกเน็ตเลย (endpoint ว่าง) — ตัวเลขเป็นของเครื่องผู้ใช้แต่ละคน
- หน้า
#/statsอ่านผ่านAnalytics.report()— มี KPI, กราฟ 14 วัน, top คำค้น, top หน้า, "ค้นแล้วไม่พบ", ดาวน์โหลด JSON, ล้างข้อมูล - เพดานกัน localStorage บวม: 300 คำ · 200 หน้า · 120 วัน
9. Failure modes & fallbacks (ออกแบบไว้แล้ว — ห้ามทำให้พังกว่าเดิม)
| สถานการณ์ | ระบบทำอะไร |
|---|---|
| ออฟไลน์ | SW precache + offline.html · หน้าเดิมยังเปิดได้ |
fetch partial/JSON ล้มเหลว |
router แสดงข้อความ router.loadFail (ไม่จอขาว) |
| ไม่มีไฟล์รูป (jpg/jpeg/webp/png) | ไล่ลองนามสกุล → ไม่มีเลย = ไม่แสดง <img> (ไม่เหลือช่องว่าง) |
| กรองตามวันแล้วไม่มีทิศ | ถอยไปแสดงทุกวัน + ธง fallback |
| ไม่มี geojson ของสาย | คงพื้นที่แผนที่ + ป้าย blog.noGeo |
| คำแปลขาด | t() คืน key เดิม (เห็นชัดว่าลืม) · apply() ไม่แตะ DOM ถ้าโหลดไฟล์ภาษาไม่ได้ |
| เบราว์เซอร์เก่าไม่มี SW/IO | ฟีเจอร์นั้นข้ามไป · เนื้อหายังอ่านได้ (JS ไม่ซ่อนอะไรถาวร) |
10. สูตรขยายงาน (recipes)
เพิ่มหน้าใหม่
ui/partials/<view>.html(+<style>และ<script src="./partials/<view>.init.js">ท้ายไฟล์)ui/router.js: เพิ่มในVIEWS+parseHash()- ข้อความทุกชิ้นใส่
data-i18n="…"+ เติมคีย์ในlocales/th.jsonและen.json ui/sw.jsPRECACHE+python resource/tools/bump-version.py
เพิ่มคำแปล
- เติมคีย์เดียวกันใน
th.jsonและen.json(ไฟล์เดียวต่อภาษา) python resource/tools/check-i18n.py→ ต้องไม่ ERROR
เพิ่มไอคอน: ดาวน์โหลดจาก lucide.dev → .image/icons/lucide/ → เพิ่ม <symbol id="ic-...">
ใน partials/icons-sprite.svg → อัปเดตรายการใน #/credits
เพิ่ม/แก้เส้นทาง
- แก้ shapefile ใน QGIS แล้ว
python resource/tools/qgis-to-web.py(ห้ามแก้ geojson มือ) - แก้ตารางเวลาใน
resource/data/scheduleslist/schedules<id>.json(หรือ GUIschedules-editor.html) python resource/tools/stop-km.pyถ้าพิกัด/เส้นเปลี่ยน →audit-geojson.pyตรวจสุขภาพข้อมูล
เพิ่มบทความ → ui/partials/blog-data/textN.json (schema ใน blog-data/README.md)
11. Performance notes
- รูป:
loading="lazy"+ImgURL.of()· รูปป้าย/สถานี hydrate เฉพาะใบที่มองเห็น (StopsRender.hydrate) - Reveal ใช้เฉพาะ
opacity/transform(ไม่เกิด CLS) · เคลียร์ class หลังอนิเมชันจบ - Leaflet โหลดเฉพาะหน้าที่มีแผนที่ และห้ามให้ CSS ภายนอกกำหนดขนาด
svg.leaflet-zoom-animated - ฟอนต์ K2D ฝังใน repo (
ui/vendor/fonts/) + precache ครบ → ออฟไลน์ได้จริง - ไม่มี bundler: จำนวน request มากกว่า แต่ทุกไฟล์ precache ไว้ → เปิดซ้ำเร็วและออฟไลน์ได้
12. Checklist ก่อน commit / ปล่อยเวอร์ชัน
python resource/tools/check-i18n.py # ERROR = ห้าม commit (คีย์ขาด/ซ้ำ)
python resource/tools/bump-version.py --check # ต้อง ✓ ทุกบรรทัด
python resource/tools/audit-geojson.py # ถ้าแตะข้อมูลเส้นทาง
node --check ui/<ไฟล์ที่แก้>.js # ไฟล์ JS ทุกไฟล์ที่แก้
ตรวจในเบราว์เซอร์ (เปิด http://localhost:8090/ui/index.html):
- ไล่ทุก route:
#/ #/stops #/routes/101 #/check #/stops/at_main_terminal #/credits #/about #/blog #/stats document.documentElement.scrollWidth - clientWidth === 0(ไม่มีล้นแนวนอน) ที่ 375px และ 1280px- Console ไม่มี error · แผนที่แสดง (
getBoundingClientRect()ของ.at-map> 0) - เปลี่ยนภาษา TH/EN แล้วข้อความครบ (ไม่มี key เปล่า ๆ)
- ออฟไลน์ (DevTools → Network offline) แล้ว reload — ยังเปิดหน้าได้
13. Glossary
| คำ | ความหมายในโปรเจกต์นี้ |
|---|---|
| view / partial | หนึ่งหน้าจอ = partials/<view>.html ที่ router fetch มาฉีดใส่ #view |
| shell | ui/index.html — topbar/footer/#view เท่านั้นที่โหลดจริงครั้งเดียว |
| ท่อกลาง | ไฟล์ JS ที่รวมตรรกะไว้ที่เดียวให้ทุกหน้าเรียก (Schedules, OtherStop, ATMap) |
| schema 2 | รูปแบบ schedules.json ที่แยกไฟล์ต่อสายใน scheduleslist/ |
| autoTimes / derive | เวลาที่คำนวณจากจุดอ้างอิง ไม่ได้กรอกตรง ๆ (แสดงเป็นค่าประมาณ) |
| fallback flag | ธงบอกว่า engine ถอยไปใช้ข้อมูลทั้งหมดเพราะกรองแล้วว่าง |
| generated | ไฟล์ที่สคริปต์สร้าง ห้ามแก้มือ (geojson-web, stop-km.json, version.json) |
| bump | การอัปเวอร์ชันเดียวทั้งระบบผ่าน bump-version.py |
เอกสารนี้ต้องเป็นจริงตามโค้ด — ถ้าแก้สถาปัตยกรรมแล้วอย่าลืมแก้ที่นี่ด้วย (เช่น เพิ่ม engine ใหม่, เปลี่ยนกลไก cache, เพิ่มที่เก็บข้อมูล)