Files
hobbypj-contents/AGENTS.md
T

8.8 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

กติกาที่ห้ามละเมิด

  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 และ <meta name="app-version"> ใน 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/auth.js ด่านชื่อ+รหัสของหลังบ้าน: PBKDF2 เทียบกับ verifier ใน config/admin-credentials.json (sessionStorage, ล็อก 30 วิเมื่อผิด 5 ครั้ง)
config/admin-credentials.json salt + iterations + verifier ของรหัสหลังบ้าน (ไม่มีรหัสจริง) — สร้างด้วยสคริปต์เท่านั้น
server/set-admin-password.mjs ตั้ง/เปลี่ยนรหัสหลังบ้าน → เขียน config/admin-credentials.json
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": "" },
  "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

หลังบ้านถูกล็อกด้วยชื่อ+รหัส

รหัสไม่ได้อยู่ในโค้ด: ui/auth.js เก็บเฉพาะวิธีตรวจ (PBKDF2-HMAC-SHA256, 250,000 รอบ, salt 16 ไบต์, เทียบแบบ constant-time) ส่วนค่า salt/verifier อยู่ใน config/admin-credentials.json — สร้างใหม่ด้วย node server/set-admin-password.mjs admin <รหัสใหม่> และจำสถานะล็อกอินใน sessionStorage → ปิดแท็บแล้วต้องใส่ใหม่

ข้อจำกัดที่ต้องรู้: การทำ hash กันไม่ให้รหัสโผล่ใน source แต่ไม่ได้กันคนที่เปิด devtools (แก้ JS ให้ isAuthed() คืน true ได้เลย) และ verifier ที่ได้ก็ถูกเดารหัส offline ได้ถ้ารหัสอ่อน — การป้องกันจริงคือ ADMIN_TOKEN ของ server/publish.mjs ซึ่งต้องตั้งทุกครั้งที่เปิดเซิร์ฟเวอร์ให้เครื่องอื่นเข้าถึง

ขั้นตอนตรวจก่อนส่งงาน

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)