- frontend/src/lib/ui/motion.ts + components/MotionBoot.tsx: page-enter and scroll reveal per pathname change (ported from mock motion.js); IntersectionObserver plus sweep fallback for jump-scroll/hidden tabs, maps never transformed - frontend/src/lib/ui/analytics.ts: cookie-less local-first search analytics (localStorage at_stats_v1, DNT/GPC + opt-out, term sanitiser, 900ms debounce, caps 300 terms / 200 views / 120 days); optional Umami endpoint via AT_ANALYTICS - /stats page (StatsView + styles/pages/stats.css): KPIs, 14-day chart, top terms, top route/stop pages, no-result terms, JSON export, clear, opt-out - hooks: stops search apply(), stop detail route filter - remove footer visitor counter (lib/ui/visitors.ts, .mu-visitor/.mu-vreset, i18n keys) - remove floating install-app button; PwaBoot keeps SW + guarded version toast (sessionStorage guard, silent reload when tab hidden) - i18n th/en: nav.stats, update.applying, stats.* (public + src/data locales) - version.json + sw VERSION -> 2026.10.24.3; docs/UI-PORT.md section for this round
105 lines
9.3 KiB
Markdown
105 lines
9.3 KiB
Markdown
# 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`, `/stats`
|
||
- เทียบภาพกับ mock ที่ viewport เดียวกัน (1280×900) — diff ที่วัดได้ 0.7–2.3%
|
||
(ที่เหลือมาจาก marquee animation / ตัวเลขผู้เข้าชม)
|
||
- ตรวจว่าไม่มี horizontal scroll และปุ่ม/ลิงก์กดได้จริง
|
||
|
||
## รอบล่าสุด — motion, สถิติ, auto-update (พอร์ตจาก mock)
|
||
|
||
| ของใน mock | ใน repo นี้ | หมายเหตุ |
|
||
|---|---|---|
|
||
| `ui/motion.js` (enter · reveal · loading bar) | `src/lib/ui/motion.ts` + `components/MotionBoot.tsx` + CSS ใน `src/styles/_shared.css` | MotionBoot เรียก `Motion.enter(#view)` ทุกครั้งที่ pathname เปลี่ยน (แทน router เดิม) · reveal ใช้ `IntersectionObserver` + sweep (กันค้างตอนกระโดดข้ามหน้า/แท็บถูกซ่อน) |
|
||
| `ui/analytics.js` + `#/stats` | `src/lib/ui/analytics.ts` + `app/stats/page.tsx` + `components/views/StatsView.tsx` + `styles/pages/stats.css` | เก็บใน localStorage `at_stats_v1` · ไม่มีคุกกี้/IP/UA · `cleanTerm()` ตัดอีเมล/เบอร์/เลขยาว · debounce 900ms · opt-out + DNT/GPC · ค่าเริ่มต้นไม่ส่งออกเน็ต (จะส่งก็ต่อเมื่อตั้ง `window.AT_ANALYTICS = {endpoint, siteId}`) |
|
||
| ปุ่มติดตั้งแอปลอยมุมขวาล่าง | **เอาออก** — `PwaBoot` เหลือ SW + version check | Chrome/Edge ยังมีไอคอนติดตั้งของเบราว์เซอร์เอง |
|
||
| ตัวเลขผู้เข้าชม 12,834 ใน footer | **เอาออก** — ลบ `lib/ui/visitors.ts` + CSS `.mu-visitor/.mu-vreset` + คีย์ `visitors.*` | backend มี `/api/visits` (record_visit/visits_summary) แต่ frontend ยังไม่เรียก — ถ้าจะทำสถิติรวมศูนย์ ให้ต่อที่ `lib/api.ts` |
|
||
| bump + `version.json` + toast อัปเดต | `PwaBoot` เทียบ `/version.json` กับ `<html data-app-version>` (อ่านตอน build) → toast + reload ครั้งเดียว/เวอร์ชัน | ต้อง bump `public/version.json` + `public/sw.js` VERSION แล้ว rebuild |
|
||
|
||
**ยังไม่พอร์ต (ตั้งใจ):** หน้ารวมศูนย์สถิติจาก backend — backend มีตาราง `visit_daily_stats`
|
||
และ API `/visits/summary` แล้ว แต่ยังไม่มี UI/การเรียก; ถ้าจะทำต้องตัดสินใจเรื่อง visitor id
|
||
เชิงความเป็นส่วนตัวก่อน (mock ใช้ local-only เพื่อไม่ต้องมี id ถาวร)
|