Tóm Tắt Mã Nguồn


Dự Án	PTX Channel Manager (ptx-cm)
Phiên Bản	2.0.0
Cập Nhật	2026-02-20

1. Đồ Thị Phụ Thuộc Monorepo

2. Cấu Trúc Thư Mục & Thống Kê

Thư Mục	Mục Đích	LOC	Files
apps/api	NestJS Backend	~12,000	85 TS
apps/web	Next.js Frontend	~8,500	95 TSX
packages/database	Prisma + migration	~600	8
packages/types	Kiểu dữ liệu/enum dùng chung	~400	4
packages/config	Cấu hình ESLint/TS	~100	3
docs	Tài liệu	~3,000	9 MD
Tổng	Tất cả mã nguồn	~25,000	200+

3. Bản Đồ Module Backend

15 Feature Module (apps/api/src/modules)

Xác Thực & User:

auth - JWT, đăng nhập, refresh, đặt lại mật khẩu, giới hạn tốc độ
users - CRUD user, cài đặt tài khoản (locale, quốc gia, dateFormat)
roles - Định nghĩa vai trò, bitmask quyền hạn (14 module × 4 hành động)
activity-logs - Ghi log HTTP request, audit trail qua middleware

Inventory & Vận Hành:

properties - CRUD property, gán timezone/tiền tệ
room-types - Inventory phòng, giá cơ bản theo property
room-mappings - Mapping OTA ↔ room type nội bộ
suppliers - Quản lý supplier/chủ phòng
supplier-room-allocations - Phân bổ supplier ↔ room M:N

Tích Hợp OTA:

ota-accounts - Credential mã hóa (AES-256-GCM)
ota-connections - Liên kết property ↔ tài khoản OTA
ota-adapters - Factory + 4 adapter (Booking, Agoda, Traveloka, Expedia)

Booking & Đồng Bộ:

bookings - CRUD booking, loại trùng upsertFromOta
booking-status - Định nghĩa trạng thái cấu hình
sync-engine - Lịch polling, theo dõi job, OTA polling/availability sync processor
sync-jobs - Theo dõi job bất đồng bộ với trạng thái

Hỗ Trợ:

alerts - Phát hiện overbooking & thông báo
dashboard - KPI tổng hợp (lấp đầy, doanh thu, cảnh báo, trạng thái đồng bộ)
settings - Cài đặt ứng dụng (interval đồng bộ, bật/tắt thông báo)
notifications - Dịch vụ email (Resend API + Mailpit trong dev)
countries - Dữ liệu tham khảo lọc quốc gia
health - Liveness probe

Mẫu Chung (apps/api/src/common)

Guard (áp dụng toàn cục, bỏ qua qua @Public):

JwtAuthGuard - Xác thực chữ ký JWT & hạn sử dụng
PermissionsGuard - Kiểm tra bitmask module:action
CountryScopeGuard - Inject bộ lọc quốc gia từ context user
ThrottlerGuard - Giới hạn tốc độ (5/phút đăng nhập, 10/phút refresh)

Decorator:

@Public() - Bỏ qua JwtAuthGuard
@RequirePermission(module, action) - Kiểm tra quyền hạn bitwise
@CountryScope() - Inject countryScope từ user.country

4. Bản Đồ Route Frontend

Route	Layer	Auth	Mục Đích
`/login`, `/forgot-password`, `/reset-password`	(auth)	Công khai	Luồng xác thực
`/dashboard`, `/bookings`, `/properties`, `/ota-accounts`, `/alerts`, `/sync-jobs`, `/suppliers`, `/master-data`, `/logs`, `/profile`, `/settings`	(main)	Bắt buộc	Trang bảo vệ

Chuỗi Context Provider

AuthProvider → CountryProvider → ReferenceDataProvider → ThemeProvider → I18nProvider → ActivityTrackerProvider

Component Chính

data-table.tsx - TanStack Table wrapper
booking-history.tsx - Timeline trạng thái + metadata
status-transition-dialog.tsx - UI state machine
ota-connections-tab.tsx - Quản lý room mapping
supplier-allocation-manager.tsx - Trình soạn phân bổ
workflow-mermaid-preview.tsx - Trực quan hóa trạng thái booking

5. File Quan Trọng

File	Mục Đích
`packages/database/prisma/schema.prisma`	Nguồn dữ liệu chính cho DB schema
`packages/types/src/enums.ts`	Enum OTA, vai trò, hằng số trạng thái
`docs/API_SPEC.md`	Hợp đồng endpoint backend
`docs/DB_DESIGN.md`	Lý do thiết kế database & ER

6. Tham Khảo Chéo

Để biết thông tin kỹ thuật chi tiết, xem:
Kiến Trúc Hệ Thống — Tech stack, design pattern, luồng sync engine, luồng xác thực, ER diagram
Thiết Kế Database — Schema đầy đủ với DDL, index, constraint

Cập Nhật: 2026-02-20 | Trạng Thái: Đang hoạt động

Tóm Tắt Mã Nguồn ​

1. Đồ Thị Phụ Thuộc Monorepo ​

2. Cấu Trúc Thư Mục & Thống Kê ​

3. Bản Đồ Module Backend ​

15 Feature Module (apps/api/src/modules) ​

Mẫu Chung (apps/api/src/common) ​

4. Bản Đồ Route Frontend ​

Chuỗi Context Provider ​

Component Chính ​

5. File Quan Trọng ​

6. Tham Khảo Chéo ​