Files
web-alterflixhub/docs/api.md
T
Bkk1234 e6e935762e docs: ปรับเอกสารให้ตรงสถานะปัจจุบัน (motion, parity, SEO, push)
- README: เพิ่มบรรทัด "หน้าตาเท่ากันทุกเอนจิน" + อธิบายการ gate อนิเมชันแบบสองชั้น
- docs/api.md: content store มี forCinemas/forFilmLovers · loader คืน origin/siteUrl/shareOrigin · sitemap/robots เป็น Nitro route
- docs/architecture.html: แก้ robots ไม่ใช่ static, 7 แท็บ, เพิ่ม ShareOriginProvider/MotionBootstrap, parity layer, แก้คำผิด "블록"
- docs/push-to-gitea.md: เขียนใหม่ให้ตรงจริง (repo web-alterflixhub, ต้อง -c http.version=HTTP/1.1, ลำดับก่อน push, วิธีตรวจว่า push ขึ้น)
2026-11-14 13:27:53 +07:00

55 lines
4.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 ดิบ |
`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`) |
| PUT | `/api/admin/content` | `{ cinemas?, site?, about?, forCinemas?, forFilmLovers? }` | บันทึกเฉพาะส่วนที่ส่งมา — ผ่าน `sanitizeCinemas` / `sanitizeSite` / `sanitizeAbout` / `sanitizeForCinemas` / `sanitizeForFilmLovers` แล้วเขียนไฟล์แบบ atomic |
| 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` — ทั้งคู่ไม่ควรถูกเขียนด้วยมือระหว่างเซิร์ฟเวอร์รัน