# AGENTS.md — คู่มือสำหรับ agent ที่เข้ามาแก้โปรเจคนี้ ## ภาพรวม Static PWA + SPA (ไม่มี build step) สำหรับหน้ารายชื่อโปรเจคอดิเรก + หลังบ้านแก้ข้อมูล สแตก: HTML + CSS + ES modules ตรง ๆ · Node 22 สำหรับเซิร์ฟเวอร์หลังบ้าน (ไม่มี dependency) Repository: `hobbypj-contents` (Gitea org `hobbyproject-list`) · deploy เป้าหมาย `www.hobbypj.com` ## คำสั่งที่ใช้บ่อย ```bash node server/publish.mjs # เซิร์ฟเวอร์ + หลังบ้าน → http://localhost:8090 npm run check # ตรวจ syntax ทุกไฟล์ JS/MJS PORT=8090 ADMIN_TOKEN=xxx node server/publish.mjs # โหมดมีรหัสเผยแพร่ PUBLISH_PUSH=0 node server/publish.mjs # เขียน+commit แต่ไม่ push ``` ## กติกาที่ห้ามละเมิด 1. **แก้ที่ repo นี้เท่านั้น** — `data/projects.json` คือข้อมูลจริง ไม่มีฐานข้อมูลอื่น 2. **ห้ามแก้อิโมจิลงหน้าเว็บ** — ไอคอนทุกตัวมาจาก `ui/ui.js` (`icon("ชื่อ")`) 3. **ภาษาไทยทั้งหน้า** — ห้ามใส่คำอังกฤษเป็นหัวข้อ/ป้าย (โดเมนและคำเทคนิคเท่านั้น) 4. **สีต้องมาจาก `assets/css/theme.css`** — ห้ามใส่ hex ใหม่ในไฟล์ view; ถ้าต้องเพิ่มสี ให้เพิ่มเป็นโทเคน + อัปเดต `DESIGN.md` 5. **ตัวอักษรต้อง ≥ 4.5:1** บนพื้นของตัวเอง — เพิ่มสีใหม่ต้องคำนวณคอนทราสต์ ไม่เดาจากสายตา 6. **ปุ่ม/ลิงก์ต้องมีพื้นที่กด ≥ 44×44px** และมี `aria-label` เมื่อเป็นไอคอนเดี่ยว 7. **แก้ `sw.js` หรือรายการ `PRECACHE` → bump `VERSION`** ใน `sw.js` และ `` ใน `index.html` ให้ตรงกัน (แก้ HTML/CSS/JSON อย่างเดียวไม่ต้อง bump) 8. **PWA boot บน plain HTTP ไม่ได้** — ต้อง HTTPS หรือ localhost 9. การเปลี่ยนคำ/ค่าออกแบบ → อัปเดต `DESIGN.md` และ `README.md` (เครดิต) ด้วยในคอมมิตเดียวกัน ## แผนที่ไฟล์ | ไฟล์ | หน้าที่ | |---|---| | `index.html` | shell: header/footer, meta, manifest, mount `#main` | | `ui/app.js` | boot: โหลดข้อมูล → ผูก router → เรนเดอร์ view, อัปเดต footer | | `ui/router.js` | hash router (`#/`, `#/admin`) + `aria-current` ของเมนู | | `ui/data.js` | อ่าน/เขียนข้อมูล, normalize, ฉบับร่าง (localStorage), `PUT api/projects` | | `ui/ui.js` | ชุดไอคอน SVG, escape, toast, ตรวจ URL/อีเมล | | `ui/views/home.js` | ฮีโร่ + ค้นหา + การ์ดโปรเจค | | `ui/views/admin.js` | หลังบ้าน: ฟอร์มแก้ไข, เรียงลำดับ, ลบ, เผยแพร่, ดาวน์โหลด JSON | | `server/publish.mjs` | static server + `GET/PUT api/projects` + git commit/push | | `data/projects.json` | ข้อมูลจริง (คีย์เต็มคำ: `project_name`, `project_description`, `project_url`, `contact_email`, `icon`) | ## สัญญาข้อมูล (schema) ```json { "schema_version": 1, "updated_at": "ISO-8601", "owner_name": "", "site": { "site_title": "", "welcome_message": "", "contact_email": "" }, "projects": [ { "project_id": "", "project_name": "", "project_description": "", "project_url": "https://…", "contact_email": "", "icon": "folder" } ] } ``` - `project_id` ต้องไม่ซ้ำ (ตัว normalize เติมให้อัตโนมัติถ้าซ้ำ) - `project_url` ต้องมี scheme `http(s)` — เซิร์ฟเวอร์ตอบ 422 ถ้าไม่ผ่าน - `icon` ต้องเป็นคีย์ใน `ICON_LABELS` (`ui/views/admin.js`) ไม่งั้นจะ fallback เป็น `folder` ## ขั้นตอนตรวจก่อนส่งงาน ```bash npm run check node server/publish.mjs curl -s localhost:8090/api/projects | head -5 # เปิด http://localhost:8090/ และ http://localhost:8090/#/admin ``` ในเบราว์เซอร์: `Page.getAppManifest` ต้องได้ `errors: []`, `navigator.serviceWorker.controller` ต้องไม่ว่าง, ไม่มี error ใน console, และทดสอบที่ 375 / 768 / 1440 px (`scrollWidth === innerWidth`) ## กับดักที่เคยเจอ - ฟอนต์: `assets/css/theme.css` อ้าง `../../fonts/…` — ถ้าย้าย CSS ให้แก้ path ไม่งั้นฟอนต์ไทยหลุดเป็นฟอนต์ระบบ - `PUT api/projects` เขียนทับทั้งไฟล์: ส่งข้อมูลที่ normalize แล้วเท่านั้น ไม่งั้นคีย์จะหาย - กดเผยแพร่ซ้ำโดยไม่แก้อะไรจะได้ commit ใหม่ (เพราะ `updated_at` เปลี่ยน) — ปกติ ไม่ใช่บั๊ก - ถ้าเปิดเว็บด้วย `python -m http.server` API จะ 404 → หน้าหลังบ้านจะขึ้นสถานะ “เปิดแบบไฟล์นิ่ง” และใช้ดาวน์โหลด JSON แทน - **Motion**: ทุกครั้งที่สร้าง DOM ใหม่ (กรองคำค้นหา, `mount()` ของ admin) ต้องเรียก `initReveal(...)` ใหม่ ไม่งั้น element ค้าง `opacity: 0`; hover ยกการ์ดต้องใช้ `translate` ไม่ใช่ `transform`; ถ้าวัดผลในแท็บเบื้องหลัง IO/rAF จะไม่ทำงาน ให้ `Page.bringToFront` ก่อนสรุปว่าโค้ดพัง (รายละเอียดใน `DESIGN.md` §9)