Aide Collector

REST API สำหรับรวบรวมและอ่านข้อมูล cinema, gold, lottery, MEA, MWA, solar, ONT และ reminder พร้อม endpoint สำหรับจัดการ API token สร้างด้วย Bun, Elysia, Kysely และ PostgreSQL

เริ่มต้นใช้งาน

ต้องมี Bun 1.3 ขึ้นไป และ PostgreSQL โดยสามารถเปิดฐานข้อมูลสำหรับ development ผ่าน Docker Compose ได้

docker compose up -d db
cp .env.example .env
bun install
bun run migration:run
bun run dev

แก้ DATABASE_URL และค่าของ collector ที่ต้องการใช้ใน .env ก่อนรัน migration เซิร์ฟเวอร์เปิดที่ http://localhost:3000 โดยค่าเริ่มต้น และ Swagger UI อยู่ที่ GET /docs

Migration ไม่ได้ทำงานอัตโนมัติตอน boot ต้องรัน bun run migration:run หลังสร้างฐานข้อมูลและทุกครั้งที่มี migration ใหม่

ตัวแปรสภาพแวดล้อม

ตัวแปร	จำเป็น	รายละเอียด
DATABASE_URL	ใช่	PostgreSQL connection string
PORT	ไม่	พอร์ตของ API ค่าเริ่มต้น 3000
LOG_LEVEL	ไม่	ระดับ log ของ Pino ค่าเริ่มต้น info
MASTER_KEY	ไม่	key สำหรับ bootstrap/จัดการ token โดยไม่ต้องมี record ใน api_keys
MEA_PAYLOAD	เฉพาะ MEA	Base64 ของ JSON { "username", "password" }
MWA_PAYLOAD	เฉพาะ MWA	Base64 ของ JSON { "userId", "password" }; ดึงทุกบัญชีที่ลงทะเบียนไว้
SOLAR_DEVICE_ID	เฉพาะ Solar	device ID ที่จะรวบรวมข้อมูล
SOLAR_OPEN_APP_ID	เฉพาะ Solar	App ID ของ Solar Open API
SOLAR_OPEN_APP_SECRET	เฉพาะ Solar	encrypted App Secret สำหรับลงลายเซ็น request
SOLAR_PAYLOAD	เฉพาะ Solar	Base64 ของ JSON { "account", "password" } โดย password เป็น MD5 hex

คำสั่งหลัก

bun run dev             # development server พร้อม watch และ pretty logs
bun run start           # production-style server
bun run migration:run   # apply migrations ล่าสุด
bun run migration:down  # rollback migration ล่าสุดหนึ่งขั้น
bun run test            # unit tests
bun run lint            # ESLint แบบไม่แก้ไฟล์
bun run format          # ตรวจ Prettier แบบไม่แก้ไฟล์
bun run build           # bundle สำหรับ Bun ไปที่ build/index.js

ใช้ bun run lint:fix และ bun run format:fix เมื่อต้องการแก้ lint/format อัตโนมัติ

ตั้งเวลา collector

บรรทัด cron ของ collector อยู่ที่ docs/crontab แก้ host ให้ตรงกับที่ deploy แล้วต่อท้าย crontab -e

endpoint กลุ่ม /stash ไม่ต้องใช้ API key จึงเรียกจาก cron ได้ตรง ๆ

Endpoints

Read API

• GET /health — health check
• GET /collector/cinema — ข้อมูลหนัง; filter ได้ด้วย genre, release_date, search, week, year
• GET /collector/cinema/theater?search= — รายชื่อสาขา Major พร้อมชื่อไทย/อังกฤษและโซน (ดึงสด ไม่เก็บลง DB)
• GET /collector/cinema/showtime?theater=&date=&movie=&time=&from=&to=&seats= — รอบฉายสดของสาขา ต้องระบุช่วงเวลา (time หรือ from+to) และ date ได้แค่วันนี้/พรุ่งนี้ ใส่ seats=true เพื่อดูที่นั่งว่าง (ดึงทีละรอบ สูงสุด 10 รอบ)
• GET /collector/cinema/showtime/:showtime/seat?detail= — ผังที่นั่งสดของรอบนั้น จำนวนว่าง/ถูกจอง และราคาตั๋ว
• GET /collector/cinema/:movie/:theater — ทางลัดถามรอบฉายของหนังเรื่องหนึ่งที่สาขาหนึ่ง
• GET /collector/gold?currency=USD|THB — ราคาทองและกำไร/ขาดทุนจาก reminder
• GET /collector/ont — snapshot อุปกรณ์ ONT ล่าสุดจาก PostgreSQL
• GET /collector/ont/:mac/history?from=&to=&limit= — ประวัติสถานะต่อเครื่อง ย้อนหลัง 24 ชั่วโมงโดยค่าเริ่มต้น
• GET /lottery?limit=24 — ประวัติผลรางวัลล่าสุด

Collector jobs

• PATCH /stash/cinema — scrape รายการหนัง now-showing/coming-soon จาก Major Cineplex (และ SF Cinema เมื่อเข้าถึงได้) แล้ว upsert ลง bucket ของสัปดาห์ปัจจุบัน
• POST /stash/cinema — รับ batch ที่ scrape มาแล้ว รวมข้อมูลโรงหนัง และลบรายการซ้ำ
• PATCH /stash/gold — ดึงราคาทองล่าสุดแล้วบันทึก
• PATCH /stash/ont — ใช้ Chrome อ่าน ONT หนึ่งรอบ รวม AdGuard แล้วบันทึก; เรียกผ่าน curl จาก cron
• PATCH /stash/lottery — ดึงผลรางวัลล่าสุดแล้วบันทึก
• PATCH /stash/lottery/bulk?date=YYYY-MM-DD — เริ่ม backfill ผลรางวัลและตอบ 202 ทันที
• PATCH /stash/mea — ดึงมิเตอร์ ประวัติค่าไฟ และประวัติการชำระย้อนหลังแยกรายเดือน โดยจับคู่ billNo แบบคงเลขศูนย์นำหน้า
• PATCH /stash/mwa — login, ดึงทุกบัญชีที่ลงทะเบียนพร้อมประวัติใบเสร็จ/ค่าน้ำ และบันทึกแบบ upsert
• PATCH /stash/solar?interval=1h — เก็บ Solar ครบทั้ง record/key history, latest state, alarm, device snapshot, energy flow, config snapshot และ station summary; history ใช้ช่วงย้อนหลัง 3 ชั่วโมงโดยค่าเริ่มต้น
• PATCH /stash/solar/bulk?date=YYYY-MM-DD — เริ่ม backfill record/key history และ station summary รายวัน/เดือน/ปี พร้อม refresh ชุดข้อมูลที่ API มีเฉพาะค่าปัจจุบัน แล้วตอบ 202 ทันที
• POST /reminder/gold — บันทึกข้อมูลการลงทุนทองสำหรับการคำนวณ collector

Token API

• GET /v1/token — แสดง active tokens
• POST /v1/token — สร้าง token
• DELETE /v1/revoke — revoke token ของผู้เรียก

endpoint กลุ่ม /v1 ต้องส่ง header X-API-Key ที่ active หรือใช้ MASTER_KEY หากกำหนดไว้

โครงสร้างโปรเจกต์

src/
├── index.js                 # ประกอบ Elysia app และ lifecycle
├── config.js                # environment, logger และ metadata
├── db.js                    # PostgreSQL/Kysely และ migration runner
├── json.js                  # normalize JSONB ที่ driver คืนเป็น string
├── middleware.js            # request context, error/response logging, Swagger
├── reminders.js             # อ่าน/เขียน JSON reminder แบบรวมศูนย์
├── migrations/              # Kysely migrations
└── routes/
    ├── collector.js         # read APIs
    ├── reminder.js          # gold reminder
    ├── token.js             # API-token lifecycle
    └── stash/               # external collectors และ bulk jobs
        └── cinema/          # scrape/normalize/store ของ cinema collector

ไฟล์ CLAUDE.md บันทึกแนวทางดูแลโค้ด การเปลี่ยนแปลงเชิง technical debt และคำสั่ง verification ล่าสุด

รายละเอียดตาราง แหล่งข้อมูล และขอบเขตการ backfill ของ Solar อยู่ที่ docs/solar-schema.md

รายละเอียดของ cinema collector แหล่งข้อมูล และข้อจำกัดของ SF Cinema อยู่ที่ docs/cinema-collector.md

รายละเอียด ONT collector, migration 010_ont, Chromium, environment และตัวอย่าง curl อยู่ที่ docs/ont-collector.md