Files
Bkk1234 246b864c06 docs: add ARCHITECTURE.md and refresh README/AGENTS indexes
- 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
2026-11-04 00:19:24 +07:00

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 — — ตามชื่อ

กติกา:

  1. ลิงก์ภายในทั้งหมดเป็น href="#/..." — ห้าม ./x.html (จะโหลดหน้าใหม่)
  2. พารามิเตอร์อ่านจาก window.__route (router ตั้งให้ก่อนสคริปต์รัน)
  3. lastKey กัน render ซ้ำ hash เดิม — langchange จะล้าง lastKey แล้ว render ใหม่
  4. เพิ่มหน้าใหม่ = สร้าง 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)

เพิ่มหน้าใหม่

  1. ui/partials/<view>.html (+ <style> และ <script src="./partials/<view>.init.js"> ท้ายไฟล์)
  2. ui/router.js: เพิ่มใน VIEWS + parseHash()
  3. ข้อความทุกชิ้นใส่ data-i18n="…" + เติมคีย์ใน locales/th.json และ en.json
  4. ui/sw.js PRECACHE + python resource/tools/bump-version.py

เพิ่มคำแปล

  1. เติมคีย์เดียวกันใน th.json และ en.json (ไฟล์เดียวต่อภาษา)
  2. python resource/tools/check-i18n.py → ต้องไม่ ERROR

เพิ่มไอคอน: ดาวน์โหลดจาก lucide.dev → .image/icons/lucide/ → เพิ่ม <symbol id="ic-..."> ใน partials/icons-sprite.svg → อัปเดตรายการใน #/credits

เพิ่ม/แก้เส้นทาง

  1. แก้ shapefile ใน QGIS แล้ว python resource/tools/qgis-to-web.py (ห้ามแก้ geojson มือ)
  2. แก้ตารางเวลาใน resource/data/scheduleslist/schedules<id>.json (หรือ GUI schedules-editor.html)
  3. 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):

  1. ไล่ทุก route: #/ #/stops #/routes/101 #/check #/stops/at_main_terminal #/credits #/about #/blog #/stats
  2. document.documentElement.scrollWidth - clientWidth === 0 (ไม่มีล้นแนวนอน) ที่ 375px และ 1280px
  3. Console ไม่มี error · แผนที่แสดง (getBoundingClientRect() ของ .at-map > 0)
  4. เปลี่ยนภาษา TH/EN แล้วข้อความครบ (ไม่มี key เปล่า ๆ)
  5. ออฟไลน์ (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, เพิ่มที่เก็บข้อมูล)