Files
web-at-transit-mock/AGENTS.md
T
Bkk1234 c44f79b7d9 Rebuild mock as hash-routed SPA with i18n and PWA refresh
- Single-page shell (ui/index.html) + vanilla hash router; each screen is a partial
- New #/check schedule view (all stop times open, no collapse) wired to the
  'check schedules' CTA; contact-operator box, route map and gallery trimmed from it
- Mobile-first responsive.css (375px iPhone 8 up to 27-inch/1440p)
- TH/EN i18n system (data-i18n, browser-language detect, topbar switcher)
- Shared form controls moved to _shared.css (mu-btn, custom select chevron,
  focus-visible ring); footer contact column now mailto:[email protected]
- SW v9: JS network-first, precache i18n.js + all partials
- Legacy pages become redirect stubs to index.html#/...
2026-09-03 00:08:04 +07:00

111 lines
10 KiB
Markdown

# 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/ รูปทั้งหมด (routes/, partners/, landmarks/, qrcode/, icons/)
```
**ทุกหน้าเป็น 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. **รูปอ้างอิงผ่าน `../resource/images/...`** — อย่า 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): `resource/images/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 ใน `resource/images/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)