Vbread.md

Bối cảnh

Chủ dự án không phải lập trình viên. Luôn giải thích bằng tiếng Việt, câu ngắn, dễ hiểu; nói rõ sắp làm gì trước khi sửa nhiều file.
Nghiệp vụ chi tiết: Nghiệp vụ MVP
Câu hỏi còn mở: Khảo sát 22 câu hỏi cần chốt
Khi gặp điều chưa rõ về nghiệp vụ: hỏi lại, không tự đoán. Nếu buộc phải giả định, ghi rõ “GIẢ ĐỊNH” trong câu trả lời và thêm vào danh sách câu hỏi cần chốt.

Người dùng và phân quyền

owner (chủ chuỗi): xem toàn bộ, cấu hình hệ thống.
manager (quản lý vận hành): chỉ thấy các xe/điểm bán được phân công.
staff (nhân viên bán hàng): chỉ thấy ca của mình; nhận hàng, bán hàng, kiểm kê, chốt ca.
Phân quyền phải được kiểm tra ở cơ sở dữ liệu (Row Level Security của Supabase), không chỉ ẩn nút trên giao diện.

Phạm vi MVP (chỉ làm những phần này)

Danh mục: xe, điểm bán, sản phẩm, giá bán, tài khoản nhân viên.
Ca bán: phân công, mở ca (hàng + tiền đầu ca), bàn giao, đóng ca.
Bán hàng: sản phẩm, số lượng, giảm giá, phương thức thanh toán.
Hàng hóa: nhận, bán, trả, hủy/hao hụt, kiểm kê, tồn cuối ca.
Đối soát tiền: tiền phải có so với tiền thực đếm, chênh lệch và lý do.
Báo cáo theo ngày, ca, xe, điểm bán.

KHÔNG làm trong MVP (chỉ làm khi chủ dự án yêu cầu): đặt hàng online, điều phối đơn, QC/chấm điểm, tài sản, KPI, bếp trung tâm, công thức/giá vốn, tính lương, khách hàng thân thiết, tích hợp bên ngoài.

Công nghệ

Next.js (App Router) + TypeScript, Tailwind CSS, shadcn/ui.
Supabase: PostgreSQL, Auth, Row Level Security. Thay đổi cấu trúc dữ liệu luôn bằng file migration trong supabase/migrations/.
Giao diện ưu tiên điện thoại (mobile-first), cài được lên màn hình chính (PWA).
Kiểm thử: Vitest cho logic tính toán; Playwright cho luồng chính.
Triển khai: Vercel (web) + Supabase (dữ liệu).

Quy ước bắt buộc

Giao diện 100% tiếng Việt. Tên biến, bảng, cột trong code bằng tiếng Anh.
Tiền: số nguyên đồng (kiểu bigint), không dùng số thập phân. Hiển thị dạng 25.000 ₫.
Thời gian: lưu timestamptz (UTC), hiển thị theo Asia/Ho_Chi_Minh, định dạng dd/MM/yyyy HH:mm. “Ngày kinh doanh” tính theo giờ Việt Nam.
Số lượng hàng: số nguyên theo đơn vị của sản phẩm (ổ, gói, hộp...).
Không xóa cứng dữ liệu nghiệp vụ; dùng trạng thái hoặc deleted_at.
Mọi thay đổi trên ca đã chốt, giá bán, phiếu kho, đối soát tiền phải ghi vào bảng audit_logs (ai, lúc nào, giá trị cũ, giá trị mới, lý do).
Công thức tính (tồn, tiền phải có, chênh lệch) viết thành hàm riêng trong src/lib/ và có test.
Nút bấm trên điện thoại cao tối thiểu 44px; thao tác bán một món không quá 2 chạm.

An toàn

Không bao giờ đọc, in ra hoặc sửa .env.local, trừ khi chủ dự án yêu cầu rõ.
Khóa SUPABASE_SERVICE_ROLE_KEY chỉ dùng phía máy chủ, không bao giờ đưa vào code chạy trên trình duyệt.
Mọi bảng mới phải bật Row Level Security kèm chính sách truy cập.
Không chạy lệnh xóa dữ liệu, reset cơ sở dữ liệu thật hoặc git push --force khi chưa hỏi.

Cách làm việc

Việc lớn: lập kế hoạch trước, chờ duyệt rồi mới sửa code.
Làm từng bước nhỏ; sau mỗi bước chạy npm run lint và npm test, báo kết quả, rồi đề xuất nội dung commit.
Kết thúc mỗi tính năng: cập nhật docs/nhat-ky-tien-do.md (đã làm gì, còn gì, lưu ý).

Lệnh thường dùng

npm run dev: chạy thử trên máy tại http://localhost:3000
npm run lint: kiểm tra lỗi cú pháp
npm test: chạy kiểm thử

Nội dung này là bản trình diễn của file CLAUDE.md trong repo — nguồn dữ liệu thật để trợ lý AI đọc và áp dụng khi làm việc trên dự án. Sửa nội dung ở đó, trang này sẽ được cập nhật theo.