Rentory
Quản lý hóa đơn phòng trọ — một codebase, một deployment, nhiều tòa nhà (định tuyến theo subdomain).
Tòa nhà đầu tiên: 190 Nguyễn Trãi → https://190nt.vercel.app
Toàn bộ tài liệu đặc tả nằm trong docs/:
Stack
| Layer | Chọn |
|---|
| Framework | Next.js 15 App Router + TypeScript strict |
| UI | Tailwind CSS v4 + shadcn/ui + lucide-react |
| Data | Supabase (Postgres + Auth + RLS), @supabase/supabase-js, @supabase/ssr |
| Client state | TanStack Query v5 |
| Validation | Zod |
| Date | date-fns |
| Font | Space Grotesk (tiêu đề + số tiền), Manrope (body), subset vietnamese |
| Test | Vitest |
Chạy local
npm install
cp .env.example .env.local # rồi điền key thật
npm run dev
.env.local (không commit):
NEXT_PUBLIC_SUPABASE_URL=https://hmymrmnrtreblizpvwbe.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=sb_publishable_...
SUPABASE_SECRET_KEY=sb_secret_... # server-only
DEFAULT_BUILDING_SLUG=190nguyentrai
Dùng cặp key mới sb_publishable_ / sb_secret_, không dùng anon / service_role.
SUPABASE_SECRET_KEY chỉ được import từ server — không bao giờ đặt sau tiền tố NEXT_PUBLIC_.
Trên localhost và *.vercel.app, host không có subdomain hợp lệ nên middleware rơi về
DEFAULT_BUILDING_SLUG. Thiếu biến này thì local dev và Preview sẽ chết.
Lệnh
npm run dev # dev server
npm run build # production build
npm run test # vitest (bắt buộc xanh trước khi merge)
npm run typecheck # tsc --noEmit
npm run lint # eslint
Database
Mọi thay đổi schema chỉ qua migration file trong supabase/migrations/, commit vào Git.
Không sửa tay trên Dashboard.
export SUPABASE_ACCESS_TOKEN=... # Personal Access Token
npx supabase link --project-ref hmymrmnrtreblizpvwbe
npx supabase db push # đẩy migration mới
npx supabase gen types typescript --project-id hmymrmnrtreblizpvwbe --schema public > src/types/database.ts
RLS: 1 admin / tòa nhà. Mọi bảng dẫn về buildings.admin_id = auth.uid() qua các
hàm is_my_building / building_of_room / building_of_invoice / building_of_receipt.
Cấu trúc
src/
app/ # App Router
login/ # S-01 đăng nhập
auth/signout/ # route đăng xuất
components/
ui/ # shadcn/ui
lib/
billing/ # ★ toàn bộ nghiệp vụ tính toán — pure function, có test
code.ts # 4.4 mã hóa đơn
periods.ts # 4.1 kỳ thu trước / thu sau
defaults.ts # HD-01/02/03 số liệu mặc định 3 loại hóa đơn
recognized.ts # TT-03/TT-06 số ghi nhận & trạng thái thu
marks.ts # HD-04/HD-08a mốc công tơ + log
occupants.ts # BR-P13…P17 người ở, người đại diện, ngưỡng hết hạn
meter.ts # BR-M01 thứ tự đọc công tơ, ngày chốt mặc định
print.ts # mục 7 SRS — model bản in hóa đơn
png.ts # xuất DOM → PNG (không dùng thư viện ngoài)
supabase/ # client (browser) · server (RLS) · admin (bypass RLS)
tenant.ts # 2.5 host → slug tòa nhà
env.ts # validate env bằng Zod
middleware.ts # subdomain + refresh session + chặn route
supabase/migrations/ # nguồn sự thật của schema
Nguyên tắc: tiền là số nguyên VND (int), không float. Kỳ là chuỗi YYYY-MM.
Toàn bộ tính toán nằm trong lib/billing/ dưới dạng pure function có unit test; UI chỉ gọi.
Mỗi function comment mã quy tắc tương ứng (// HD-02).
Deploy
main → Production (Vercel project rentory, account ducpm103)- PR → Preview
Domain đang dùng: 190nt.vercel.app — domain free của account, không cần DNS.
*.vercel.app luôn rơi về DEFAULT_BUILDING_SLUG trong middleware, kể cả domain
"đẹp" như 190nt: không phân biệt được với URL preview
(rentory-a1iav6i1v-ducpm103.vercel.app), mà đoán sai thì Preview chết. Một tòa
thì fallback là đủ.
Khi thêm tòa thứ hai sẽ cần domain riêng để mỗi tòa có subdomain thật
(toa2.example.com). Lúc đó thêm domain vào project rồi trỏ DNS:
CNAME <slug> cname.vercel-dns.com
Nếu apex domain nằm ở một Vercel account khác, account này phải verify quyền sở
hữu bằng bản ghi TXT _vercel do Vercel cấp — subdomain của cùng một apex chạy
ở các account khác nhau được, nhưng cùng một hostname thì chỉ một account giữ.
