Quản Lý Chi Tiêu Chung

Ứng dụng web (cài được ra màn hình chính điện thoại) để hai người ghi và chia chi tiêu chung, kèm sổ chi tiêu cá nhân.

• Sổ chung: mỗi cặp tài khoản liên kết có một sổ riêng. Ghi khoản chi theo danh mục, ai trả, mua giùm; tự tính ai cần trả ai bao nhiêu; đánh dấu đã trả (từng khoản hoặc nhiều khoản một lúc); lịch sử sửa từng khoản.
• Cá nhân: chi tiêu riêng theo danh mục, ngân sách tháng, tổng chi thực tế (gồm cả phần của mình trong sổ chung).
• Thống kê: chi chung theo tháng, theo danh mục, ai đã chi bao nhiêu.
• Tự động nhập (Android): MacroDroid chuyển tiếp thông báo của app ngân hàng, MoMo về /api/import/notify; giao dịch nằm ở Chờ xác nhận để xếp vào Cá nhân hay Sổ chung. Cài ở Liên kết → Tự động nhập.
• Đăng nhập bằng Google. Liên kết với người khác bằng lời mời qua email.

Next.js 16 (App Router) · React 19 · Prisma 7 · PostgreSQL (Neon). Triển khai trên Vercel: push lên main là tự build (prisma generate && prisma db push && next build) và lên production.

Chạy ở máy

Cần Node 22+ và Docker Desktop.

npm install
npm run db:up      # Postgres trong Docker, cổng 5544 (compose.yaml)
npm run db:push    # tạo bảng theo prisma/schema.prisma
npm run db:seed    # dữ liệu mẫu: 3 người dùng, 2 sổ chung, ~6 tháng chi tiêu — XOÁ SẠCH dữ liệu cũ trong database ở máy
npm run dev        # http://localhost:4000
npm test           # bộ thử (Vitest): đọc thông báo ngân hàng / MoMo, đoán danh mục

Đổi gói thì dùng npm 10: npx npm@10 install <gói>. npm 11 (tới 11.6) làm rơi các gói biên dịch theo nền tảng khỏi package-lock.json (binding của rolldown cho máy khác, lightningcss-* riêng của vite) — kể cả npm install không đổi gì. Chỉ npm ci thì npm nào cũng được. optionalDependencies ghi sẵn @rolldown/binding-* cho Windows và Linux để lỡ dùng npm 11 thì Vitest vẫn chạy; nâng Vitest thì nâng các gói này cùng phiên bản rolldown.

db:push, db:seed, dev:login đọc .env.local; seed và dev:login từ chối chạy nếu DATABASE_URL không phải localhost.

Prisma 7: client sinh vào src/generated/prisma (không commit, tạo lại ở postinstall) — import từ @/generated/prisma/client, không phải @prisma/client. Kết nối qua @prisma/adapter-pg (src/lib/db.ts); chuỗi kết nối cho CLI nằm ở prisma.config.ts. Prisma 7 không tự đọc .env và db push không tự generate — các lệnh npm run db:* đã lo việc đó. Script ở scripts/ import client TypeScript nên chạy qua tsx.

.env.local

Next.js ưu tiên file này hơn .env. Không commit (.gitignore đã chặn .env*).

DATABASE_URL="postgresql://postgres:postgres@localhost:5544/chi_tieu"
AUTH_SECRET="<chuỗi ngẫu nhiên bất kỳ>"   # node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

Muốn đăng nhập Google thật ở máy thì thêm GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET (đặt trong .env hay .env.local đều được).

Đăng nhập ở máy không cần Google

npm run dev:login                               # Quốc Thiệu ([email protected])
npm run dev:login -- [email protected]    # người còn lại trong sổ

Lệnh in ra một dòng JavaScript. Mở http://localhost:4000/login, F12 → Console, dán dòng đó là vào app. Cookie ký bằng AUTH_SECRET của .env.local nên không dùng được trên production; app không có đường đăng nhập nào thêm.

Tắt database: docker compose stop (dữ liệu giữ trong volume chi-tieu-db).

Biến môi trường trên Vercel

Biến	Dùng cho
DATABASE_URL	Postgres production
AUTH_SECRET	ký cookie đăng nhập
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET	đăng nhập Google
APP_URL (tùy chọn)	origin cố định cho địa chỉ callback Google, khi chạy sau proxy làm sai origin

Đổi schema: chỉ thêm cột/bảng có giá trị mặc định hoặc cho phép null, và không thêm @unique vào bảng đã có dữ liệu (dùng @@index) — prisma db push chạy thẳng lên database thật mỗi lần deploy, gặp cảnh báo mất dữ liệu là hỏng build.

Tài liệu nội bộ

• docs/_internal/viec-con-treo.md — việc chưa làm
• docs/_internal/nhat-ky-lam-viec.md — nhật ký làm việc
• AGENTS.md — quy ước mở / đóng phiên cho Claude