Files
web-at-transit/docs/UI-PORT.md
T
itmeadmin 138a3d15d8 พอร์ต UI จาก web-at-transit-mock เข้า Next.js + data sync เข้า Postgres/SeaweedFS
- 8 หน้า (home/stops/routes/stop/check/blog/about/credits) แปลง partials → React component ตรง mock
- ตรรกะพอร์ตเป็น src/lib/ui/*.ts (mount()) + runtime/PageRuntime
- CSS: base + pages/*.css import ต่อ route (คงลำดับ cascade ของ mock)
- asset/content: public/{image,resource/data,content,locales,vendor}
- แก้ path รูปไทล์พาร์ทเนอร์ (.image → /image) + fallback absolute
- ลบ UI เดิมที่ไม่ตรง mock (expanded/stops details/old components/globals.css)
- script/sync_data_to_postgres.mjs + sync_images_to_storage.mjs (dry-run/--apply, backup)
- docs/UI-PORT.md + DESIGN.md + README
2026-10-23 15:50:00 +07:00

91 lines
6.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# UI port — web-at-transit-mock → web-at-transit (Next.js)
Frontend ของ repo นี้เป็น **พอร์ต 1:1 จาก mock** (`D:\Git\workspace\web-at-transit-mock`)
มาร์กอัป/CSS/ข้อความ/ตรรกะ ต้องตรงกับ mock — mock คือแหล่งความจริงของดีไซน์
อ่าน `DESIGN.md` ก่อนแก้ UI ทุกครั้ง
## โครงสร้าง frontend
```
frontend/
├─ src/app/ route จริง (mock เดิมใช้ hash router)
│ ├─ page.tsx / หน้าแรก
│ ├─ stops/page.tsx /stops ป้ายหยุดรถ + ค้นหา
│ ├─ stops/[code]/page.tsx /stops/:code รายละเอียดป้าย
│ ├─ routes/page.tsx /routes รายละเอียดสาย
│ ├─ routes/[routeId]/page.tsx /routes/:id
│ ├─ check/{,[routeId]}/ /check, /check/:id
│ ├─ blog/{,[postId]}/ /blog, /blog/:postId
│ ├─ about/page.tsx /about
│ ├─ credits/page.tsx /credits
│ └─ files/[...path]/route.ts proxy → backend /files (SeaweedFS)
├─ src/components/
│ ├─ views/*.tsx มาร์กอัปแต่ละหน้า (แปลงจาก partials ของ mock)
│ ├─ SiteHeader.tsx topbar + nav (แทน index.html)
│ ├─ SiteFooter.tsx footer + สายยอดนิยม + ตัวเลขผู้เข้าชม
│ ├─ IconSprite.tsx SVG symbols (#ic-*)
│ ├─ PageRuntime.tsx เรียก mount() ของหน้า หลัง runtime พร้อม
│ └─ SiteBoot.tsx โหลด shared libs + apply i18n ทุกหน้า
├─ src/lib/
│ ├─ runtime.ts boot shared libs, mountPage(), route context
│ └─ ui/*.ts ตรรกะที่พอร์ตจาก ui/*.js (แก้เฉพาะ path + mount())
├─ src/styles/
│ ├─ _shared.css · map.css · shell.css · responsive.css
│ └─ pages/*.css CSS ของ partial แต่ละหน้า
└─ public/
├─ image/ ← .image ของ mock
├─ resource/data/ ← resource/data ของ mock (JSON + geojson + scheduleslist)
├─ content/{blog,about}-data/ เนื้อหาบทความ
├─ locales/{th,en}.json คำแปล (I18N)
└─ vendor/{fonts,leaflet} K2D ฝังในโปรเจกต์ + Leaflet
```
## กฎที่ต้องถือ (บทเรียนจากการพอร์ต)
1. **CSS ของแต่ละหน้า import ใน view ของหน้านั้น** (`src/components/views/*.tsx`)
- ห้าม import รวมใน `layout.tsx`: CSS ทุกหน้าจะทับกัน (เช่น `.mu-toolbar` ของ
route.css ทับ stops.css) — เกิดแล้วระหว่างพอร์ต
- ห้ามครอบ `@layer` และห้ามเติม `#view` นำหน้า selector เพื่อจัดลำดับ:
ทั้งสองวิธีเปลี่ยน specificity ทำให้ rule ที่ mock ตั้งใจให้ responsive ชนะ กลับแพ้
(เช่น `.mu-stop-grid` กลายเป็น 2 คอลัมน์แทน 3)
- ที่ถูกคือ: import ต่อ route → Next แยก CSS chunk ต่อหน้า และโหลด base chunk ก่อน
= ลำดับเดียวกับ mock ที่ inject `<style>` ของ partial หลัง `<link responsive.css>`
2. **ตรรกะหน้าอยู่ใน `src/lib/ui/*.ts`** พอร์ตจาก mock ตรง ๆ (`@ts-nocheck`)
แต่ละไฟล์ส่งออก `export default function mount()` เรียกผ่าน `PageRuntime`
ด้วย `page="home" | "stops" | "route" | "stop" | "check" | "blog" | "about"`
(ส่ง string จาก server component — ห้ามส่งฟังก์ชัน)
3. **path asset** ในไฟล์ UI: `/image/…`, `/resource/data/…`, `/content/blog-data/…`,
`/locales/…` — ห้ามใช้ `../.image/…` แบบ mock
4. **ลิงก์ภายในเป็น path จริง** (`/stops`) ไม่ใช่ `#/stops`
5. **ห้าม emoji** ใช้ SVG sprite `<use href="#ic-…">` และฟอนต์ K2D เท่านั้น
6. **i18n**: ข้อความในมาร์กอัปใช้ `data-i18n="key"` + `public/locales/*.json`
ปุ่มสลับภาษา `[data-i18n-switch]` → reload หน้า (เท่ากับ mock ที่ re-render partial)
## ข้อมูลและไฟล์
- UI อ่านชุดข้อมูลเดียวกับ mock: `public/resource/data/*.json`
(routes, stations, busstop_list, schedules + `scheduleslist/`, `geojson-web/`,
holidays, stop-km, captions)
- เนื้อหา blog/about: `public/content/*/text<N>.json` + `pic<N>.jpg`
- รูป: `public/image/**` (คัดลอกจาก `.image/` ของ mock)
- ไฟล์อัปโหลดของผู้ใช้ → backend → SeaweedFS (`STORAGE_URL=http://seaweed-filer:8888`)
แล้วอ่านผ่าน `/files/...`
- **ยังไม่มี Postgres migration/seed ใน repo** — ถ้าจะย้าย JSON เข้า DB ต้องเพิ่ม
schema + seed ก่อน แล้วแก้ `src/lib/ui/*` ให้ยิง `/api/*` แทนไฟล์ JSON
(`script/import_assets_to_storage.py` อัปโหลดรูปเข้า SeaweedFS ผ่าน API ได้แล้ว)
## ตรวจก่อนส่งงาน
```bash
cd frontend
npx tsc --noEmit
npm run build # ต้องผ่าน (static 9 หน้า)
npm run dev # http://localhost:3000
```
- เปิดทุก route: `/`, `/stops`, `/stops/:code`, `/routes`, `/routes/:id`, `/check`,
`/check/:id`, `/blog`, `/blog/:id`, `/about`, `/credits`
- เทียบภาพกับ mock ที่ viewport เดียวกัน (1280×900) — diff ที่วัดได้ 0.7–2.3%
(ที่เหลือมาจาก marquee animation / ตัวเลขผู้เข้าชม)
- ตรวจว่าไม่มี horizontal scroll และปุ่ม/ลิงก์กดได้จริง