Files
web-alterflixhub/docs/api.md
T
Bkk1234 1932098a1d feat(home): ชั้นกรองที่ 1 — ประเภทโรงหนัง (ท้องถิ่น / อินดี้ / กลุ่มคนฉายหนัง)
- แถบกรองสองชั้นในแถวเดียว: ทั้งหมด → 3 ประเภท │ ยอดนิยม → หมวดภาพยนตร์เดิม
- เก็บประเภทที่ฟิลด์เดี่ยว cinema.venue_type (ค่าเดียว) + hasVenue()/filterCinemas({ venue })
- ย้าย "กลุ่มคนฉายหนัง" จาก categories ขึ้นชั้น 1 (ไม่ให้ปุ่มซ้ำ) · tag ยังอยู่และยังค้นหาเจอ
- เลือกได้ทีละชั้น: กดประเภทล้างหมวด / กดหมวดล้างประเภท / ทั้งหมดล้างทั้งคู่
- ปิด popularity path เมื่อกรองด้วยประเภท (กันจัดอันดับข้ามประเภท)
- หลังบ้าน: ช่อง "ประเภทโรงหนัง" ในหมวดข้อมูลหลัก + sanitize เฉพาะค่าใน VENUE_TYPES
- i18n: messages.venues (TH/EN) · override ได้ผ่าน site.terms
- scripts/set-venue-types.mjs จัดประเภท 29 โรง (15 ท้องถิ่น / 11 อินดี้ / 3 กลุ่มคนฉายหนัง) พร้อมสำรอง content.json
- tests: hasVenue + filterCinemas (165 ผ่าน) · sw v2.0.5 · DESIGN/AGENTS/README/admin-guide/api อัปเดต
2026-11-16 01:46:59 +07:00

57 lines
5.7 KiB
Markdown

# API reference — AlterFlixHub
ทุก endpoint เป็น `JSON` และอยู่ใต้ path `/api` ของแอปเอง (ไม่ต้องมี prefix อื่น)
ค่าเริ่มต้น: `Content-Type: application/json` · error ใช้รูปแบบ `{ statusMessage }` หรือ `{ message }`
## สาธารณะ (ไม่ต้องล็อกอิน)
| Method | Path | Body / Query | ทำอะไร |
|---|---|---|---|
| POST | `/api/analytics/collect` | `{ type, locale, query?, category?, result_count?, slug?, source?, position? }` | รับ event สถิติ 1 ครั้ง — เซิร์ฟเวอร์เป็นผู้ใส่ `at` และ hash ผู้เข้าชม (`sha256(เกลือรายวัน \| ip \| ua)` 16 ตัวอักษร) ไม่ใช้คุกกี้ ไม่เก็บ IP/UA ดิบ |
| GET | `/uploads/cinemas/<ไฟล์>` | — | เสิร์ฟรูปที่อัปโหลดจากหลังบ้าน (อ่านจาก `data/uploads/cinemas/`) · `Cache-Control: immutable` · กัน path traversal |
`type` ที่รองรับ: `search` · `cinema_select` · `cinema_view` · `near_me`
## หลังบ้าน (ต้องมีคุกกี้ `afx_admin`)
| Method | Path | Body / Query | ทำอะไร |
|---|---|---|---|
| POST | `/api/admin/login` | `{ username, password }` | ตรวจรหัส → ออกคุกกี้ HttpOnly เซ็น HMAC (8 ชั่วโมง) |
| POST | `/api/admin/logout` | — | ลบคุกกี้ session |
| GET | `/api/admin/session` | — | ตรวจว่ายังล็อกอินอยู่ |
| GET | `/api/admin/content` | — | อ่าน `ContentStore` ทั้งก้อน (`cinemas`, `site`, `about`, `forCinemas`, `forFilmLovers`) |
| POST | `/api/admin/uploads` | `multipart/form-data`: `file` (บังคับ, ≤ 8 MB), `slug` (ไม่บังคับ) | อัปโหลดรูปโรงหนัง — ตรวจชนิดจริงจาก magic bytes (JPEG/PNG/WebP/AVIF) เก็บที่ `data/uploads/cinemas/` คืน `{ url, bytes, type }` โดย `url` = `/uploads/cinemas/<ไฟล์>` |
| PUT | `/api/admin/content` | `{ cinemas?, site?, about?, forCinemas?, forFilmLovers? }` | บันทึกเฉพาะส่วนที่ส่งมา — ผ่าน `sanitizeCinemas` / `sanitizeSite` / `sanitizeAbout` / `sanitizeForCinemas` / `sanitizeForFilmLovers` แล้วเขียนไฟล์แบบ atomic · **`contacts[].href` ถูกคำนวณใหม่ให้กดใช้ได้จริง (tel:/mailto:/https:) ทุกครั้ง** · `venue_type` รับเฉพาะค่าใน `VENUE_TYPES` (ค่าอื่นถูกทำให้เป็น `null`) |
| POST | `/api/admin/cinemas/import` | `{ cinemas: Cinema[] }` หรือรายการเดียว | นำเข้าโรงหนังโดยใช้ slug เป็นกุญแจ (มีอยู่ = ทับ) |
| GET | `/api/admin/analytics` | `?days=1\|7\|30\|90` | สรุปสถิติ (`summarize()`) — คำค้นยอดนิยม, คำค้นไม่พบผล, CTR, โรงที่ถูกเปิด/คลิก |
## ข้อมูลที่ฝังมากับ loader (ไม่ใช่ API)
| Route | ค่าที่ส่งมา |
|---|---|
| `/` (root loader) | `content` (cinemas/site/about/forCinemas/forFilmLovers) + `localeFromUrl` + **`siteUrl`** และ **`shareOrigin`** (origin ของ request ใช้ทำ canonical/OG/ลิงก์แชร์ — ไม่ฝังโดเมน) |
| `/` (`_index` loader) | `popularity` + `orderKey` (สลับลำดับการ์ดรายวัน) + `origin` |
| `/cinema/:slug` | ฟิลด์ SEO ของโรง (`name`, `description`, `locationLabel`, `coordinates`, `mapUrl`, `photo`) + `origin` แล้วนำไปสร้าง meta/JSON-LD |
| `/about` · `/for-cinemas` · `/for-film-lovers` · `/admin` · `/admin/login` | `{ origin }` — `meta()` ของ React Router ไม่มี access ต่อ request จึงต้องส่งมาจาก loader |
| `/sitemap.xml` · `/robots.txt` | ไม่ใช่ loader ของ React — เป็น Nitro route (`server/routes/`) อ่าน origin จาก header เอง |
## ตัวอย่างเรียก
```bash
# บันทึกเฉพาะ cinemas (เช่น หลังลากสลับลำดับ)
curl -X PUT http://localhost:8080/api/admin/content \
-H 'Content-Type: application/json' \
--cookie "$(cat .output/afx_admin.cookie)" \
-d '{"cinemas": [...]}'
# อ่านสถิติ 30 วัน
curl -H "Cookie: afx_admin=$TOKEN" \
'http://localhost:8080/api/admin/analytics?days=30'
```
## ข้อควรระวัง
- `PUT /api/admin/content` **เขียนทับทั้งก้อนของส่วนที่ส่งมา** — ถ้าส่ง `cinemas` ต้องส่งของครบทุกรายการ ไม่ใช่แค่ตัวที่แก้
- `slug` เปลี่ยนแล้วลิงก์เดิม `/cinema/<slug>` จะ 404 (ยังไม่มี redirect table)
- ไฟล์จริงอยู่ที่ `data/content/content.json` · สถิติที่ `data/analytics/events.jsonl` — ทั้งคู่ไม่ควรถูกเขียนด้วยมือระหว่างเซิร์ฟเวอร์รัน