Files
Bkk1234 4b5a4d33d3 sync from mock: motion, privacy-first search stats, auto-update UX
- 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
2026-11-04 00:53:37 +07:00

105 lines
9.3 KiB
Markdown
Raw Permalink 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`, `/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 ถาวร)