Tiêu Chuẩn Code & Hướng Dẫn

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

---

1. Nguyên Tắc Dự Án

YAGNI - You Aren't Gonna Need It Không xây dựng tính năng trước khi cần. Tránh over-engineering.

KISS - Keep It Simple, Stupid Ưu tiên giải pháp đơn giản hơn các abstraction phức tạp.

DRY - Don't Repeat Yourself Trích xuất logic chung vào helper, service hoặc tiện ích.

---

2. Quy Ước Đặt Tên

File & Thư Mục

Ngữ Cảnh	Mẫu	Ví Dụ
TypeScript/JavaScript	kebab-case	country-scope.guard.ts, api-client.ts
Thư mục	kebab-case	ota-accounts/, room-mappings/
File test	name.spec.ts	auth.service.spec.ts
DTO	PascalCase + hậu tố Dto	CreatePropertyDto, ListBookingsDto
Interface	PascalCase + tiền tố I tùy chọn	OtaAdapter hoặc IOtaAdapter
Class	PascalCase	AuthService, PropertyController
Enum	PascalCase	UserRole, AlertSeverity
Hằng số	UPPER_SNAKE_CASE	ALLOWED_COUNTRIES, JWT_EXPIRY
Bảng database	snake_case (Prisma)	ota_accounts, refresh_tokens
Cột database	snake_case	password_hash, is_active

Hàm & Phương Thức

// ✓ Tốt: Động từ + danh từ, mô tả rõ ràng
async fetchBookingsFromOta(otaType: string): Promise<Booking[]>
function assertPropertyAccess(prisma, propertyId, countryScope?): Property
function validateSortByField(field: string, allowedFields: string[]): void

// ✗ Xấu: Viết tắt, mục đích không rõ
async getB(type: string): Promise<any>
function checkProp(id: string): void

Biến

// ✓ Tốt: Mô tả, không viết tắt không cần thiết
const refreshTokenExpiry = '7d';
const MAX_RETRY_ATTEMPTS = 3;
let availableRooms = totalRooms - bookedRooms;

// ✗ Xấu: Một chữ cái, viết tắt
const rt = '7d';
const max_retries = 3;
let avail = total - booked;

---

3. Tổ Chức File & Giới Hạn Kích Thước

File Code: Tối Đa 200 Dòng

Mục tiêu: Giữ file tập trung và dễ điều hướng.

Chiến lược chia tách:

• 200-400 dòng: Cân nhắc chia thành 2-3 file tập trung
• 400+ dòng: PHẢI chia tách ngay lập tức

Ví dụ chia tách service lớn:

ota-accounts/
├── ota-accounts.service.ts         # CRUD (150 dòng)
├── ota-accounts.controller.ts      # Endpoint
├── ota-account-discovery.service.ts # Logic discovery & import (120 dòng)
├── ota-credential.helper.ts        # Mã hóa/giải mã (80 dòng)
├── dto/
│   ├── create-ota-account.dto.ts
│   └── list-ota-accounts.dto.ts
└── ota-accounts.module.ts

File Tài Liệu: Tối Đa 800 Dòng

Mục tiêu: Giữ tài liệu dễ bảo trì và đọc.

Chiến lược chia tách:

• 800-1200 dòng: Tạo thư mục chủ đề với index + phần
• 1200+ dòng: PHẢI chia tách

---

4. Tài Liệu Liên Quan

Tài Liệu	Nội Dung
code-standards-backend.md	Mẫu NestJS, bảo mật, xử lý lỗi, DB/Prisma, testing
code-standards-frontend.md	Mẫu Next.js/React, API client, Git commit, hiệu suất
system-architecture.md	Sơ đồ kiến trúc và luồng
codebase-summary.md	Cấu trúc dự án và phụ thuộc
API_SPEC.md	Tham khảo REST API endpoint
DB_DESIGN.md	Schema database và index