Files
web-at-transit-mock/AGENTS.md
T
phattaranun.a 82aafdc61f Rename hidden image folder .resource/ to .image/
.resource/ clashed with resource/ (the tracked data folder), so rename the
hidden image folder to .image/ for clarity. Re-zip resource/images.zip to
contain .image/ and update setup.sh, .gitignore, README.md, AGENTS.md and
all image references in ui/.
2026-09-12 12:40:29 +07:00

11 KiB

AGENTS.md — คำสั่งสำหรับ AI coding agent

โปรเจกต์: web-at-transit-mock — mockup/ดีไซน์ HTML ต้นแบบของเว็บข้อมูลการเดินรถ สถานีขนส่งผู้โดยสารจังหวัดอ่างทอง (AT Transit)

หมายเหตุ: 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)
    • ชื่อเฉพาะ (ชื่อสถานี/จังหวัด/สายรถ) ไม่ต้องแปล — คงภาษาไทย

ลำดับการอ่านไฟล์เมื่อเริ่มงาน

  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)