Hệ thống quản lý bãi đỗ xe thông minh (Smart Parking PTIT) phát triển trên kiến trúc Full-Stack hiện đại: FastAPI (/api/v1) + WebSocket thời gian thực, giao diện React 19 + TypeScript + Tailwind CSS v4, và cơ sở dữ liệu quan hệ dbptit (16 bảng trên TiDB Cloud / MySQL 8 với migration có phiên bản và khóa giao dịch đồng thời SELECT ... FOR UPDATE).
Phiên bản v2.1.0 tách rõ tầng nghiệp vụ domain, bổ sung xác thực RBAC (ADMIN / ACCOUNTANT / OPERATOR) kèm refresh token rotation, đổi mật khẩu trực tiếp trên giao diện, đối soát ca trực thu ngân, nhật ký kiểm toán nguyên tử, mã thanh toán VietQR chuẩn EMVCo/NAPAS, in phiếu nhiệt 80mm, kiểm thử tự động đa tầng (pytest + vitest) và GitHub Actions CI.
- Cổng Vào / Ra (Gate POS): Check-in / check-out nguyên tử theo thứ tự khóa chống deadlock, phím tắt vận hành (
F2,F3//,1–3,Enter,Esc), mã QR chuyển khoản chuẩn EMVCo/NAPAS VietQR, xử lý mất thẻ (kèm cấp đổi thẻ cho vé tháng), chuyển vị trí đỗ và in phiếu/biên lai 80mm qua trình duyệt. - Tổng quan & Sơ đồ bãi trực tiếp: KPI theo thời gian thực (đồng bộ qua WebSocket xác thực bằng single-use ticket), thanh công suất bãi/khu vực, lưới vị trí lọc tại SQL, bật/tắt bảo trì và công cụ đối soát giải phóng ô đỗ & thẻ RFID mồ côi.
- Vé tháng & Bảng giá: Đăng ký, gia hạn nhiều tháng, đổi xe/thẻ, hủy trước hạn và quản lý bảng giá với kiểm tra trùng vé/thẻ trong transaction.
- Giao dịch & Ca trực thu ngân: Tra cứu lịch sử giao dịch có phân trang và lọc từ khóa trực tiếp tại SQL, xuất CSV phía máy chủ, mở/chốt ca bàn giao quỹ tiền mặt – chuyển khoản – hoàn tiền.
- Phân tích Doanh thu (Recharts): Biểu đồ doanh thu & lưu lượng theo ngày (múi giờ Việt Nam UTC+7), cơ cấu theo loại phương tiện và theo bãi đỗ (gộp đầy đủ cả lượt ngày và đăng ký/gia hạn vé tháng).
- Quản trị RBAC & Kiểm toán: Quản lý tài khoản đăng nhập (thu hồi phiên tức thì qua
token_version, chặn khóa ADMIN cuối cùng), danh bạ nhân sự/khách hàng/phương tiện (ẩn PII đối vớiOPERATOR), kho thẻ RFID, hạ tầng bãi/khu và nhật kýaudit_logsghi kèm IP trong cùng transaction.
SmartParkingDemo/
├── .github/workflows/ci.yml # CI tự động: ruff, mypy, pytest, oxlint, tsc, vitest, vite build
├── pyproject.toml # Cấu hình đóng gói, pytest, coverage, ruff, mypy
├── .env.example # Mẫu biến môi trường (TIDB_*, AUTH_SECRET_KEY, VIETQR_*, CORS_*)
├── Dump20261118.sql # Lược đồ nền 13 bảng & dữ liệu mẫu dbptit
├── src/
│ ├── core/ # Settings (pydantic-settings), Exceptions, JSON Logging
│ ├── models/ # Canonical Pydantic v2 entities (16 bảng) & response DTOs
│ ├── services/
│ │ ├── db_service.py # Connection pool an toàn, UTC +00:00, TiDB conflict retry
│ │ ├── migration_service.py # Runner migration có phiên bản (schema_migrations + GET_LOCK)
│ │ ├── auth_service.py # PBKDF2 600k, JWT HS256, Refresh rotation, WS tickets
│ │ ├── parking_service.py # Facade tương thích ngược
│ │ └── domain/ # 6 domain service: gate, infra, pass, billing, directory, analytics
│ ├── api/
│ │ ├── main.py # FastAPI app factory, error envelopes, SPA fallback
│ │ ├── deps.py # DI, RBAC, lot scoping
│ │ ├── middleware.py # Request-ID, Security Headers, Sliding-window Rate Limiter
│ │ ├── ws.py # WebSocket xác thực ticket, broadcast song song, heartbeat
│ │ └── v1/routers/ # 8 module router REST /api/v1/*
├── frontend/ # React 19 + TypeScript (strict) + Vite 8 + Tailwind v4 SPA
│ └── src/
│ ├── context/ # AuthContext, ToastContext, ThemeContext (Dark Mode)
│ ├── hooks/ # useLiveSocket (ticket auth + targeted React Query invalidation)
│ ├── lib/ # API client (refresh interceptor), VietQR EMVCo TLV, CSV
│ ├── components/ # UI primitives (Modal, ConfirmDialog, Pagination) & Gate/Admin modules
│ ├── pages/ # 6 trang nghiệp vụ lazy-loaded + LoginPage
│ └── test/ # Bộ kiểm thử Vitest + React Testing Library
├── tests/ # Bộ kiểm thử Pytest (Unit, Security, RBAC, WebSocket)
└── docs/ # Tài liệu kỹ thuật, hướng dẫn cài đặt & sử dụng (user-guide.md)
Xem thêm hướng dẫn thao tác chi tiết theo từng phân hệ và vai trò tại docs/user-guide.md và hướng dẫn cài đặt đầy đủ tại docs/setup-guide.md.
- Cấu hình môi trường: Sao chép
.env.examplethành.envvà điền thông tin TiDB Cloud / MySQL cùngAUTH_SECRET_KEY. - Cài đặt và chạy Backend FastAPI:
Tài liệu Swagger OpenAPI tại
python -m venv .venv .\.venv\Scripts\pip.exe install -r requirements-dev.txt .\.venv\Scripts\uvicorn.exe src.api.main:app --reload --port 8000
http://127.0.0.1:8000/docs(tài khoản dev mặc định sau seed:admin/thungan/baove— mật khẩu123456). - Cài đặt và chạy Frontend SPA:
Truy cập
Set-Location frontend npm install npm run devhttp://localhost:5173(Vite tự proxy/api,/ws,/healthvề cổng8000), hoặc chạynpm run buildđể FastAPI phục vụ trực tiếp bản build tạihttp://127.0.0.1:8000.
# Backend lint, typecheck & pytest + coverage
.\.venv\Scripts\python.exe -m ruff check src tests
.\.venv\Scripts\python.exe -m mypy src
.\.venv\Scripts\python.exe -m pytest tests --cov=src -v
# Frontend lint, strict typecheck, Vitest & production build
Set-Location frontend
npm run lint
npm run typecheck
npm run test
npm run build- Nguyễn Hoàng Tùng —
B24DCCE284(Trưởng nhóm) - Nguyễn Bá Minh Đức —
B24DCCE053 - Trần Anh Tú —
B24DCCE277 - Bùi Minh Khang —
B24DCCE137