Cấu trúc Source Code

Tech Stack đề xuất

Frontend

React 18 + Vite

TypeScript, TailwindCSS, React Query, React Router v6

Backend

Node.js + Express

TypeScript, Prisma ORM, JWT Auth, Zod validation

Database

PostgreSQL 15

Prisma migrations, Redis (cache & queue)

Infrastructure

Docker Compose

Dev local, CI/CD GitHub Actions, deploy VPS / cloud

Cây thư mục

📁 salon-system/ — monorepo

salon-system/ ├── apps/ │ ├── api/ # Backend Express API │ │ ├── src/ │ │ │ ├── modules/ # Feature modules │ │ │ │ ├── auth/ # Xác thực, JWT │ │ │ │ ├── appointments/ # Lịch hẹn │ │ │ │ ├── customers/ # Hồ sơ khách hàng │ │ │ │ ├── services/ # Danh mục dịch vụ │ │ │ │ ├── staff/ # Nhân viên & ca làm │ │ │ │ ├── pos/ # Thanh toán / hóa đơn │ │ │ │ ├── inventory/ # Quản lý hàng hóa │ │ │ │ └── reports/ # Báo cáo doanh thu │ │ │ ├── common/ # Shared utilities │ │ │ │ ├── middleware/ # auth, error, logger │ │ │ │ ├── decorators/ │ │ │ │ └── utils/ │ │ │ ├── prisma/ # Schema & migrations │ │ │ │ ├── schema.prisma │ │ │ │ └── migrations/ │ │ │ └── app.ts # Entry point │ │ ├── Dockerfile │ │ ├── package.json │ │ └── tsconfig.json │ │ │ └── web/ # Frontend React │ ├── src/ │ │ ├── pages/ # Route-level pages │ │ │ ├── dashboard/ │ │ │ ├── appointments/ │ │ │ ├── customers/ │ │ │ ├── staff/ │ │ │ ├── pos/ │ │ │ ├── inventory/ │ │ │ └── reports/ │ │ ├── components/ # Shared UI components │ │ │ ├── ui/ # Button, Input, Modal… │ │ │ ├── layout/ # Sidebar, Header… │ │ │ └── calendar/ # Booking calendar widget │ │ ├── hooks/ # Custom React hooks │ │ ├── services/ # API client (axios) │ │ ├── store/ # Zustand global state │ │ ├── types/ # TS type definitions │ │ └── main.tsx │ ├── Dockerfile │ ├── vite.config.ts │ └── package.json │ ├── packages/ # Shared across apps │ ├── shared-types/ # DTOs, enums dùng chung │ └── ui-kit/ # (tuỳ chọn) Component lib │ ├── infra/ # Infrastructure as code │ ├── docker-compose.yml │ ├── docker-compose.prod.yml │ └── nginx/ │ ├── .github/ │ └── workflows/ │ ├── ci.yml # Lint + test │ └── deploy.yml │ ├── .xp-docs/ # Tài liệu dự án (nội bộ) ├── .env.example ├── package.json # Monorepo root (pnpm workspaces) ├── pnpm-workspace.yaml └── turbo.json # Turborepo build pipeline

Chi tiết các Module Backend

Module	Layer	Chức năng chính	Files trong module
auth/	BE	Đăng nhập, phân quyền RBAC (Admin / Staff / Receptionist)	auth.controller.ts · auth.service.ts · auth.router.ts · jwt.strategy.ts
appointments/	BE	CRUD lịch hẹn, kiểm tra conflict, gửi reminder	appointment.controller.ts · appointment.service.ts · appointment.router.ts · appointment.schema.ts
customers/	BE	Hồ sơ khách, lịch sử dịch vụ, ghi chú, tích điểm	customer.controller.ts · customer.service.ts · customer.router.ts
services/	BE	Danh mục dịch vụ, giá, thời lượng, nhân viên thực hiện	service.controller.ts · service.service.ts · service.router.ts
staff/	BE	Hồ sơ nhân viên, ca làm việc, kỹ năng, doanh số	staff.controller.ts · staff.service.ts · shift.service.ts · staff.router.ts
pos/	BE	Tính tiền, áp dụng voucher, xuất hóa đơn, VNPay / tiền mặt	pos.controller.ts · invoice.service.ts · payment.service.ts · pos.router.ts
inventory/	BE	Nhập / xuất kho, cảnh báo tồn kho thấp	inventory.controller.ts · stock.service.ts · inventory.router.ts
reports/	BE	Doanh thu theo ngày/tuần/tháng, hiệu suất nhân viên, top dịch vụ	report.controller.ts · revenue.service.ts · report.router.ts

Sơ đồ bảng Database (tổng quan)

🗄 PostgreSQL — các entity chính

User (id, name, email, passwordHash, role, createdAt) Customer (id, name, phone, email, notes, points, createdAt) Staff (id, userId→User, skills[], hireDate) Service (id, name, category, price, durationMin, staffIds[]) Appointment (id, customerId→Customer, staffId→Staff, serviceId→Service, startAt, endAt, status, notes) Invoice (id, appointmentId→Appointment, total, discount, paymentMethod, paidAt, items[]) Product (id, name, unit, costPrice, salePrice) StockMovement(id, productId→Product, type IN|OUT, qty, note, createdAt) Shift (id, staffId→Staff, date, startTime, endTime)

Quy ước đặt tên & coding style

Files & Folders

Tên file: kebab-case.ts
Tên class: PascalCase
Tên function/var: camelCase
Constants: UPPER_SNAKE_CASE
DB table: snake_case (Prisma map)

API Endpoints

GET /api/v1/appointments
POST /api/v1/appointments
PATCH /api/v1/appointments/:id
DELETE /api/v1/appointments/:id
Luôn wrap response: { data, meta }

Git branches

main — production
develop — integration
feat/<module>-<desc>
fix/<issue-id>-<desc>
Commit: Conventional Commits

Frontend structure

Pages = route containers (no logic)
Logic vào hooks/use*.ts
API calls qua services/api.ts
Global state: Zustand store
Server state: React Query

Ghi chú & quyết định cần xác nhận

Cần team xác nhận trước khi scaffold:
1. Tech stack: React + Express/Node.js có phù hợp không, hay dùng Next.js fullstack / NestJS?
2. Monorepo tool: Turborepo + pnpm workspaces (đề xuất) hay Nx?
3. Auth: JWT tự quản lý hay tích hợp SSO (Google, dịch vụ ngoài)?
4. Mobile: Có cần app mobile (React Native) hay chỉ web responsive?
5. Đặt lịch online: Có cần trang booking public cho khách tự đặt không?

Cấu trúc Source CodeSalon System

Files & Folders

API Endpoints

Git branches

Frontend structure

Cấu trúc Source Code
Salon System