- server: GET /api/local-projects scans sibling folders for index.html (title from <title>/<h1>, generic titles fall back to the folder name, sorted by newest edit) and GET /projects/<folder>/ serves that folder - both endpoints are loopback-only; node_modules/.git/.hermes blocked and path traversal rejected; WORKSPACE_DIR=none disables the feature - home: new 'โปรเจคในเครื่อง' list (2 columns >=700px) that hides itself when the API is absent, so the live static site never shows fake rows - SW skips /projects/* so other projects' files are never cached; version 2026.11.19.5 - docs: README/AGENTS/DESIGN cover the endpoints, the loopback rule and the layout
100 lines
10 KiB
Markdown
100 lines
10 KiB
Markdown
# 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` และ `<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)
|
|
|
|
```json
|
|
{
|
|
"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` ซึ่งต้องตั้งทุกครั้งที่เปิดเซิร์ฟเวอร์ให้เครื่องอื่นเข้าถึง
|
|
|
|
## โปรเจคในเครื่อง (`/projects/*`)
|
|
|
|
`server/publish.mjs` สแกนโฟลเดอร์ข้างเคียง (ค่าเริ่มต้น `D:\Git\workspace`) แล้วเปิดหน้า `index.html` ของแต่ละโปรเจคให้คลิกดูได้จากหน้าแรก
|
|
|
|
- `GET /api/local-projects` — รายการโฟลเดอร์ที่พบ (เรียงตามเวลาแก้ล่าสุด), `GET /projects/<โฟลเดอร์>/…` — เสิร์ฟไฟล์
|
|
- **รับเฉพาะ loopback** ทั้งสอง endpoint (`isLoopback`) ห้าม loosen เป็น 0.0.0.0 เด็ดขาด เพราะจะเปิดไฟล์ทั้งเครื่องให้ LAN
|
|
- เพิ่มโฟลเดอร์เข้า `SKIP_NAMES` เมื่อมีของที่ไม่ควรถูกสแกน; ชื่อ `<title>` ที่เป็นคำลอย ๆ ถูกแทนด้วยชื่อโฟลเดอร์ผ่าน `GENERIC_TITLES`
|
|
- `ui/views/home.js` ซ่อนส่วนนี้เมื่อ API ไม่ตอบ (static host) — อย่าทำให้มันแสดงรายการปลอม
|
|
- `sw.js` ข้าม `/projects/*` (ไม่แคชไฟล์ของโปรเจคอื่น)
|
|
|
|
## ขั้นตอนตรวจก่อนส่งงาน
|
|
|
|
```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)
|