From 246b864c068b70101c365356577bbc7a66598a30 Mon Sep 17 00:00:00 2001 From: Bkk1234 Date: Wed, 4 Nov 2026 00:19:24 +0700 Subject: [PATCH] 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 --- AGENTS.md | 45 ++++++- ARCHITECTURE.md | 337 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 30 +++++ 3 files changed, 411 insertions(+), 1 deletion(-) create mode 100644 ARCHITECTURE.md diff --git a/AGENTS.md b/AGENTS.md index d7481f6..5ae7a4d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,6 +9,19 @@ อ่านไฟล์นี้ก่อนทำงานเสมอ เพื่อประหยัด token อย่าเดาโครงสร้าง +## แผนที่เอกสาร (อ่านตามงาน) + +| งาน | เอกสาร | +|---|---| +| เข้าใจระบบทั้งหมด (boot, routing, data layer, engines, cache, analytics, recipes) | **`ARCHITECTURE.md`** ← ละเอียดที่สุด | +| กฎการแก้โค้ด / ห้ามทำอะไร | ไฟล์นี้ (`AGENTS.md`) | +| สี ฟอนต์ ระยะ กฎดีไซน์ | `DESIGN.md` (รัฐธรรมนูญ — แก้ก่อนเขียนโค้ด) | +| ข้อมูลเส้นทางจาก QGIS | `resource/data/QGIS Project/GeoJSON-2/README.md` | +| schema บทความ / หน้าเกี่ยวกับ | `ui/partials/blog-data/README.md` · `about-data/README.md` | +| ภาพรวมโปรเจกต์ + วิธีรัน | `README.md` | + +> ถ้าเอกสารขัดกัน: `DESIGN.md` ชนะเรื่องหน้าตา · `AGENTS.md` ชนะเรื่องวิธีแก้โค้ด · `ARCHITECTURE.md` ชนะเรื่อง "ระบบทำงานยังไง" (ต้องอัปเดตให้ตรงโค้ดเสมอ) + --- ## โครงสร้าง @@ -149,6 +162,35 @@ python -m http.server 8090 # เปิด http://localhost:8090/ui/index. - เพิ่มหน้าใหม่: ไม่ต้องแก้อะไร (router + observer จัดการ) — เพียงใช้คลาสการ์ดเดิม (`mu-card`, `mu-stop-card`, `mu-zone`, `mu-summary`, `mu-stat`, …) - อย่าลืม `./motion.js` ใน `PRECACHE` ของ `sw.js` (มีแล้ว) และ bump `VERSION` เมื่อแก้ SW +## สถิติ (ui/analytics.js + หน้า #/stats) — privacy-first แบบ Umami + +**แนวคิด:** อิง Umami (MIT) — ไม่มีคุกกี้/ไม่มี fingerprint/ไม่เก็บ IP-UA แต่ repo นี้ไม่มี backend +จึงเก็บรวมในเครื่อง (localStorage) เป็นค่าเริ่มต้น และ **ไม่ส่งออกเน็ตเลย** + +| เก็บ | ไม่เก็บ | +|---|---| +| จำนวนเปิดหน้า/วัน · คำค้น (ทำให้ปลอดภัยแล้ว) + จำนวน + เวลาล่าสุด · คำที่ค้นไม่พบ · views ของ route/stop | IP · UA · พิกัด · คุกกี้ · รหัสเครื่อง · ประวัติข้ามเว็บ · ไม่มีรหัสผู้ใช้ถาวร | + +**กติกา** +1. คำค้นต้องผ่าน `cleanTerm()` เสมอ (ตัดอีเมล · @handle · เลขยาว ≥5 หลัก · cap 60 ตัวอักษร · คำ <2 ตัวไม่เก็บ) +2. `Analytics.search()` **debounce 900ms ในตัว** — เรียกได้ทุกครั้งที่ผลค้นเปลี่ยน ไม่ต้อง debounce เอง +3. เคารพ `Do Not Track` + `Global Privacy Control` + สวิตช์ในหน้า `#/stats` (`at_stats_optout`) +4. **ห้ามเพิ่มคุกกี้/สคริปต์ภายนอก** — ถ้าต้องการเซิร์ฟเวอร์ให้ตั้ง `window.AT_ANALYTICS = {endpoint, siteId}` + ชี้ Umami ของตัวเอง (payload ตรงสเปก `/api/send`) อย่าเขียน endpoint ใหม่ +5. เพดานกัน localStorage บวม: 300 คำ · 200 หน้า · 120 วัน · หน้าใหม่เรียกแค่ `search()` / `view()` (pageview ผูก hashchange แล้ว) + +## อัปเดตเวอร์ชัน — ผู้ใช้ไม่ต้องกด Ctrl+Shift+R (ทั้งคอมและมือถือ) + +``` +python resource/tools/bump-version.py # คำสั่งเดียวจบ +python resource/tools/bump-version.py --check # ต้อง ✓ ทุกบรรทัด +``` + +คำสั่งเดียวอัปเดตครบ: `sw.js VERSION` · `meta app-version` · โลโก้ `?v=` · **shell js/css `?v=`** · **`ui/version.json`** +`ui/pwa.js` ตรวจ `version.json` (เปิดหน้า · ทุก 5 นาที · กลับมาที่แท็บ · เน็ตกลับมา) แล้วขึ้น toast + รีโหลดเอง +(รีโหลดครั้งเดียวต่อเวอร์ชัน — กันลูป) · แท็บถูกซ่อน = รีโหลดเงียบ +**กติกา:** เพิ่ม/ลบไฟล์ใน `PRECACHE` หรือแก้ `sw.js` = ต้อง bump · แก้รูปทับชื่อเดิม = ต้อง bump + ## หน้ารายละเอียดป้าย `#/stops/<รหัสป้าย>` — ข้อมูลมาจากไหน หน้า `ui/partials/stopDetail.html` เป็น "โครงเปล่า" ล้วน ๆ (มีแต่ `