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` เป็น "โครงเปล่า" ล้วน ๆ (มีแต่ `