- drop the SSL note from hero meta, footer column and meta description - footer becomes two columns; ssl_note removed from data schema, payload and server serializer - content-only change: service worker version unchanged (network-first)
6.9 KiB
6.9 KiB
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
คำสั่งที่ใช้บ่อย
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
กติกาที่ห้ามละเมิด
- แก้ที่ repo นี้เท่านั้น —
data/projects.jsonคือข้อมูลจริง ไม่มีฐานข้อมูลอื่น - ห้ามแก้อิโมจิลงหน้าเว็บ — ไอคอนทุกตัวมาจาก
ui/ui.js(icon("ชื่อ")) - ภาษาไทยทั้งหน้า — ห้ามใส่คำอังกฤษเป็นหัวข้อ/ป้าย (โดเมนและคำเทคนิคเท่านั้น)
- สีต้องมาจาก
assets/css/theme.css— ห้ามใส่ hex ใหม่ในไฟล์ view; ถ้าต้องเพิ่มสี ให้เพิ่มเป็นโทเคน + อัปเดตDESIGN.md - ตัวอักษรต้อง ≥ 4.5:1 บนพื้นของตัวเอง — เพิ่มสีใหม่ต้องคำนวณคอนทราสต์ ไม่เดาจากสายตา
- ปุ่ม/ลิงก์ต้องมีพื้นที่กด ≥ 44×44px และมี
aria-labelเมื่อเป็นไอคอนเดี่ยว - แก้
sw.jsหรือรายการPRECACHE→ bumpVERSIONในsw.jsและ<meta name="app-version">ในindex.htmlให้ตรงกัน (แก้ HTML/CSS/JSON อย่างเดียวไม่ต้อง bump) - PWA boot บน plain HTTP ไม่ได้ — ต้อง HTTPS หรือ localhost
- การเปลี่ยนคำ/ค่าออกแบบ → อัปเดต
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)
{
"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ต้องมี schemehttp(s)— เซิร์ฟเวอร์ตอบ 422 ถ้าไม่ผ่านiconต้องเป็นคีย์ในICON_LABELS(ui/views/admin.js) ไม่งั้นจะ fallback เป็นfolder
ขั้นตอนตรวจก่อนส่งงาน
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.serverAPI จะ 404 → หน้าหลังบ้านจะขึ้นสถานะ “เปิดแบบไฟล์นิ่ง” และใช้ดาวน์โหลด JSON แทน - Motion: ทุกครั้งที่สร้าง DOM ใหม่ (กรองคำค้นหา,
mount()ของ admin) ต้องเรียกinitReveal(...)ใหม่ ไม่งั้น element ค้างopacity: 0; hover ยกการ์ดต้องใช้translateไม่ใช่transform; ถ้าวัดผลในแท็บเบื้องหลัง IO/rAF จะไม่ทำงาน ให้Page.bringToFrontก่อนสรุปว่าโค้ดพัง (รายละเอียดในDESIGN.md§9)