Files
web-at-transit/docs/UI-PORT.md
T
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

9.3 KiB
Raw Blame History

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 ได้แล้ว)

ตรวจก่อนส่งงาน

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 ถาวร)