Files
web-at-transit-mock/README.md
T
Bkk1234 246b864c06 docs: add ARCHITECTURE.md and refresh README/AGENTS indexes
- 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
2026-11-04 00:19:24 +07:00

101 lines
6.7 KiB
Markdown

# 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 เนื้อหาบทความ/หน้าเกี่ยวกับ | งานเนื้อหา |
## ระบบทำงานยังไง (ย่อ)
1. `ui/index.html` คือ shell เดียว — topbar/footer + `<div id="view">`
2. `ui/router.js` อ่าน `location.hash` → `fetch('partials/<view>.html')` → ฉีดเข้า `#view` → รัน `<script>` ในไฟล์นั้น
3. แต่ละ view ดึงข้อมูลจาก `resource/data/*.json` ตรง ๆ (ไม่มี API)
4. ตรรกะร่วมอยู่ใน "ท่อกลาง": `partials/schedules.js` (ตารางเดินรถ/วัน) · `partials/otherStop.js` · `ui/map.js` (ATMap)
5. `ui/sw.js` precache ทุกไฟล์ → เปิดซ้ำเร็ว/ออฟไลน์ได้ · `ui/pwa.js` + `version.json` อัปเดตเองโดยผู้ใช้ไม่ต้องกดอะไร
6. สถิติ (`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
```bash
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`
### เงื่อนไขสำคัญ
1. **ต้องรัน `make setup` ก่อน** — ไม่งั้นรูปพังทั้งหน้า (relative path `../.image/...` หาไฟล์ไม่เจอ)
2. **ต้อง serve จาก root ของ repo** (ไม่ใช่จาก `ui/`) — รูปและข้อมูลอ้างอิงด้วย relative path
3. **ห้ามเปิด `file://`** — fetch JSON + relative path จะใช้ไม่ได้ ต้องผ่าน static server เสมอ
4. เปลี่ยน port ได้ด้วย `make serve PORT=8080`
## งานที่ต้องรันก่อน commit / ปล่อยเวอร์ชัน
```bash
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:
```bash
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`