- 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
338 lines
26 KiB
Markdown
338 lines
26 KiB
Markdown
# 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 ครั้งเดียว/เวอร์ชัน
|
|
```
|
|
|
|
**ขั้นตอนปล่อยเวอร์ชัน (คำสั่งเดียว):**
|
|
|
|
```bash
|
|
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 / ปล่อยเวอร์ชัน
|
|
|
|
```bash
|
|
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, เพิ่มที่เก็บข้อมูล)*
|