ClipperQ

Booking platform for barber shops. Thai pronunciation: คลิปเปอร์คิว.

ClipperQ is the platform, not the shop. On customer pages the merchant brand comes first; ClipperQ stays a small platform signature. Brand rules live in docs/BRAND.md. Cursor/agent brand workflow lives in README_FOR_CURSOR.txt.

Product OS: docs/barberqx-os/README.md. This README is the map, not the full spec.

Product

Customers book from the shop’s LINE OA using ClipperQ LIFF. Owners get a queue board, team, hours, and shop settings without building their own booking system.

Each shop is a tenant at /{shopSlug} (example seed shop: /phinxstudio).

Customers

• Book at /{shopSlug}: barber, date, time, confirm
• View / cancel at /{shopSlug}/bookings
• LINE Login required
• Shop cover, shop name, and (optional) barber photos on the booking page

Owners / staff

• Owner: today board, team, stats; More → schedule, settings, customer booking
• Barber: today board, own schedule; More → customer booking
• Settings: shop name, cover image, logo, LINE/phone, hours
• Claim shop via invite at /owner/join
• Setup / LINE OA install help under /{shopSlug}/admin/setup

Platform ops: /superadmin (shop invites, LINE OA requests) and /pilot (production pilot checklist).

Stack (this repo)

• Next.js 16 App Router, React 19, TypeScript
• Tailwind CSS 4
• LINE LIFF (@line/liff)
• Supabase JS (Postgres + Storage in production)
• In-memory store in local prototype mode when Supabase env is unset
• date-fns / date-fns-tz, lucide-react

Layout

src/app/            routes + API (`/[shop]`, `/admin` re-exports, `/api`)
src/components/     customer, admin, layout, superadmin
src/lib/            booking, auth, shop, data (memory + supabase)
src/types/          shared types
supabase/migrations SQL + Storage buckets
docs/BRAND.md       brand system
docs/barberqx-os/   product operating system
public/brand/       approved ClipperQ assets

Shop-scoped APIs: /api/[shop]/…. Legacy unscoped /api/bookings etc. still exist; prefer shop-scoped routes.

Develop

npm run dev

Open http://localhost:3000. Copy env from .env.example.

Without NEXT_PUBLIC_SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY, the app uses the memory store (prototype). Production requires those plus NEXT_PUBLIC_LIFF_ID, NEXT_PUBLIC_APP_URL, and SUPERADMIN_TOKEN.

Dedicated QA environment (Tommy): step-by-step Thai guide in docs/qa-setup.md.

npm run lint
npm run typecheck
npm run test:shop
npm run test:booking
npm run test:security
npm run test:onboarding
npm run build
npm run start

UI QA crawl (Playwright / ภาษาไทย)

ชุดตรวจ UI อัตโนมัติยิงไปที่ barberq-qa เท่านั้น (ร้าน barberqpilottest) — ห้ามยิง Production (barber-q / barber-q-pi.vercel.app) สคริปต์จะ hard-fail ถ้า base URL เป็นโปรดักชัน

# หน้าสาธารณะ (ไม่ต้องมี secret)
QA_BASE_URL=https://barberq-qa.vercel.app npm run qa:crawl

# รวมหน้า admin เมื่อ deploy แล้วตั้ง QA_E2E_SECRET บน Vercel barberq-qa
QA_BASE_URL=https://barberq-qa.vercel.app QA_E2E_SECRET=… npm run qa:crawl

ผลลัพธ์: report/index.html (กริดภาพ 3 viewport + ปัญหาเรียง fail/warn) และ report/summary.json
Workflow มือ (workflow_dispatch): .github/workflows/qa-ui-crawl.yml — อัปโหลด artifact ไม่บังคับใน CI

Env ที่ต้องใส่ใน Vercel โปรเจกต์ barberq-qa (ชื่ออย่างเดียว): QA_E2E_SECRET (และต้องมีอยู่แล้ว: BARBERQ_ENV, NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_APP_URL) — ห้ามใส่บน Production

Security / tenancy (high level)

• Data and admin actions are shop-scoped. Staff from shop A cannot manage shop B.
• Customer identity is LINE. Owner/barber roles are shop staff records, not a platform super_admin role on the shop.
• Super Admin is a separate token (SUPERADMIN_TOKEN), not a shop owner.
• Uploads (cover / barber photos) go through owner-authorized APIs; buckets are public-read, writes are server-side.
• Do not leak shop IDs, tokens, or another shop’s bookings across tenants.

Status

0.1.0, private. Product is in pilot / beta: real shops can be invited from Super Admin and exercised via /pilot. Local prototype mode is for development only; production must not use the memory store or LINE mock auth.