11 KiB
11 KiB
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 จะพัง)
กฎบังคับ
- ห้ามใส่ framework/build step — repo นี้เป็น static HTML + vanilla JS เท่านั้น
- ทุกหน้าเป็น SPA view ผ่าน hash router — ห้ามสร้างไฟล์ HTML หน้าใหม่
ถ้าจะเพิ่มหน้าจอใหม่: สร้าง
partials/<view>.html(+<script>/<style>ในไฟล์นั้น) แล้วเพิ่ม route ในui/router.js(VIEWS + parseHash) - ลิงก์ภายในใช้
href="#/..."เสมอ — ห้ามhref="./xxx.html"(จะโหลดหน้าใหม่) และห้ามlocation.href/location.replaceไปหน้า html ยกเว้นใน redirect stub <style>และ<script>ของ view ให้อยู่ใน partial ของมัน — router inject แล้ว รัน<script>ให้อัตโนมัติ ถ้า script ต้องอ่าน params ให้ใช้window.__route- ทุกหน้าโหลด
_shared.css— สไตล์ร่วมต้องอยู่ที่นี่ ไม่ใช่ inline ในแต่ละหน้า (ยกเว้นสไตล์เฉพาะหน้าที่จำเป็นจริง ๆ ให้อยู่ใน<style>ใน partial) - class ที่ขึ้นต้น
mu-= component ร่วม (เช่น.mu-card,.mu-cover,.mu-hero) — ถ้าจะเพิ่ม component ใหม่ ใช้ prefixmu-ด้วย - รูปอ้างอิงผ่าน
../.image/...— อย่า copy รูปเข้า ui/ - ข้อมูลตัวอย่างมาจาก
resource/data/*.json— ถ้าจะเพิ่มเส้นทาง/ป้าย ต้องเพิ่มข้อมูล ใน JSON ให้ตรงกัน (ไม่ hardcode เฉพาะหน้า) - ข้อความ UI เป็นภาษาไทย — ภาษาอังกฤษใช้เป็น label รองเท่านั้น
- อ่าน
DESIGN.mdก่อนแก้ UI ทุกครั้ง — มีกฎ "ห้ามทำ" ที่กันสไตล์ AI genric และโทเคนสี/ฟอนต์ตายตัว - ไอคอนใช้ระบบ 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
- ไอคอนต้นฉบับ (MIT):
main-theme.css(อ้างอิงจาก HTML) ไม่อยู่ใน repo นี้ — ถ้าแก้สไตล์ให้แก้ที่_shared.cssแทน อย่าไปสร้าง main-theme.css ใหม่- PWA / Service Worker (ui/sw.js) — ห้ามแก้กลไกโดยไม่เข้าใจ:
- HTML/CSS/JS/partials/JSON → network-first (ออนไลน์ได้ของใหม่เสมอ, ออฟไลน์ใช้ cache)
- รูป/ฟอนต์ → cache-first
- เนื้อหา HTML/CSS/JS เปลี่ยน = เห็นผลทันทีโดยผู้ใช้ไม่ต้องล้างแคช (network-first)
- เฉพาะแก้
sw.jsเองเท่านั้น ต้อง bumpVERSIONใน sw.js (เช่น2026.09.02.9) → cache ใหม่ถูกสร้าง + cache เก่าถูกลบอัตโนมัติตอน activate - อย่าลืม: ทุกหน้า HTML ต้องมี
<link rel="manifest">+<script src="./pwa.js">(ถ้าสร้างหน้าใหม่) และถ้าเพิ่มไฟล์ shell (หน้า/partial/CSS/JS หลัก) ให้เพิ่มในPRECACHE
- หลายภาษา (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 หน้าใหม่ให้อัตโนมัติ (ฟัง eventlangchange) - ชื่อเฉพาะ (ชื่อสถานี/จังหวัด/สายรถ) ไม่ต้องแปล — คงภาษาไทย
- ข้อความ UI ห้าม hardcode ภาษาเดียว — ใช้
ลำดับการอ่านไฟล์เมื่อเริ่มงาน
AGENTS.md(ไฟล์นี้) →DESIGN.md(ถ้าแตะ UI)- หน้าที่เกี่ยวข้อง (
ui/*.html) +_shared.css+maintheme.png(ถ้าต้องการอารมณ์ดีไซน์) resource/data/*.jsonที่เกี่ยวข้อง (ถ้าแตะข้อมูล)
หมายเหตุ
- commit ล่าสุดเน้น: sponsor marquee (เลื่อนสปอนเซอร์), ลบไฟล์ backup HTML
.gitignoreว่างเปล่า — ถ้าเพิ่มไฟล์ขยะ (เช่น .DS_Store) ให้เพิ่มใน .gitignore- งานถัดไปที่คาดว่าเกี่ยวข้อง: นำดีไซน์นี้ไป implement ใน
web-at-transit(Next.js)