Files
web-at-transit-mock/AGENTS.md
T
Bkk1234 656f65b41c แผนที่จาก GPKG + บทความ 6 ชิ้น + ลดความหนา footer
== แผนที่ / GIS ==
- qgis-to-web.py: อ่าน GPKG ได้ (--from gpkg) + เพิ่ม dream-Watcharapol
- เพิ่ม dream-*.geojson 6 ไฟล์ (เส้นทางที่เสนอ: บ้านภาชี · ชานเมืองอยุธยา · HSR · เมืองทองธานี · ปากเกร็ด · วัชรพล)
- map.js: ATMap.proposal() วาดเส้นจริงจาก geojson (ไม่ใช่เส้นตรง) · smoothFactor 0.5
  · coordOf() รับ coords=[lat,lng] · fitAll รับได้ทั้งจุดเดี่ยวและเส้น · setStyle บน featureGroup

== บทความ (blog) ==
- text3: ถ้าผมได้ออกแบบสายเดินรถเอง (จาก mydream.html) TH+EN
- text4: วิธีเดินทางไปสถานีรถไฟ และสนามบิน (จาก train-airplane.html) TH+EN
- text5/text6: โครงเปล่ารอเติมเนื้อหา (แสวงหา-โพธิ์ทอง · อำเภอเข้าเมือง)
- แผนที่ความฝัน: map.groups 3 กลุ่ม · คลิกเส้น/หมุด/แถวได้ · ป้ายที่มา
- ย่อหน้า: ระยะห่าง 20px + ย่อหน้าหน้าบรรทัด 1.5em

== ตารางเดินรถ ==
- เปลี่ยนชื่อคีย์ dir_* -> direction_* ทุกไฟล์ (backward-compat ในโค้ด)
- 1011: จุดย่อย 2 ทิศ + offsets [0,25,55]
- 954/2194: จุดย่อย station 8 + offsets
- refreshHighlights: วนข้ามวันเมื่อเลยเที่ยวสุดท้าย + ไฮเทลต์ชิปทุกจุด
- 8 other_stop.md: อัปเดตตรงข้อมูลจริง 8 รายการ

== i18n ==
- แยกไฟล์ต่อภาษา ui/locales/{th,en}.json + i18n.js = loader (ลด 28KB -> 6.5KB)
- resource/tools/check-i18n.py ตรวจคีย์ขาด/ซ้ำ
- ข้อความผู้สนับสนุนหน้าแรก + คำแปล EN

== UI ==
- ฝังฟอนต์ K2D (ui/vendor/fonts/) ออฟไลน์ 100%
- cache busting ?v=<SW VERSION> ทุกรูป (ui/imageurl.js)
- footer: ลดความหนา 468 -> 349px + line-height 1.5 กันสระ/วรรณยุกต์ซ้อน
- QR modal + ปุ่มคัดลอกลิงก์ · หน้าอัปเดตล่าสุดใน #/check
- credits: ขอขอบคุณภาพรถ 3 สาย

== เครื่องมือ ==
- bump-version.py · stamp-schedules.py · derive-times.py (จุดอ้างอิง ± นาที)
2026-10-05 03:55:09 +07:00

47 KiB
Raw Blame History

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 อย่าเดาโครงสร้าง


โครงสร้าง

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)

วิธีเปิดดูผลงาน

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 ของเว็บ — รันมือเมื่อข้อมูลเส้นเปลี่ยน):
    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)

หน้ารายละเอียดป้าย #/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 ของป้ายนั้น:

{ "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 นาที)

วิธีแก้: เขียนกฎครั้งเดียวต่อจุด ในไฟล์สายของตัวเอง แล้วให้เว็บคำนวณเสมอ (ไม่เก็บเวลาซ้ำ)

/* 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  ← ตรวจว่าทุกที่ตรงกัน
→ ให้ผู้ใช้กด Ctrl+Shift+R ครั้งเดียว = รูปทั้งหมดโหลดใหม่

⚠️ รูปที่เพิ่ม "ชื่อใหม่" (ไม่ทับของเดิม) เห็นผลทันที ไม่ต้อง bump