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
This commit is contained in:
1 parent
fcdab3ac80
commit
246b864c06
3 files changed
+411
-1
No files matched your search
@@ -9,6 +9,19 @@
|
||||
|
||||
อ่านไฟล์นี้ก่อนทำงานเสมอ เพื่อประหยัด token อย่าเดาโครงสร้าง
|
||||
|
||||
## แผนที่เอกสาร (อ่านตามงาน)
|
||||
|
||||
| งาน | เอกสาร |
|
||||
|---|---|
|
||||
| เข้าใจระบบทั้งหมด (boot, routing, data layer, engines, cache, analytics, recipes) | **`ARCHITECTURE.md`** ← ละเอียดที่สุด |
|
||||
| กฎการแก้โค้ด / ห้ามทำอะไร | ไฟล์นี้ (`AGENTS.md`) |
|
||||
| สี ฟอนต์ ระยะ กฎดีไซน์ | `DESIGN.md` (รัฐธรรมนูญ — แก้ก่อนเขียนโค้ด) |
|
||||
| ข้อมูลเส้นทางจาก QGIS | `resource/data/QGIS Project/GeoJSON-2/README.md` |
|
||||
| schema บทความ / หน้าเกี่ยวกับ | `ui/partials/blog-data/README.md` · `about-data/README.md` |
|
||||
| ภาพรวมโปรเจกต์ + วิธีรัน | `README.md` |
|
||||
|
||||
> ถ้าเอกสารขัดกัน: `DESIGN.md` ชนะเรื่องหน้าตา · `AGENTS.md` ชนะเรื่องวิธีแก้โค้ด · `ARCHITECTURE.md` ชนะเรื่อง "ระบบทำงานยังไง" (ต้องอัปเดตให้ตรงโค้ดเสมอ)
|
||||
|
||||
---
|
||||
|
||||
## โครงสร้าง
|
||||
@@ -149,6 +162,35 @@ python -m http.server 8090 # เปิด http://localhost:8090/ui/index.
|
||||
- เพิ่มหน้าใหม่: ไม่ต้องแก้อะไร (router + observer จัดการ) — เพียงใช้คลาสการ์ดเดิม (`mu-card`, `mu-stop-card`, `mu-zone`, `mu-summary`, `mu-stat`, …)
|
||||
- อย่าลืม `./motion.js` ใน `PRECACHE` ของ `sw.js` (มีแล้ว) และ bump `VERSION` เมื่อแก้ SW
|
||||
|
||||
## สถิติ (ui/analytics.js + หน้า #/stats) — privacy-first แบบ Umami
|
||||
|
||||
**แนวคิด:** อิง Umami (MIT) — ไม่มีคุกกี้/ไม่มี fingerprint/ไม่เก็บ IP-UA แต่ repo นี้ไม่มี backend
|
||||
จึงเก็บรวมในเครื่อง (localStorage) เป็นค่าเริ่มต้น และ **ไม่ส่งออกเน็ตเลย**
|
||||
|
||||
| เก็บ | ไม่เก็บ |
|
||||
|---|---|
|
||||
| จำนวนเปิดหน้า/วัน · คำค้น (ทำให้ปลอดภัยแล้ว) + จำนวน + เวลาล่าสุด · คำที่ค้นไม่พบ · views ของ route/stop | IP · UA · พิกัด · คุกกี้ · รหัสเครื่อง · ประวัติข้ามเว็บ · ไม่มีรหัสผู้ใช้ถาวร |
|
||||
|
||||
**กติกา**
|
||||
1. คำค้นต้องผ่าน `cleanTerm()` เสมอ (ตัดอีเมล · @handle · เลขยาว ≥5 หลัก · cap 60 ตัวอักษร · คำ <2 ตัวไม่เก็บ)
|
||||
2. `Analytics.search()` **debounce 900ms ในตัว** — เรียกได้ทุกครั้งที่ผลค้นเปลี่ยน ไม่ต้อง debounce เอง
|
||||
3. เคารพ `Do Not Track` + `Global Privacy Control` + สวิตช์ในหน้า `#/stats` (`at_stats_optout`)
|
||||
4. **ห้ามเพิ่มคุกกี้/สคริปต์ภายนอก** — ถ้าต้องการเซิร์ฟเวอร์ให้ตั้ง `window.AT_ANALYTICS = {endpoint, siteId}`
|
||||
ชี้ Umami ของตัวเอง (payload ตรงสเปก `/api/send`) อย่าเขียน endpoint ใหม่
|
||||
5. เพดานกัน localStorage บวม: 300 คำ · 200 หน้า · 120 วัน · หน้าใหม่เรียกแค่ `search()` / `view()` (pageview ผูก hashchange แล้ว)
|
||||
|
||||
## อัปเดตเวอร์ชัน — ผู้ใช้ไม่ต้องกด Ctrl+Shift+R (ทั้งคอมและมือถือ)
|
||||
|
||||
```
|
||||
python resource/tools/bump-version.py # คำสั่งเดียวจบ
|
||||
python resource/tools/bump-version.py --check # ต้อง ✓ ทุกบรรทัด
|
||||
```
|
||||
|
||||
คำสั่งเดียวอัปเดตครบ: `sw.js VERSION` · `meta app-version` · โลโก้ `?v=` · **shell js/css `?v=`** · **`ui/version.json`**
|
||||
`ui/pwa.js` ตรวจ `version.json` (เปิดหน้า · ทุก 5 นาที · กลับมาที่แท็บ · เน็ตกลับมา) แล้วขึ้น toast + รีโหลดเอง
|
||||
(รีโหลดครั้งเดียวต่อเวอร์ชัน — กันลูป) · แท็บถูกซ่อน = รีโหลดเงียบ
|
||||
**กติกา:** เพิ่ม/ลบไฟล์ใน `PRECACHE` หรือแก้ `sw.js` = ต้อง bump · แก้รูปทับชื่อเดิม = ต้อง bump
|
||||
|
||||
## หน้ารายละเอียดป้าย `#/stops/<รหัสป้าย>` — ข้อมูลมาจากไหน
|
||||
|
||||
หน้า `ui/partials/stopDetail.html` เป็น "โครงเปล่า" ล้วน ๆ (มีแต่ `<style>` + element ที่มี id)
|
||||
@@ -449,6 +491,7 @@ WARN = ค่าว่างเปล่า (อาจตั้งใจ) · ค
|
||||
```
|
||||
python resource/tools/bump-version.py ← +1 รอบ (อัปเดต sw.js + meta + โลโก้ ให้ตรงกัน)
|
||||
python resource/tools/bump-version.py --check ← ตรวจว่าทุกที่ตรงกัน
|
||||
→ ให้ผู้ใช้กด Ctrl+Shift+R ครั้งเดียว = รูปทั้งหมดโหลดใหม่
|
||||
→ **ไม่ต้องให้ผู้ใช้กดอะไร**: `pwa.js` เทียบ `version.json` กับ `meta app-version` แล้วรีโหลดเอง
|
||||
(ดู `ARCHITECTURE.md` §7) · ใช้ Ctrl+Shift+R เฉพาะตอนพัฒนาเครื่องตัวเอง
|
||||
```
|
||||
⚠️ รูปที่เพิ่ม "ชื่อใหม่" (ไม่ทับของเดิม) เห็นผลทันที ไม่ต้อง bump
|
||||
+337
@@ -0,0 +1,337 @@
|
||||
# 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, เพิ่มที่เก็บข้อมูล)*
|
||||
@@ -5,6 +5,27 @@ Static HTML mockup / ดีไซน์ต้นแบบเว็บข้อ
|
||||
> repo นี้เป็น **static HTML + vanilla JS** (ไม่มี backend / framework / build step)
|
||||
> ส่วน implementation จริง (Next.js) อยู่ที่ `web-at-transit`
|
||||
|
||||
## เอกสาร (อ่านตามบทบาท)
|
||||
|
||||
| ไฟล์ | เนื้อหา | ใครอ่าน |
|
||||
|---|---|---|
|
||||
| **`ARCHITECTURE.md`** | สถาปัตยกรรมเต็ม: boot sequence, routing, data layer, shared engines, cache/อัปเดต, analytics, failure modes, recipes | คน/AI ที่ต้องเข้าใจ "ระบบทำงานยังไง" |
|
||||
| `AGENTS.md` | กฎการแก้โค้ด (ห้ามทำอะไร, ความจริงแต่ละเรื่องอยู่ที่ไหน) | AI coding agent |
|
||||
| `DESIGN.md` | ระบบดีไซน์: โทเคนสี/ฟอนต์/ระยะ + กฎ "ห้ามทำ" | งาน UI ทุกชิ้น |
|
||||
| `resource/data/QGIS Project/GeoJSON-2/README.md` | วิธี export เส้นทางจาก QGIS → geojson | งานข้อมูลเส้นทาง |
|
||||
| `ui/partials/blog-data/README.md` · `about-data/README.md` | schema เนื้อหาบทความ/หน้าเกี่ยวกับ | งานเนื้อหา |
|
||||
|
||||
## ระบบทำงานยังไง (ย่อ)
|
||||
|
||||
1. `ui/index.html` คือ shell เดียว — topbar/footer + `<div id="view">`
|
||||
2. `ui/router.js` อ่าน `location.hash` → `fetch('partials/<view>.html')` → ฉีดเข้า `#view` → รัน `<script>` ในไฟล์นั้น
|
||||
3. แต่ละ view ดึงข้อมูลจาก `resource/data/*.json` ตรง ๆ (ไม่มี API)
|
||||
4. ตรรกะร่วมอยู่ใน "ท่อกลาง": `partials/schedules.js` (ตารางเดินรถ/วัน) · `partials/otherStop.js` · `ui/map.js` (ATMap)
|
||||
5. `ui/sw.js` precache ทุกไฟล์ → เปิดซ้ำเร็ว/ออฟไลน์ได้ · `ui/pwa.js` + `version.json` อัปเดตเองโดยผู้ใช้ไม่ต้องกดอะไร
|
||||
6. สถิติ (`ui/analytics.js`) เก็บในเครื่องแบบไม่ระบุตัวตน — ดูที่ `#/stats`
|
||||
|
||||
รายละเอียดทั้งหมด (diagram, API ของแต่ละ engine, checklist ทดสอบ) → `ARCHITECTURE.md`
|
||||
|
||||
## โครงสร้าง
|
||||
|
||||
```
|
||||
@@ -45,6 +66,15 @@ http://localhost:8090/ui/index.html
|
||||
3. **ห้ามเปิด `file://`** — fetch JSON + relative path จะใช้ไม่ได้ ต้องผ่าน static server เสมอ
|
||||
4. เปลี่ยน port ได้ด้วย `make serve PORT=8080`
|
||||
|
||||
## งานที่ต้องรันก่อน commit / ปล่อยเวอร์ชัน
|
||||
|
||||
```bash
|
||||
python resource/tools/check-i18n.py # ERROR = ห้าม commit (คีย์ขาด/ซ้ำ)
|
||||
python resource/tools/bump-version.py --check # ต้อง ✓ ทุกบรรทัด
|
||||
python resource/tools/bump-version.py # ปล่อยเวอร์ชันใหม่ (ผู้ใช้ไม่ต้องกด Ctrl+Shift+R)
|
||||
node --check ui/<ไฟล์ที่แก้>.js
|
||||
```
|
||||
|
||||
## การจัดการรูปภาพ (images)
|
||||
|
||||
รูปทั้งหมด (~31MB) อยู่ใน folder hidden `.image/` (ถูก `.gitignore` → ไม่ push ขึ้น git)
|
||||
|
||||
Reference in new issue
Block a user