- 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
6.7 KiB
6.7 KiB
web-at-transit-mock
Static HTML mockup / ดีไซน์ต้นแบบเว็บข้อมูลการเดินรถ — สถานีขนส่งผู้โดยสารจังหวัดอ่างทอง (Atroute)
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 เนื้อหาบทความ/หน้าเกี่ยวกับ | งานเนื้อหา |
ระบบทำงานยังไง (ย่อ)
ui/index.htmlคือ shell เดียว — topbar/footer +<div id="view">ui/router.jsอ่านlocation.hash→fetch('partials/<view>.html')→ ฉีดเข้า#view→ รัน<script>ในไฟล์นั้น- แต่ละ view ดึงข้อมูลจาก
resource/data/*.jsonตรง ๆ (ไม่มี API) - ตรรกะร่วมอยู่ใน "ท่อกลาง":
partials/schedules.js(ตารางเดินรถ/วัน) ·partials/otherStop.js·ui/map.js(ATMap) ui/sw.jsprecache ทุกไฟล์ → เปิดซ้ำเร็ว/ออฟไลน์ได้ ·ui/pwa.js+version.jsonอัปเดตเองโดยผู้ใช้ไม่ต้องกดอะไร- สถิติ (
ui/analytics.js) เก็บในเครื่องแบบไม่ระบุตัวตน — ดูที่#/stats
รายละเอียดทั้งหมด (diagram, API ของแต่ละ engine, checklist ทดสอบ) → ARCHITECTURE.md
โครงสร้าง
web-at-transit-mock/
├── maintheme.png ← ภาพธีม/ดีไซน์ต้นแบบ
├── Makefile ← คำสั่งรวม (make setup / pack / serve)
├── ui/ ← Single-page app (hash router)
│ ├── index.html shell หน้าเดียว
│ ├── router.js / i18n.js / pwa.js / sw.js
│ ├── _shared.css / responsive.css
│ └── partials/ view ละ 1 ไฟล์ (router fetch + inject)
├── resource/
│ ├── data/ ← ข้อมูล mock: routes.json, schedules.json, stations.json, ...
│ └── images.zip ← ★ รูปทั้งหมด (บีบไว้ — แตกด้วย make setup)
└── .image/ ← รูปทั้งหมด (hidden — เกิดหลัง make setup, ไม่ commit)
วิธี run
cd web-at-transit-mock
make setup # 1. แตก resource/images.zip → .image/ (ครั้งเดียว)
make serve # 2. รัน static server (Ctrl+C เพื่อหยุด)
แล้วเปิดเบราว์เซอร์ที่:
http://localhost:8090/ui/index.html
ดูคำสั่งทั้งหมด: make help
เงื่อนไขสำคัญ
- ต้องรัน
make setupก่อน — ไม่งั้นรูปพังทั้งหน้า (relative path../.image/...หาไฟล์ไม่เจอ) - ต้อง serve จาก root ของ repo (ไม่ใช่จาก
ui/) — รูปและข้อมูลอ้างอิงด้วย relative path - ห้ามเปิด
file://— fetch JSON + relative path จะใช้ไม่ได้ ต้องผ่าน static server เสมอ - เปลี่ยน port ได้ด้วย
make serve PORT=8080
งานที่ต้องรันก่อน commit / ปล่อยเวอร์ชัน
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)
โดยแจกผ่านไฟล์เดียว resource/images.zip:
-
แตกไฟล์ (ครั้งแรกหลัง clone):
make setup -
เพิ่ม/เปลี่ยนรูป: แก้ไฟล์ใน
.image/แล้ว re-zip:make packแล้ว commit
resource/images.zip -
ห้าม commit ไฟล์ใน
.image/— อยู่ใน.gitignoreแล้ว
หมายเหตุ (ไม่ต้องแก้)
ui/index.htmlอ้าง../../frontend-web-transit/web-transit/css/main-theme.css— ไฟล์นี้ไม่อยู่ใน repo (ดู AGENTS.md ข้อ 12) จะขึ้น 404 ใน DevTools แต่ไม่กระทบ การแสดงผล เพราะสไตล์จริงอยู่ที่_shared.css- Google Fonts (
fonts.googleapis.com) ต้องต่อเน็ต — ถ้า offline ฟอนต์จะ fallback เป็น system font แต่หน้าไม่พัง - รายละเอียดกฎการแก้โค้ดฉบับเต็ม ดูใน
AGENTS.mdและDESIGN.md