.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/.
112 lines
11 KiB
Markdown
112 lines
11 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.zip ← รูปทั้งหมดบีบรวม (แตกด้วย setup.sh)
|
|
└── .image/ ← รูปทั้งหมด (hidden — เกิดหลังรัน setup.sh, ไม่ commit)
|
|
```
|
|
|
|
**ทุกหน้าเป็น 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. **รูปอ้างอิงผ่าน `../.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)
|