CLR
Webapp (PWA) cho CLB chạy bộ CLR: đăng nhập bằng Strava, thống kê, challenge, thưởng phạt, event, quỹ. Kế hoạch và tiến độ nằm trong plans/.
Chạy local
Yêu cầu: Node 24 (nvm use), Docker (cho Supabase local).
npm ci
cp .env.example .env.local
npx supabase start # in ra URL và key local, điền vào .env.local
npx supabase db reset # chạy migration + seed
npm run dev # http://localhost:3000
Trang kiểm tra (chỉ có khi chạy dev): /dev/theme (bảng màu), /dev/db (đọc bảng settings).
Kiểm tra trước khi commit: npm run typecheck && npm run lint && npm test.
Sinh lại kiểu DB sau khi đổi schema: npm run db:types (ghi src/lib/types/database.generated.ts, không sửa tay). Code import Database từ @/lib/types/database, file này thu hẹp các cột text có check constraint thành union; thêm giá trị vào constraint thì sửa union ở đó.
Đưa migration lên production
Tự động: khi merge vào main có file mới trong supabase/migrations/, workflow Migrate production chạy supabase db push lên project production. Cần 3 secret trong GitHub (Settings → Secrets and variables → Actions): SUPABASE_ACCESS_TOKEN (tạo ở supabase.com/dashboard/account/tokens), SUPABASE_DB_PASSWORD (mật khẩu database của project production), SUPABASE_PROJECT_REF (project ref của clr). Có thể chạy lại tay ở tab Actions.
Preview (clr-preview) vẫn chạy tay:
npx supabase login
npx supabase link --project-ref <project-ref-preview>
npx supabase db push
Migration chỉ thêm file mới (supabase/migrations/000N_*.sql), không sửa file đã chạy.
Triển khai
Vercel: preview cho mỗi PR, production từ main. Biến môi trường khai báo theo .env.example (URL công khai là APP_URL, không có tiền tố NEXT_PUBLIC_), tách Preview và Production (Preview dùng project Supabase riêng).
Đồng bộ Strava
- Điền
STRAVA_WEBHOOK_VERIFY_TOKEN và CRON_SECRET trên Vercel (Production và Preview), thêm secret APP_URL và CRON_SECRET vào GitHub Actions để workflow Strava cron gọi /api/cron/*.
- Sau khi deploy, đăng ký webhook một lần:
npm run strava:subscribe -- create (đọc .env.local; Strava gọi GET /api/strava/webhook để xác thực). list xem subscription, delete <id> xoá. Mỗi app Strava chỉ có một subscription.
Ảnh event (Cloudflare R2)
- Tạo bucket R2, bật truy cập công khai qua custom domain (ví dụ
img.clr.vn), tạo API token quyền Object Read & Write cho đúng bucket.
- Điền
R2_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, R2_BUCKET, R2_PUBLIC_BASE_URL trên Vercel (Production và Preview).
- Trình duyệt PUT thẳng lên R2 nên bucket cần CORS cho domain của app (Settings > CORS policy):
[
{
"AllowedOrigins": ["https://<domain-app>", "http://localhost:3000"],
"AllowedMethods": ["PUT", "GET"],
"AllowedHeaders": ["Content-Type"],
"MaxAgeSeconds": 3600
}
]
Ảnh event nằm dưới events/{eventId}/; ảnh giấy chứng nhận (task 5.2) sẽ dùng prefix riêng.
