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

498 lines
54 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# AGENTS.md — คำสั่งสำหรับ AI coding agent
โปรเจกต์: **web-at-transit-mock** — mockup/ดีไซน์ HTML ต้นแบบของเว็บข้อมูลการเดินรถ
สถานีขนส่งผู้โดยสารจังหวัดอ่างทอง (Atroute)
> หมายเหตุ: repo นี้เป็น **static HTML mockup** (ยังไม่มี backend / framework)
> ส่วน implementation จริง (Next.js) อยู่ที่ `web-at-transit` — เวลาทำงานกับ repo นี้
> ให้แก้ HTML/CSS ตรง ๆ อย่าแนะนำให้ย้ายไป framework
อ่านไฟล์นี้ก่อนทำงานเสมอ เพื่อประหยัด 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` ชนะเรื่อง "ระบบทำงานยังไง" (ต้องอัปเดตให้ตรงโค้ดเสมอ)
---
## โครงสร้าง
```
web-at-transit-mock/
├── maintheme.png ← ภาพธีม/ดีไซน์ต้นแบบ (เปิดดูเพื่อจับอารมณ์สีและ layout)
├── ui/ ← ★ Single-page app (static HTML + vanilla JS)
│ ├── index.html SHELL หน้าเดียว — header + <div id="view"> + footer
│ ├── router.js hash router: สลับ view โดยไม่โหลดหน้าใหม่
│ ├── sw.js / pwa.js / manifest.json ← PWA + อัปเดตอัตโนมัติ (ดูข้อ 11)
│ ├── _shared.css สไตล์ร่วมทุก view (โหลดจาก shell)
│ ├── responsive.css ★ Mobile-first layer — base = iPhone 8 (375px)
│ │ ขยายตาม min-width: 480/640/768/1024/1280/1600px
│ │ (component ใน #view ต้องใช้ prefix `#view`)
│ ├── partials/ ★ view ละ 1 ไฟล์ (router fetch + inject ที่ #view)
│ │ ├── home.html + home.init.js ← #/ (selectors + marquee)
│ │ ├── busStop.html ← #/stops
│ │ ├── busDetail.html ← #/routes, #/routes/:id
│ │ ├── busDetailExpanded.html ← #/routes/expanded
│ │ ├── stopDetail.html ← #/stops/:code
│ │ ├── credits.html ← #/credits
│ │ └── icons-sprite.svg ← Lucide sprite
│ ├── busStop.html / busDetail.html / ... ← เหลือแค่ redirect stub → #/...
├── resource/
│ ├── data/ ข้อมูล mock: routes.json, schedules.json, stations.json,
│ │ provinces.json, route_groups.json
│ └── images.zip ← รูปทั้งหมดบีบรวม (แตกด้วย setup.sh)
└── .image/ ← รูปทั้งหมด (hidden — เกิดหลังรัน setup.sh, ไม่ commit)
```
**ทุกหน้าเป็น hash URL** (`#/stops`, `#/routes/101`, `#/stops/at_main_terminal`) —
ลิงก์ภายในทั้งหมดเป็น `<a href="#/...">` ไม่มีการโหลดหน้าใหม่เลย (no reflash)
## วิธีเปิดดูผลงาน
```bash
cd D:\Git\web-at-transit-mock
python -m http.server 8090 # เปิด http://localhost:8090/ui/index.html
```
(ใช้ static server เสมอ — ห้ามเปิด file:// เพราะ relative path และ fetch JSON จะพัง)
## กฎบังคับ
1. **ห้ามใส่ framework/build step** — repo นี้เป็น static HTML + vanilla JS เท่านั้น
2. **ทุกหน้าเป็น SPA view ผ่าน hash router** — ห้ามสร้างไฟล์ HTML หน้าใหม่
ถ้าจะเพิ่มหน้าจอใหม่: สร้าง `partials/<view>.html` (+ `<script>`/`<style>` ในไฟล์นั้น)
แล้วเพิ่ม route ใน `ui/router.js` (VIEWS + parseHash)
3. **ลิงก์ภายในใช้ `href="#/..."` เสมอ** — ห้าม `href="./xxx.html"` (จะโหลดหน้าใหม่)
และห้าม `location.href`/`location.replace` ไปหน้า html ยกเว้นใน redirect stub
4. **`<style>` และ `<script>` ของ view ให้อยู่ใน partial ของมัน** — router inject แล้ว
รัน `<script>` ให้อัตโนมัติ ถ้า script ต้องอ่าน params ให้ใช้ `window.__route`
5. **ทุกหน้าโหลด `_shared.css`** — สไตล์ร่วมต้องอยู่ที่นี่ ไม่ใช่ inline ในแต่ละหน้า
(ยกเว้นสไตล์เฉพาะหน้าที่จำเป็นจริง ๆ ให้อยู่ใน `<style>` ใน partial)
6. **class ที่ขึ้นต้น `mu-`** = component ร่วม (เช่น `.mu-card`, `.mu-cover`, `.mu-hero`)
— ถ้าจะเพิ่ม component ใหม่ ใช้ prefix `mu-` ด้วย
7. **รูปอ้างอิงผ่าน `../.image/...`** — อย่า copy รูปเข้า ui/
8. **ข้อมูลตัวอย่างมาจาก `resource/data/*.json`** — ถ้าจะเพิ่มเส้นทาง/ป้าย ต้องเพิ่มข้อมูล
ใน JSON ให้ตรงกัน (ไม่ hardcode เฉพาะหน้า)
9. **ข้อความ UI เป็นภาษาไทย** — ภาษาอังกฤษใช้เป็น label รองเท่านั้น
10. **อ่าน `DESIGN.md` ก่อนแก้ UI ทุกครั้ง** — มีกฎ "ห้ามทำ" ที่กันสไตล์ AI genric
และโทเคนสี/ฟอนต์ตายตัว
11. **ไอคอนใช้ระบบ Lucide sprite เท่านั้น** — ห้ามใช้ emoji แทนไอคอน (DESIGN.md ข้อ 4):
- ไอคอนต้นฉบับ (MIT): `.image/icons/lucide/`
- sprite: `ui/partials/icons-sprite.svg` (symbol ชื่อ `ic-<ชื่อ>`)
- ใช้งาน: `<svg class="ic" aria-hidden="true"><use href="#ic-ชื่อ"/></svg>` (CSS `.ic` ใน `_shared.css`)
- **เพิ่มไอคอนใหม่**: ดาวน์โหลดจาก https://lucide.dev → เก็บ SVG ใน `.image/icons/lucide/`
→ เพิ่ม `<symbol>` ใน sprite → อัปเดตรายการใน `ui/credits.html`
12. `main-theme.css` (อ้างอิงจาก HTML) **ไม่อยู่ใน repo นี้** — ถ้าแก้สไตล์ให้แก้ที่
`_shared.css` แทน อย่าไปสร้าง main-theme.css ใหม่
13. **PWA / Service Worker (ui/sw.js)** — ห้ามแก้กลไกโดยไม่เข้าใจ:
- HTML/CSS/JS/partials/JSON → network-first (ออนไลน์ได้ของใหม่เสมอ, ออฟไลน์ใช้ cache)
- รูป/ฟอนต์ → cache-first
- **เนื้อหา HTML/CSS/JS เปลี่ยน = เห็นผลทันทีโดยผู้ใช้ไม่ต้องล้างแคช** (network-first)
- เฉพาะแก้ `sw.js` เองเท่านั้น ต้อง **bump `VERSION`** ใน sw.js (เช่น `2026.09.02.9`)
→ cache ใหม่ถูกสร้าง + cache เก่าถูกลบอัตโนมัติตอน activate
- อย่าลืม: ทุกหน้า HTML ต้องมี `<link rel="manifest">` + `<script src="./pwa.js">`
(ถ้าสร้างหน้าใหม่) และถ้าเพิ่มไฟล์ shell (หน้า/partial/CSS/JS หลัก) ให้เพิ่มใน `PRECACHE`
14. **หลายภาษา (i18n)** — ระบบอยู่ใน `ui/i18n.js` (ไทย/อังกฤษ):
- **ข้อความ UI ห้าม hardcode ภาษาเดียว** — ใช้ `data-i18n="key"` บน element
(ข้อความ) หรือ `data-i18n-attr="placeholder:key,aria-label:key"` (attribute)
- ตัวเลขในข้อความ: `data-i18n="key" data-i18n-n="6"` → dict ใช้ `{n}` (เช่น `... · {n} เส้นทาง`)
- **เพิ่มคำแปล**: เติม key ใน `DICT.th` + `DICT.en` ใน `ui/i18n.js` (key หาย = แสดง key เปล่า ๆ ให้เห็นชัด)
- ข้อความที่ JS สร้าง: เรียก `window.I18N.t('key', {n})` (ดู `partials/home.init.js`)
- ภาษาเริ่มต้น: อ่านจาก `localStorage('at_lang')` → ถ้าไม่มี ใช้ภาษา browser (`navigator.language`)
- ปุ่มสลับ: `<button data-i18n-switch="en">EN</button>` — เปลี่ยนภาษาแล้ว router
จะ render หน้าใหม่ให้อัตโนมัติ (ฟัง event `langchange`)
- **ชื่อเฉพาะ (ชื่อสถานี/จังหวัด/สายรถ) ไม่ต้องแปล** — คงภาษาไทย
## ข้อมูลเส้นทางจาก GIS (QGIS → GeoJSON → แผนที่)
- **ห้ามแก้ `resource/data/geojson-web/*.geojson` ด้วยมือ** — เป็นไฟล์ที่ "สร้าง" จาก shapefile ใน
`resource/data/QGIS Project/*.shp` (ตารางจับคู่ `SHP_MAP` อยู่ในสคริปต์) — user แก้ใน QGIS แล้วกด Save
- แปลง/อัปเดตด้วยคำสั่งเดียว (ไม่ใช่ build step ของเว็บ — รันมือเมื่อข้อมูลเส้นเปลี่ยน):
```bash
python resource/tools/qgis-to-web.py --check # ตรวจก่อน (ไม่เขียนไฟล์) — "เหมือนเดิม ✓" = ไม่มีอะไรเปลี่ยน
python resource/tools/qgis-to-web.py # เขียนจริง (--from geojson = ทางเดิมผ่าน GeoJSON-2/)
python resource/tools/qgis-to-web.py --list # ดูตารางรหัสสาย ↔ ไฟล์ .shp
```
- สคริปต์จะ**ปฏิเสธ**ไฟล์ที่ CRS ไม่ใช่ WGS84 (พิกัดเป็น UTM) และตัดจุดที่หลุดกรอบประเทศไทย
- **ตรวจสุขภาพข้อมูลก่อนใช้**: `python resource/tools/audit-geojson.py` (CRS · พิกัดว่าง/ซ้ำ ·
ช่วงเส้นตัดตรง · ปลายเส้นตรงจุดจอดไหม · ไฟล์ซ้ำ/ไม่ถูกใช้)
- กติกา + ตารางเลเยอร์↔รหัสสาย + วิธี export: `resource/data/QGIS Project/GeoJSON-2/README.md`
- แผนที่ใช้ Leaflet (vendor ใน `ui/vendor/leaflet/`) — **ห้ามให้ CSS ภายนอกกำหนด width/height ของ
`svg.leaflet-zoom-animated`** (จะถูกยุบเป็น 0×0 แล้ว "เส้นทางไม่แสดง" — มี guard ใน `ui/map.css` แล้ว)
- ตรวจว่าเส้นทางแสดงจริง ต้องวัด `getBoundingClientRect()` เทียบกับกล่องแผนที่ — นับ `<path>` ใน DOM ไม่พอ
> 📌 กติกาจุดขึ้นรถประจำทางอื่นๆ (`8 other_stop.json`): ดู **`resource/data/8 other_stop.md`** — ระบุสายที่ **ห้ามเพิ่ม** entry และรายการที่ห้ามลบ
## ลำดับการอ่านไฟล์เมื่อเริ่มงาน
1. `AGENTS.md` (ไฟล์นี้) → `DESIGN.md` (ถ้าแตะ UI)
2. หน้าที่เกี่ยวข้อง (`ui/*.html`) + `_shared.css` + `maintheme.png` (ถ้าต้องการอารมณ์ดีไซน์)
3. `resource/data/*.json` ที่เกี่ยวข้อง (ถ้าแตะข้อมูล)
## หมายเหตุ
- commit ล่าสุดเน้น: sponsor marquee (เลื่อนสปอนเซอร์), ลบไฟล์ backup HTML
- `.gitignore` ว่างเปล่า — ถ้าเพิ่มไฟล์ขยะ (เช่น .DS_Store) ให้เพิ่มใน .gitignore
- งานถัดไปที่คาดว่าเกี่ยวข้อง: นำดีไซน์นี้ไป implement ใน `web-at-transit` (Next.js)
## การเคลื่อนไหว (ui/motion.js) — อนิเมชันร่วมทุกหน้า
**ไฟล์:** `ui/motion.js` (โหลดใน `index.html` ก่อน `router.js`) + CSS ท้าย `_shared.css` (`.mu-loadbar`, `#view.mu-view-in`, `.mu-reveal`)
**สเปก/โทเคน:** `DESIGN.md §8` — อย่าคิดระยะเวลาใหม่เอง
| ทำอะไร | เรียกจากไหน |
|---|---|
| แถบโหลดบางบนสุดระหว่าง fetch partial | `router.js` → `Motion.loading(true/false)` |
| หน้าใหม่ค่อย ๆ โผล่ (fade + 10px) | `router.js` → `Motion.enter(viewEl)` หลัง inject |
| การ์ดโผล่ตอนเลื่อน | อัตโนมัติ: `scan()` ใน `#view` + `MutationObserver` (การ์ดจาก JSON ก็ได้) |
**กติกา**
- อนิเมตเฉพาะ `opacity` + `transform` · ห้าม width/height/top/left
- **ห้าม**ใส่ `.mu-reveal` ให้อิลิเมนต์ที่ครอบแผนที่ (`.at-map`, `.leaflet-container`, `.blog-mapx`) — ใส่ `data-no-reveal` ถ้าต้องการยกเว้นเอง
- ของที่เห็นบนจอตอนโหลดไม่ถูกอนิเมต · หลังจบจะลบ class ทิ้ง (hover lift เดิมไม่เพี้ยน)
- `prefers-reduced-motion: reduce` → ปิดทั้งหมด (ทั้ง JS และ CSS)
- เพิ่มหน้าใหม่: ไม่ต้องแก้อะไร (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)
ข้อมูลทั้งหมดเรนเดอร์โดย `ui/partials/stopDetail.init.js` จาก JSON — **ห้ามฝังข้อมูลป้ายลง HTML**
| ส่วนบนหน้า | มาจาก |
|---|---|
| ชื่อป้าย · ประเภท · รหัส · จังหวัด | `resource/data/stations.json` (`station_name_th`, `station_type`, `station_code`, `city_th`, `province_th`) |
| สายรถที่ผ่านป้ายนี้ + เวลารถ | `routes.json` (`station_ids`) × `schedules.json` (schema 2 ผ่านตัวอ่านกลาง `ui/partials/schedules.js`) |
| จำนวนสาย · เที่ยวต่อวัน · เวลาบริการ (เปิด–ปิด) · เที่ยวถัดไป | **คำนวณอัตโนมัติ** จากข้อมูลข้างบน (ไม่ต้องกรอก) |
| แผนที่ | `ui/map.js` (`ATMap.forStop`) วาดจาก `geojson-web/*.geojson` |
| รูปป้าย | หาเองจาก `busstop_list.json` (ป้ายใกล้สุดภายใน 3 กม. → `.image/stops/<หลัก กม.>.jpg`) หรือกำหนดเอง |
**ฟิลด์เสริม (ไม่ใส่ก็ได้ — ถ้าไม่ใส่ ส่วนนั้นจะซ่อนเอง) ใส่ใน `stations.json` ของป้ายนั้น:**
```json
{ "station_id": 1, "station_code": "at_main_terminal",
"photo": "../.image/stops/54950.jpg",
"description": "ข้อความแนะนำป้าย (แทนประโยคอัตโนมัติ)",
"facilities": ["ห้องน้ำ", "ที่พักคอย", "ร้านอาหาร"],
"landmarks": [ { "img": "../.image/landmarks/temple.png", "caption": "วัดสำคัญ", "sub": "เดิน 5 นาที" } ],
"landmarks_note": "คำโปรยใต้หัวข้อใกล้เคียงป้าย" }
```
URL ที่ใช้ได้: `#/stops/<station_code>` และ `#/stops/<station_code>?route=<รหัสสาย>` (กรองเฉพาะสายนั้น)
## ตารางเดินรถแยก "วันทำงาน / วันหยุด" (ดีไซน์ที่ไม่ต้องแก้โค้ดหน้าไหน)
**หลักคิด:** ใส่ตรรกะไว้ที่ตัวอ่านกลาง `ui/partials/schedules.js` ที่เดียว → หน้า check/busDetail/home/stopDetail
เรียก API เดิม (`Schedules.records/route/directions/times/countTrips`) แล้วได้ข้อมูลของ "วันนี้" ให้เอง
**เพิ่มฟิลด์ไม่บังคับ 2 ระดับ (ไม่ใส่ = พฤติกรรมเดิมทุกอย่าง):**
| ระดับ | ฟิลด์ | ความหมาย |
|---|---|---|
| ทิศทาง | `"service": "weekday" \| "holiday"` | ทั้งทิศทางใช้เฉพาะวันนั้น (ไม่ใส่/`"all"` = ทุกวัน) |
| จุดจอด | `"groups": [ { "label": "วันหยุด", "dayType": "holiday", "times": ["10:00"] } ]` | เวลาที่เพิ่มเฉพาะบางวัน — `times[]` ยังเป็นตารางพื้นฐานทุกวัน |
**การตรวจจับวัน:** เสาร์–อาทิตย์ = วันหยุด · นักขัตฤกษ์อ่านจาก `resource/data/holidays.json` (เจ้าของข้อมูลต้องกรอกเอง — **ห้ามเดา**)
**ความปลอดภัย:** ถ้ากรองแล้วไม่มีทิศเหลือ → ถอยไปใช้ทั้งหมด + ติดธง `fallback` (หน้าเว็บไม่มีทางว่างเปล่า) + เครื่องมือแก้ไขเตือนไว้
**GUI:** `resource/data/schedules-editor.html` มีช่อง "ใช้กับวัน" ต่อทิศ + ตรวจจับคำในหมายเหตุ (วันทำงาน/วันหยุด) แล้วเสนอให้ตั้งค่า
**หน้าเว็บ:** หน้า `#/check` จะขึ้น "ตารางวันทำงาน (จ–ศ)" / "ตารางวันหยุด" ต่อท้ายคำอธิบาย **เฉพาะสายที่มีการแยกตารางตามวัน**
## จุดกลางทาง "ไม่ต้องทำตาราง" — คำนวณจากต้นทาง (autoTimes)
**หลักคิด:** 1 ทิศ มีจุดที่กรอกเวลาจริง (ต้นทาง/จุดอ้างอิง) ส่วนจุดอื่นปล่อยว่างได้ → ระบบคำนวณให้จาก
`เวลา + (ผลต่าง กม. ÷ ความเร็ว)` แล้วทำเครื่องหมายว่าเป็น **ค่าประมาณ** (ไม่ใช่ตารางผู้ประกอบการ)
**ต้องมีอะไรบ้าง**
1. พิกัดของจุดนั้นใน `stations.json` (ถ้าเป็น 'จุดขึ้นรถประจำทางอื่นๆ' → ใช้พิกัดจาก `8 other_stop.json`)
2. ค่า `km` ของจุดใน `schedules.json` — วัดด้วย `python resource/tools/stop-km.py` (วัดตามเส้นจริงใน `geojson-web/`)
3. ตั้ง `"autoTimes": true` ที่ทิศนั้น (และ `"speedKmh": 40` ถ้าต้องการความเร็วอื่น) — **ตั้งได้จาก GUI ช่อง "คำนวณจากต้นทาง"**
**กติกาในท่อกลาง (`ui/partials/schedules.js`)**
- จุดที่มี `times[]` จริง → ใช้ของจริงเสมอ (ไม่คำนวณทับ)
- จุดที่ว่าง → หาจุดที่มีเวลาซึ่งอยู่ใกล้ที่สุด (ตาม กม.) แล้วบวก/ลบเวลาตามระยะ
- ไม่มี `km` หรือไม่มีจุดอ้างอิง → ถอยไปแสดง "ยังไม่มีข้อมูล" เหมือนเดิม (ไม่พัง)
- หน้าเว็บแสดงเวลาที่คำนวณด้วย **กรอบเส้นประ + ข้อความ "~ เวลาคำนวณจากต้นทาง (ประมาณ)"** เสมอ
**อย่าลืม:** ถ้าแก้พิกัด/เส้นทางใหม่ ให้รัน `stop-km.py` ซ้ำ (ค่า กม. จะเปลี่ยน)
## เครื่องมือแก้ schedules.json — กติกา UX (resource/data/schedules-editor.html)
1. **ตัวเลือกจุดจอด คัดจาก `station_order` ของสายนั้น** (ไม่ใช่สถานีทั้งจังหวัด)
- ถ้าเป็น `station_id 8` = "จุดขึ้นรถประจำทางอื่นๆ" → แสดง**ชื่อจุดจริงของสายนั้นจาก `8 other_stop.json`**
(รองรับรหัสเพี้ยนสลับหลัก เช่น `1101` = สาย `1011` แบบเดียวกับ `ui/partials/otherStop.js`)
- จุดที่อยู่นอก `station_order` ยังคงแสดงได้ (ไม่หาย) + บอกให้เห็นว่าอยู่นอกลำดับ
2. **"สร้างตารางเวลาอัตโนมัติ" เป็นการ์ดแยก** ต่อทิศ (ไม่อยู่ในหัวการ์ดทิศ)
- ขั้น 1 เลือก **จุดอ้างอิง** จาก dropdown ที่แสดงเฉพาะจุดในทิศนั้น**ที่มีตารางเวลาอยู่แล้ว** (พร้อมจำนวนเที่ยว) → เก็บเป็น `"baseSid"`
- ขั้น 2 ใส่ **เวลาเดินทางโดยประมาณ (นาที)** → เก็บเป็น `"travelMin"` (ระบบคำนวณความเร็วให้เอง)
- ขั้น 3 เลือก **จุดเป้าหมาย** จาก `station_order` ของสายนั้น (บอกสถานะ: มีตารางแล้ว / ว่างอยู่ / ยังไม่มีในทิศนี้ → จะเพิ่มจุดให้) → เก็บเป็น `"autoFor": [station_id]`
· ถ้าไม่เลือก = ทุกจุดที่ว่าง · ถ้าจุดเป้าหมายยังไม่มีเป็นจุดในทิศนั้น ระบบจะ **เพิ่มจุดให้อัตโนมัติ** ตอนกดใช้ตาราง
- ขั้น 4 กด **คำนวณตาราง** → พรีวิว (แถวเป้าหมายมี 🎯) → เลือก "ใช้ตารางนี้ (คำนวณอัตโนมัติ)" หรือ "เติมเวลาลงข้อมูลจริง"
· "เติมเวลาลงข้อมูลจริง" จะเติม **เฉพาะจุดเป้าหมาย** ถ้าเลือกไว้ (ไม่ทับจุดอื่น)
- ค่าที่พิมพ์ในแผงเป็นการชั่วคราว (ไม่แตะไฟล์จนกว่าจะกดปุ่ม) · เปิด/ปิดพรีวิวไม่ทำให้ไฟล์ "ยังไม่บันทึก"
3. **ค่าที่คำนวณไม่เคยถูกเขียนลง `schedules.json`** — `km` อยู่ใน `resource/data/stop-km.json` (generated)
4. ตัวอ่านกลาง `ui/partials/schedules.js` รองรับ `baseSid` (จุดอ้างอิง) → `baseEnd` → อัตโนมัติ ตามลำดับความสำคัญ
และ `autoFor` จำกัดว่าคำนวณเฉพาะจุดใด (ไม่ใส่ = ทุกจุดที่ว่าง)
## เครื่องยนต์ตรวจวัน (จันทร์–อาทิตย์) — อยู่ที่ท่อกลางที่เดียว
อยู่ที่ `ui/partials/schedules.js` เท่านั้น → หน้า check/busDetail/home/stopDetail ได้ผลเหมือนกัน **ไม่ต้องแก้โค้ดหน้าไหน**
**ลำดับการตัดสิน (แม่น → หลวม):**
1. `"days": ["sat","sun"]` ระบุตรง ๆ → ใช้ตามนั้น
2. `"service": "weekday" | "holiday" | "all"` → เทียบกับวันนี้
3. ไม่ระบุ → **ตรวจคำอัตโนมัติ** จาก `direction_label` + `direction_note`/`note` ของทุกจุดในทิศนั้น
(เจอ "วันหยุด/นักขัตฤกษ์/ส-อา/weekend" = วันหยุด · "วันทำงาน/จ-ศ/ธรรมดา/workday" = วันทำงาน **ไม่เดาถ้าเจอทั้งคู่**)
4. ตัดสินไม่ได้ → **แสดงทุกวัน** (ไม่ซ่อนข้อมูล) + ป้าย "ยังไม่ระบุวันของตาราง"
**วันหยุด = เสาร์–อาทิตย์ + นักขัตฤกษ์** จาก `resource/data/holidays.json` (เจ้าของข้อมูลกรอกเอง ห้ามเดา)
**API ที่เพิ่ม:** `Schedules.dayInfo(date)` → `{dayType, weekday, weekday_th, date}` · `Schedules.dayKey(date)` → `'mon'…'sun'`
· `Schedules.detectDay(text)` · `Schedules.detectDayOfDir(dir)` · `Schedules.serviceOf(dir|null, dir)` → `{day, from, matches, conflict?, unknown?}`
**การป้องกันข้อมูลหาย:** ถ้ากรองตามวันแล้วไม่มีทิศเหลือ → ถอยไปแสดงทั้งหมด + ติดธง `fallback`
## รูปภาพ — นามสกุลที่รองรับ (.jpg / .jpeg / .webp / .png)
**ทุกรูปในเว็บไล่ลองนามสกุลอัตโนมัติ** — ใส่ไฟล์นามสกุลไหนก็ได้ ไม่ต้องแก้โค้ด
| ลำดับ | นามสกุล |
|---|---|
| 1 | `.jpg` |
| 2 | `.jpeg` |
| 3 | `.webp` |
| 4 | `.png` |
**ที่ใช้:**
- รูปสถานี `.image/stations/<station_id>.<ext>` (รูปเสริม `<station_id>-2.<ext>`) — `PHOTO_EXTS` ใน `stopDetail.init.js`
- รูปป้ายริมทาง `.image/stops/<pad5 กม.>.<ext>` + รูปสถานีบนการ์ด `#/stops` — `IMG_EXTS` + `firstExisting()` ใน `busStop.init.js`
- รูปรถ `.image/routes/<รหัส>/car|boat.<ext>` · QR `.image/qrcode/<รหัส>.<ext>` — `CAR_EXTS`/`QR_EXTS` ใน `busDetail.init.js` (ทำมาก่อนแล้ว)
**กติกา:** เลือกนามสกุลแรกที่มีไฟล์จริง (ตรวจ HEAD ก่อนแสดง) · **ไม่มีไฟล์เลย → ไม่แสดงช่องว่าง** ในหน้าเว็บ (ไม่เหลือ `<img>` พาธลอย) · SW จัดการรูปทุกนามสกุลแบบ cache-first เหมือนกัน
**หมายเหตุ:** ถ้ามีทั้ง `.jpg` และ `.jpeg` ในชื่อเดียวกัน → **`.jpg` ชนะ** (รักษาพฤติกรรมเดิม)
## หัวแถวทิศในหน้า `#/check` — ใช้ `direction_label` ก่อน
การ์ดในหน้า check จัดกลุ่ม **ตามจุดจอด** (จุดเดียวกันที่มีหลายทิศ = การ์ดเดียว หลายแถว)
หัวแถวจึงต้องใช้ **`direction_label`** (ชื่อทิศ เช่น `ป่าโมกไปอ่างทอง` / `ป่าโมกไปอยุธยา`) ไม่ใช่คำกลางว่า "ทิศทาง"
ลำดับที่ใช้แสดง: `direction_label` → `direction_note` (พร้อมป้าย "ทิศทาง") → "ที่จุด X"
`records()` ส่งออกทั้ง `direction_label` และ `direction_note` — หน้าที่อื่นเรียกใช้ได้
## ชิปสาย (`buses-line`) ในหน้า `#/stops` → `#/routes/<รหัส>`
ชิป "สาย N" บนการ์ดป้าย **ลิงก์ไปหน้ารายละเอียดสาย** `#/routes/<รหัส>` (ไม่ใช่ `#/check`)
- สายที่ไม่มีใน `routes.json` → คงเป็น `<span>` (ไม่ทำลิงก์) กันลิงก์ตาย
- ข้อความปุ่ม: `stops.viewRoute` = "ดูรายละเอียดสาย {n}" / "View route {n}"
- (หน้า `#/stops/<slug>` ปุ่ม "ดูตารางเวลาสาย N" ยังใช้ `#/check/<รหัส>` ตามเดิม — คนละบริบท)
## สีของเลขสายตามหมวดเส้นทาง (`#/routes/<id>`)
เลขสายในหัวเรื่อง (`.mu-route-chip #route-chip`) เปลี่ยน**สีพื้นหลังตามหมวดเส้นทาง**
โดยอ่านจาก `routes.json → route_group` (นิยามหมวดอยู่ที่ `route_groups.json`)
| `route_group` | สี | คลาส | สายที่ใช้ตอนนี้ |
|---|---|---|---|
| `bangkok` | น้ำเงิน `#1f5fbf` | `.grp-bangkok` | 902, 15, 951, 952, 954, 8, 999 |
| `interprovincial` | ม่วง `#7a4cc0` | `.grp-interprovincial` | 101, 464, 641, 2194 |
| `in_province` | ชมพู `#d6388f` | `.grp-in_province` | 324, 1011, 2231 |
| `municipal` | เทา `#6b7268` | `.grp-municipal` | *(สำรอง — ยังไม่มีสายใช้)* |
| ไม่ระบุ | ม่วงแบรนด์ (ค่าเริ่มต้น) | — | — |
**วิธีทำงาน:** `busDetail.init.js` → `chipEl.className = 'mu-route-chip' + (route.route_group ? ' grp-' + route.route_group : '')`
→ กฎ CSS `.mu-route-chip.grp-<key>` อยู่ใน `busDetail.html`
**เพิ่มหมวดใหม่ (3 ขั้น):**
1. เพิ่มหมวดใน `resource/data/route_groups.json` (+ ใส่ `route_group` ให้สายใน `routes.json`)
2. เพิ่มโทเคนสีใน `DESIGN.md §3` และกฎใน `DESIGN.md §5` (หัวข้อ "เลขสายหน้า `#/routes/:id`")
3. เพิ่มกฎ `.mu-route-chip.grp-<key>` ใน `ui/partials/busDetail.html`
⚠️ ไม่แตะ CSS ของ chip หน้า `#/stops` (คนละบริบท ยังใช้ม่วงแบรนด์)
## ลิงก์ติดต่อผู้ประกอบการ (หน้ารายละเอียดสาย `#/routes/<id>`)
ใช้ฟิลด์ **`web_url`** ใน `routes.json` (มีอยู่เดิม) — ไม่ต้องแก้โค้ดเวลาเพิ่ม/เปลี่ยนลิงก์
- **`web_url` เก็บเป็นอาร์เรย์ `[ชนิดลิงก์, URL]`** เช่น `["facebook", "https://www.facebook.com/..."]`
→ อ่านด้วย `parseWebUrl()` ใน `busDetail.init.js` (รับสตริงเดี่ยวได้ด้วย เผื่อไฟล์เก่า)
→ **ใช้ `kind` ที่ระบุในไฟล์ก่อน** ถ้าไม่มีจึงเดาจาก URL · ⚠️ ห้ามใช้ `String(web_url)` ตรง ๆ (จะได้ `"line,https://..."` แล้วลิงก์เสีย)
- **ไอคอน + ชื่อ + สี เปลี่ยนตามชนิด URL อัตโนมัติ** (`linkKind()` ใน `busDetail.init.js`):
| ตรวจพบ | ไอคอน | โทนสี | ชื่อที่แสดง |
|---|---|---|---|
| `facebook.com` / `fb.me` | `ic-facebook` | `tone-sky` (ฟ้า) | Facebook |
| `line.me` / `lin.ee` / `linevoom` | `ic-message-circle` | `tone-green` | LINE Official |
| `http(s)://` อื่น ๆ | `ic-globe` | `tone-purple` | เว็บไซต์ |
- **ปุ่ม "เปิดลิงก์" แยกต่างหาก** (`route.openLink` + `route.link.*` ใน i18n) เปิดแท็บใหม่ `target="_blank" rel="noopener"` · โชว์ URL แบบสั้น (ตัด `https://`)
- **QR** ตั้งชื่อตามรหัสสาย: `.image/qrcode/<route_id>.<png|JPG|jpeg|webp>` (ไล่ลองนามสกุล) หรือระบุเองที่ `caption<id>.json → qr_image`
- **ไม่มี `web_url`** → แสดงเฉพาะแถว LINE+QR เหมือนเดิม (ไม่พัง)
## กฎ "จุดนี้ = เวลาจุดอ้างอิง ± n นาที" (`derive`) — แนวทาง A
**ปัญหาเดิม:** จุดระหว่างทางที่ไม่มีตารางของตัวเอง มักถูก "คัดลอกเวลา" จากจุดอื่นมา → เวลาผิด (เช่น 902 จุด 15
คัดลอกจากจุด 6 ทั้ง 25 เที่ยว ทั้งที่รถวิ่งต่ออีก 30 นาที)
**วิธีแก้:** เขียนกฎครั้งเดียวต่อจุด **ในไฟล์สายของตัวเอง** แล้วให้เว็บคำนวณเสมอ (ไม่เก็บเวลาซ้ำ)
```json
/* resource/data/scheduleslist/schedules902.json */
{ "station_id": 15,
"times": [],
"derive": { "from_station_id": 6, "offset_min": 30, "note": "รอรถที่ 7-11 หน้ากินซ่า" } }
```
- `from_station_id` อ้างจุดได้ **ข้ามทิศ** (ใน 902 จุด 6 อยู่ทิศ `all` แต่จุด 15 อยู่ทิศ `rungsit`) ✓
- `offset_min` เป็นบวก (หลังจุดอ้างอิง) หรือลบ (ก่อนหน้า) · เกินเที่ยงคืน = วนกลับแบบ mod 24
- **กฎชนะเวลาที่เขียนไว้** (`times`) — และเครื่องมือจะลบ `times` ที่ซ้ำให้อัตโนมัติ
**เว็บแสดงผลอัตโนมัติ:** ชิปเส้นประ + ตัวเอียง (`is-est`) + ข้อความ
`time.derived` = *"~ ตารางจากการคำนวณ (จาก {base} {n} นาที) — อาจเปลี่ยนแปลงตามการจราจรจริง"*
({base} = ชื่อจุดอ้างอิง ดึงจาก `stations.json` · ถ้ายังโหลดชื่อไม่ทันใช้ `#<id>` แทน)
**เครื่องมือ:** `resource/tools/derive-times.py` + ตาราง `resource/data/derive-times.csv`
```
route_id,station_id,from_station_id,offset_min,note
902,15,6,30,รอรถที่ 7-11 หน้ากินซ่า
```
- `--check` ดูก่อน · รันเปล่า = เขียนจริง · `--audit` = ตรวจว่าไฟล์ตรงตาราง + **ชี้จุดที่เวลาซ้ำแต่ยังไม่มีกฎ** ✓
- รันซ้ำได้ (idempotent) · จุดอ้างอิงต้องมีเวลาจริง · เขียนไฟล์คง CRLF เดิม
## บทความ (`#/blog`) — แผนที่ในบทความ 2 โหมด (`textN.json` → `map`)
**โหมด 1 · เส้นทางจริง** `"map": {"route_id":"101"}` → ใช้ `ATMap.route()` + geojson
- ขึ้นเฉพาะหน้าอ่าน · ไม่มีไฟล์ geojson → คงรูป + ป้าย `blog.noGeo`
**โหมด 2 · เส้นทางที่เสนอ ("ความฝัน")** `"map": {"origin":{…}, "routes":[…]}`
- เข้าโหมดนี้ทันทีเมื่อมี `routes` (อาร์เรย์) · ใช้ `ATMap.proposal(el, spec, onPick)` ใน `ui/map.js`
- วาดเส้นต้นทาง → ปลายทาง (เส้นประ สีตาม `line_color`) + หมุดสีเดียวกัน · **คลิกได้ทั้งเส้น หมุด และแถวรายการ**
- แผงรายละเอียดอยู่ใน blog (`buildProposal()` ใน `blog.init.js`) — map.js แค่เรียก `onPick(route)` กลับมา
- **`dest.lat/lng` ต้องเป็นตัวเลข** → ถ้า `null` ไม่วาด แต่ขึ้นในรายการพร้อมป้าย `blog.mapNoCoord`
- `distance_km`/`duration_min`/`fare_thb` = `null` → **ซ่อนในแผง** (ห้ามโชว์ 0 หรือเดาค่า)
- พิกัดต้นทาง: `station_code` → ค้นจาก `stations.json` หรือใส่ `lat`/`lng` ตรง ๆ
- ค่าทุกอย่างเป็น WGS84 · รายการ `routes[]` ใช้ `__layer` ที่ `proposal()` แนบไว้เพื่อไฮไลต์เส้นที่เลือก
**ร่วมทั้ง 2 โหมด**
- แผนที่ขึ้นเฉพาะหน้าอ่าน — การ์ดในรายการยังใช้รูป `picN.*` (ไม่โหลด Leaflet หลายใบ)
- รูปใน blog เติม `?v=` ผ่าน `ImgURL.of()` · เรียก `invalidateSize()` หลังวาด (กันแผนที่ 0×0)
- เอกสาร schema เต็ม: `ui/partials/blog-data/README.md`
## ระบบภาษา (i18n) — ไฟล์ต่อภาษา + fallback chain
**สถาปัตยกรรม (แนวทาง A2):** คำแปล **ไม่ได้อยู่ใน `i18n.js` แล้ว** — แยกเป็นไฟล์ต่อภาษา
| ส่วน | ที่อยู่ | หน้าที่ |
|---|---|---|
| ไฟล์คำแปล | `ui/locales/th.json` · `en.json` | แบน `"key": "ข้อความ"` (256 คีย์/ภาษา) |
| ตัวโหลด | `ui/i18n.js` | `SUPPORTED` · `BASE='th'` · cache ต่อภาษา · `t()` · `apply()` · `setLang()` · **`ready`** |
| จุดรอโหลด | `ui/router.js` ท้ายไฟล์ | `I18N.ready.then(render)` — รอคำแปลก่อนวาดหน้าแรก |
| precache | `ui/sw.js` | `./locales/th.json` + `./locales/en.json` (ออฟไลน์ใช้ได้) |
| เครื่องมือตรวจ | `resource/tools/check-i18n.py` | ดูหัวข้อท้าย |
**กติกาเหล็ก**
- เพิ่มคีย์ = ใส่ **ทุกไฟล์ภาษา** ในคำสั่งเดียว · คีย์ที่ขาดจะถอยไปใช้ `BASE` (คำไทยโผล่ในหน้า EN)
- **ห้ามคีย์ซ้ำในไฟล์เดียวกัน** — JSON เก็บตัวหลังเงียบ ๆ (เคยเกิดจริง: ค่าอังกฤษทับค่าไทย ทำให้โหมดไทยแสดงอังกฤษ)
- ข้อความใน HTML คือ **fallback** → ถ้าโหลดไฟล์ภาษาไม่ได้ `apply()` จะ **ไม่แตะ DOM** (ผู้ใช้เห็นข้อความเดิม ไม่เห็น key)
- `t()` คืน **key เดิม** เมื่อไม่พบทั้งภาษาปัจจุบันและ BASE (ใช้ตรวจว่าลืมแปล)
- ข้อความ JS ใช้ `I18N.t(...)` เท่านั้น · ข้อความล้วนใส่ `textContent` · ถ้าต้องมี HTML → `data-i18n-attr="html:key"`
- ชื่อเฉพาะ (สถานี/จังหวัด/สายรถ) **ไม่แปล**
- เพิ่มภาษาใหม่ 4 ขั้น: ไฟล์ `locales/<รหัส>.json` → `SUPPORTED` → PRECACHE ใน `sw.js` → รัน `check-i18n.py`
**ตรวจก่อน commit**
```
python resource/tools/check-i18n.py
```
ERROR = คีย์ขาด · คีย์ซ้ำ · ไฟล์ภาษาไม่ตรง `SUPPORTED` → exit 1 ห้าม commit
WARN = ค่าว่างเปล่า (อาจตั้งใจ) · คีย์ที่ไม่พบที่ใช้ (อาจใช้ไดนามิก)
## หัวโซน (`.mu-zone-head`) — ป้ายหัวข้อ + บรรทัดข้อมูลที่ตัดคำถูกต้อง
**ปัญหาเดิม:** `.mu-zone-head` เป็น `display:flex` **ไม่มี `flex-wrap`** แต่ลูก ๆ เป็น `flex-basis:100%`
→ ทุกบรรทัดถูกย่อรวมในแถวเดียว ข้อความไทยถูกตัดกลางคำ (แย่มากบนมือถือ)
**แก้แล้ว:**
| ส่วน | ที่อยู่ | ทำอะไร |
|---|---|---|
| โครง flex/grid | `ui/index.html` (§.mu-zone-head) | `flex-wrap: wrap` + `.mu-zone-head .mu-zone-desc { flex-basis:100%; min-width:0; line-height:1.65 }` |
| กฎจริง (ต้องชนะ partial) | `ui/responsive.css` (`#view …`) | `.mu-zone-meta` / `.mu-zone-seg` / ตัวคั่น `::after` · ≥768px เปลี่ยนเป็น grid 2 คอลัมน์ + `max-width:82ch` |
| สร้างชิ้น | `ui/partials/checkSchedule.init.js` → `setSegments(host, segs)` | รับ `"ข้อความ"` หรือ `{ html, icon }` · ข้อความล้วนใช้ `textContent` (กัน HTML หลุด) |
| HTML | `ui/partials/checkSchedule.html` | `#check-zone-desc` = `mu-zone-desc mu-zone-meta` · `#check-now-line` เพิ่ม `mu-zone-now` |
**กติกาสำคัญ**
- **ห้าม** สร้างบรรทัดข้อมูลด้วยสตริงเดียวที่ต่อ `' · '` เอง → ให้ส่ง array เข้า `setSegments()` เสมอ
- ตัวคั่น `·` **ห้าม** ใส่ในข้อความ — CSS `(.mu-zone-seg:not(:last-child)::after)` วาดให้ (ชิ้นสุดท้ายไม่มีจุด)
- ต้องการสไตล์ใหม่ → ใส่ที่ `responsive.css` **พร้อม prefix `#view`** (เพราะ `<style>` ของ partial ถูก inject ทีหลัง)
- เพิ่มหน้าใหม่ที่ใช้ `.mu-zone-head` ได้เลย — โครง flex/grid + ระยะห่างจัดการให้อัตโนมัติทั้งมือถือและจอคอม
**ตรวจ layout หลายความกว้าง:** ใช้ iframe จำลองความกว้าง (320/375/414/768/1024/1280) แล้ววัด
`getBoundingClientRect()` ของทุกชิ้น — เกณฑ์ผ่าน: `scrollWidth - clientWidth === 0` (ไม่มีล้นแนวนอน)
และไม่มีชิ้นไหนล้นขอบขวาของโซน
## ฟอนต์ (Typography)
| บทบาท | ฟอนต์ | ที่ใช้ |
|---|---|---|
| เนื้อหา + หัวเรื่อง | **K2D** (มีหัวแบบไทย) 300–800 | ทุกหน้า SPA + หน้าสถานี static |
| ตัวสำรอง | Prompt · Noto Sans Thai · Sarabun | ใน fallback chain ของ `font-family` |
| เวลา/เลขสาย/ตัวเลข | **IBM Plex Mono** + `tabular-nums` | `.mu-time-chip` · เลขสาย · รหัสป้าย |
- **K2D ฝังในโปรเจกต์**: `ui/vendor/fonts/` (`k2d.css` + `.woff2` 18 ไฟล์ · 6 น้ำหนัก × thai/latin/latin-ext)
→ ทุกหน้า link `k2d.css` (SPA = `./vendor/fonts/`, หน้าสถานี static = `../vendor/fonts/`)
→ **precache ใน `sw.js` ครบทุกไฟล์** = ออฟไลน์ได้จริง · เพิ่ม/เปลี่ยนฟอนต์ → แก้ `PRECACHE` + bump `VERSION`
- ตัวสำรอง (`Noto Sans Thai` · `Prompt` · `IBM Plex Mono`) ยังโหลดจาก Google Fonts CDN
- เปลี่ยนฟอนต์ = แก้ **DESIGN.md §4 ก่อน** แล้วค่อยแก้โค้ด (DESIGN.md เป็นรัฐธรรมนูญ)
- ห้ามใช้ฟอนต์แฟนซี/display เกินจำเป็น (DESIGN.md กฎข้อ 9) — ระบบเดียวทั้งเว็บ
## รูปเปลี่ยนแล้วไม่ขึ้น? — cache busting (แนวทาง B2)
**สาเหตุ:** SW ใช้ **cache-first กับรูป** → วางรูปทับชื่อเดิมแล้วเบราว์เซอร์ยังใช้ของเก่า
**วิธีแก้ (ใช้อยู่):** เติม **`?v=<เวอร์ชันแอป>`** ต่อท้าย URL รูปทุกตัว
- `ui/imageurl.js` → `ImgURL.of(url)` เติมให้ (ข้าม URL ภายนอก/data:; ไม่เติมซ้ำ)
- ใช้ใน: `busDetail.init.js` (รูปรถ/QR) · `busStop.init.js` (รูปสถานี/ป้าย) · `stopDetail.init.js` (รูปสถานี)
- รูป static ใน `ui/index.html` (โลโก้/ไอคอน 4 จุด) เติม `?v=` ตรง ๆ
- ค่ามาจาก `<meta name="app-version">` ซึ่ง**ต้องตรงกับ** `const VERSION` ใน `sw.js`
**ขั้นตอนหลังอัปรูป:**
```
python resource/tools/bump-version.py ← +1 รอบ (อัปเดต sw.js + meta + โลโก้ ให้ตรงกัน)
python resource/tools/bump-version.py --check ← ตรวจว่าทุกที่ตรงกัน
→ **ไม่ต้องให้ผู้ใช้กดอะไร**: `pwa.js` เทียบ `version.json` กับ `meta app-version` แล้วรีโหลดเอง
(ดู `ARCHITECTURE.md` §7) · ใช้ Ctrl+Shift+R เฉพาะตอนพัฒนาเครื่องตัวเอง
```
⚠️ รูปที่เพิ่ม "ชื่อใหม่" (ไม่ทับของเดิม) เห็นผลทันที ไม่ต้อง bump