goodgo-platform/docs/audits/TESTING_INDEX.md

# Chỉ Mục Tài Liệu Kiểm Thử

**Tạo ngày:** 2026-04-11  
**Tổng số dòng tài liệu:** 3.014  
**Tổng số tệp được phân tích:** 17 tệp nguồn chưa có kiểm thử  

---

## 📚 Các Tệp Tài Liệu

### 1. **README_TEST_COVERAGE.md** (9,1 KB)
Bắt đầu từ đây để có cái nhìn tổng quan đầy đủ và lộ trình thực hiện.

**Nội dung:**
- Tổng quan về cả 4 tệp tài liệu
- Tổ chức tệp theo mô-đun (Inquiries, Leads, Reviews)
- Mức độ ưu tiên kiểm thử (Quan trọng 🔴, Cao 🟡, Trung bình 🟢)
- Lộ trình kiểm thử 3 tuần kèm ước tính thời gian
- Các mẫu kiểm thử quan trọng cho từng loại tệp
- Các công thức then chốt cần xác minh trong kiểm thử
- Dữ liệu kiểm thử chung và câu lệnh import
- Hướng dẫn xử lý sự cố
- Hướng dẫn khởi động nhanh

**Thời gian đọc:** 5–10 phút

---

### 2. **TEST_COVERAGE_ANALYSIS.md** (55 KB)
Tài liệu tham khảo đầy đủ với tất cả 17 tệp nguồn và triển khai chi tiết.

**Nội dung:**
- Tóm tắt điều hành
- **PHẦN 1: MÔ-ĐUN INQUIRIES** (4 tệp)
  - PrismaInquiryRepository (146 dòng)
  - InquiriesController (120 dòng)
  - CreateInquiryDto (20 dòng)
  - ListInquiriesDto (20 dòng)
  
- **PHẦN 2: MÔ-ĐUN LEADS** (6 tệp)
  - PrismaLeadRepository (151 dòng)
  - LeadScore ValueObject (16 dòng)
  - LeadsController (126 dòng)
  - CreateLeadDto (35 dòng)
  - ListLeadsDto (30 dòng)
  - UpdateLeadStatusDto (14 dòng)
  
- **PHẦN 3: MÔ-ĐUN REVIEWS** (5 tệp)
  - PrismaReviewRepository (162 dòng)
  - Rating ValueObject (16 dòng)
  - ReviewsController (122 dòng)
  - CreateReviewDto (26 dòng)
  - ListReviewsDto (42 dòng)

- **PHẦN 4: MẪU KIỂM THỬ THAM KHẢO** (3 tệp kiểm thử)
  - Mẫu kiểm thử CreateInquiryHandler
  - Mẫu kiểm thử CreateLeadHandler
  - Mẫu kiểm thử ReviewsController

- Bảng tóm tắt tất cả tệp
- Các ưu tiên kiểm thử
- Mục tiêu độ bao phủ kiểm thử

**Thời gian đọc:** 30–45 phút để xem xét đầy đủ

**Cách sử dụng:**
1. Tìm tệp bạn muốn kiểm thử
2. Đọc toàn bộ phần triển khai
3. Xem mục "Key Methods to Test"
4. Kiểm tra mục "Test Scenarios"
5. Đối chiếu với các mẫu trong TEST_TEMPLATES.md

---

### 3. **TEST_COVERAGE_QUICK_REFERENCE.md** (9,1 KB)
Danh sách kiểm tra và tài liệu tra cứu nhanh.

**Nội dung:**
- Tổng quan 17 tệp kèm số dòng
- Các kịch bản kiểm thử nhanh theo loại:
  - Repositories (3 tệp) — danh sách kiểm tra + ghi chú cụ thể
  - Value Objects (2 tệp) — phạm vi xác thực
  - Controllers (2 tệp) — danh sách kiểm tra endpoint
  - DTOs (10 tệp) — quy tắc xác thực
  
- Ma trận ưu tiên kiểm thử:
  - Quan trọng: 4 mục (logic nghiệp vụ)
  - Cao: 5 mục (toàn vẹn dữ liệu)
  - Trung bình: 3 mục (xác thực/guards)

- Khuyến nghị thứ tự thực thi kiểm thử
- Mẫu thiết lập mock (4 ví dụ)
- Các công thức then chốt cần xác minh
- Tài liệu tham chiếu vị trí tệp

**Thời gian đọc:** 3–5 phút để tra cứu

**Cách sử dụng:**
1. Tìm loại tệp bạn đang kiểm thử
2. Kiểm tra danh sách kiểm tra nhanh
3. Chuyển đến mục chi tiết trong Analysis để biết thêm thông tin
4. Sao chép mẫu mock từ tệp này

---

### 4. **TEST_TEMPLATES.md** (16 KB)
Các mẫu code sẵn sàng sử dụng cho tất cả loại tệp.

**Nội dung:**
- Mẫu kiểm thử Repository
  - Thiết lập với Prisma được mock
  - Kiểm thử findById()
  - Kiểm thử save()
  - Kiểm thử findByListing() với phân trang

- Mẫu kiểm thử Value Object
  - Kiểm thử create() với giá trị hợp lệ
  - Kiểm thử giá trị biên
  - Kiểm thử giá trị không hợp lệ
  - Kiểm thử thông báo lỗi
  - Kiểm thử getters

- Mẫu kiểm thử DTO
  - Kiểm thử xác thực trường bắt buộc
  - Kiểm thử trường tùy chọn
  - Kiểm thử ràng buộc trường (email, phạm vi)
  - Kiểm thử chuyển đổi kiểu dữ liệu

- Mẫu kiểm thử Controller
  - Thiết lập với bus được mock
  - Kiểm thử điều phối lệnh (command dispatch)
  - Kiểm thử ánh xạ tham số
  - Kiểm thử xử lý null
  - Kiểm thử giá trị mặc định

- Các kiểm thử trợ giúp
  - Kiểm thử tính toán phân trang
  - Kiểm thử công thức tổng hợp
  - Kiểm thử phân trang DTO

**Thời gian đọc:** 10–15 phút trong khi viết kiểm thử

**Cách sử dụng:**
1. Sao chép mẫu phù hợp cho loại tệp của bạn
2. Dán vào tệp kiểm thử
3. Thay thế tên chung bằng tên tệp cụ thể của bạn
4. Cập nhật các import và dữ liệu kiểm thử
5. Chạy và xác minh kiểm thử vượt qua

---

## 🎯 Điều Hướng Nhanh Theo Nhiệm Vụ

### "Tôi muốn hiểu những gì cần kiểm thử"
→ Bắt đầu với **README_TEST_COVERAGE.md** (5 phút)  
→ Sau đó **TEST_COVERAGE_QUICK_REFERENCE.md** (3 phút)

### "Tôi muốn viết kiểm thử cho một tệp cụ thể"
→ Tìm tệp trong **TEST_COVERAGE_QUICK_REFERENCE.md**  
→ Đọc triển khai chi tiết trong **TEST_COVERAGE_ANALYSIS.md**  
→ Sao chép mẫu từ **TEST_TEMPLATES.md**  
→ Điều chỉnh mẫu theo tệp của bạn

### "Tôi muốn hiểu một thành phần cụ thể"
→ Tra cứu tệp trong **TEST_COVERAGE_ANALYSIS.md**  
→ Tìm mục "Key Methods to Test"  
→ Tìm mục "Test Scenarios"  
→ Kiểm tra **TEST_TEMPLATES.md** để xem mẫu

### "Tôi muốn công thức và phép tính"
→ **TEST_COVERAGE_QUICK_REFERENCE.md** — "Key Formulas to Verify"  
→ **TEST_TEMPLATES.md** — Aggregation Test Helper  
→ **TEST_COVERAGE_ANALYSIS.md** — Mục repo cụ thể

### "Tôi cần ví dụ thiết lập mock"
→ **TEST_COVERAGE_QUICK_REFERENCE.md** — Mock Setup Template  
→ **TEST_TEMPLATES.md** — Phần đầu tiên cho mỗi loại

---

## 📋 17 Tệp Tổng Quan

### Inquiries (4 tệp)
| Tệp | Loại | Kiểm thử chính |
|-----|------|----------------|
| prisma-inquiry.repository.ts | Repository | Phân trang, quan hệ |
| inquiries.controller.ts | Controller | 4 endpoint, guards |
| create-inquiry.dto.ts | DTO | 3 xác thực |
| list-inquiries.dto.ts | DTO | Xác thực phân trang |

### Leads (6 tệp)
| Tệp | Loại | Kiểm thử chính |
|-----|------|----------------|
| prisma-lead.repository.ts | Repository | Tổng hợp thống kê |
| lead-score.vo.ts | ValueObject | Phạm vi 0–100 |
| leads.controller.ts | Controller | 5 endpoint, role guard |
| create-lead.dto.ts | DTO | 6 xác thực |
| list-leads.dto.ts | DTO | Enum trạng thái |
| update-lead-status.dto.ts | DTO | Xác thực trạng thái |

### Reviews (5 tệp)
| Tệp | Loại | Kiểm thử chính |
|-----|------|----------------|
| prisma-review.repository.ts | Repository | Thống kê phân phối |
| rating.vo.ts | ValueObject | Chỉ số nguyên 1–5 |
| reviews.controller.ts | Controller | 5 endpoint, xác thực hỗn hợp |
| create-review.dto.ts | DTO | 4 xác thực |
| list-reviews.dto.ts | DTO | 2 DTO, phân trang |

---

## ⏱️ Ước Tính Thời Gian

### Theo Loại Tệp
- **Value Objects** (2 tệp): 30–45 phút
- **DTOs** (10 tệp): 2–3 giờ (sử dụng mẫu)
- **Controllers** (2 tệp): 1,5–2 giờ
- **Repositories** (3 tệp): 2,5–3,5 giờ

### Tổng cộng: 9–14 giờ

### Thứ Tự Khuyến Nghị
1. Value Objects (nhanh nhất, xây dựng sự tự tin)
2. DTOs (nhanh, lặp lại nhiều tệp)
3. Controllers (độ phức tạp trung bình)
4. Repositories (phức tạp nhất, nên làm cuối cùng)

---

## 🔍 Mỗi Tệp Kiểm Thử Những Gì

### Value Objects
- **LeadScore.vo**
  - ✓ Phạm vi hợp lệ 0–100
  - ✓ Từ chối giá trị không hợp lệ
  - ✓ Thông báo lỗi bằng tiếng Việt
  
- **Rating.vo**
  - ✓ Chỉ số nguyên hợp lệ 1–5
  - ✓ Từ chối 0, 6, số thập phân
  - ✓ Thông báo lỗi bằng tiếng Việt

### DTOs
- **Pagination DTOs** (4 tệp)
  - ✓ Xác thực page/limit
  - ✓ Chuyển đổi kiểu dữ liệu
  - ✓ Giá trị mặc định
  
- **Status DTOs** (2 tệp)
  - ✓ Xác thực enum
  - ✓ Chỉ chấp nhận trạng thái hợp lệ
  
- **Create DTOs** (4 tệp)
  - ✓ Xác thực trường bắt buộc
  - ✓ Xử lý trường tùy chọn
  - ✓ Ràng buộc trường (email, độ dài, phạm vi)

### Controllers
- **InquiriesController**
  - ✓ 4 endpoint với điều phối chính xác
  - ✓ Xác thực JWT
  - ✓ Guards dựa trên vai trò (AGENT)
  
- **LeadsController**
  - ✓ 5 endpoint với điều phối chính xác
  - ✓ Role guard ở cấp class (AGENT)
  - ✓ Xử lý trường tùy chọn
  
- **ReviewsController**
  - ✓ 5 endpoint với điều phối chính xác
  - ✓ Xác thực hỗn hợp (một số endpoint công khai)
  - ✓ Xác minh quyền sở hữu của người dùng

### Repositories
- **PrismaInquiryRepository**
  - ✓ CRUD: findById, save, markAsRead
  - ✓ Phân trang: findByListing, findByAgent
  - ✓ Tổng hợp: countUnreadByAgent
  - ✓ Ánh xạ dữ liệu: toDomain
  
- **PrismaLeadRepository**
  - ✓ CRUD: findById, save, update, delete
  - ✓ Phân trang với bộ lọc trạng thái tùy chọn
  - ✓ Tổng hợp: getStatsByAgent (tỷ lệ chuyển đổi, điểm trung bình)
  - ✓ Ánh xạ dữ liệu kể cả LeadScore VO
  
- **PrismaReviewRepository**
  - ✓ CRUD: findById, findByUserAndTarget, save, delete
  - ✓ Phân trang: findByTarget, findByUserId
  - ✓ Tổng hợp: getStats (phân phối, điểm đánh giá trung bình)
  - ✓ Ánh xạ dữ liệu kể cả Rating VO

---

## 📖 Ví Dụ Tham Khảo

### Mẫu Kiểm Thử Đang Hoạt Động
Ba tệp kiểm thử đầy đủ được đưa vào làm tài liệu tham khảo:

1. **create-inquiry.handler.spec.ts** (99 dòng)
   - Mock repository, EventBus, Prisma
   - Kiểm thử đường đi thành công (happy path)
   - Kiểm thử xử lý lỗi
   - Xác minh phát sự kiện

2. **create-lead.handler.spec.ts** (121 dòng)
   - Mẫu tương tự như create-inquiry
   - Kiểm thử xử lý trường tùy chọn
   - Kiểm thử xác thực ValueObject

3. **reviews.controller.spec.ts** (135 dòng)
   - Kiểm thử endpoint controller
   - Xác minh điều phối bus
   - Xử lý tham số truy vấn
   - Áp dụng giá trị mặc định

---

## ✅ Mẫu Danh Sách Kiểm Tra Kiểm Thử

```
Module: ___________________
File: _____________________

Imports:
- [ ] Framework kiểm thử đã được import
- [ ] Các class đã được import
- [ ] Mocks đã sẵn sàng

Setup:
- [ ] beforeEach tạo mocks mới
- [ ] Các dependency đã được inject
- [ ] Dữ liệu kiểm thử đã được chuẩn bị

Happy Path:
- [ ] Kiểm thử chức năng cơ bản
- [ ] Xác minh giá trị trả về
- [ ] Các phương thức được gọi đúng cách

Edge Cases:
- [ ] Xử lý Null/undefined
- [ ] Xử lý kết quả rỗng
- [ ] Giá trị biên

Error Cases:
- [ ] Từ chối đầu vào không hợp lệ
- [ ] Xác minh thông báo lỗi
- [ ] Xác thực guard

Cleanup:
- [ ] Mocks được làm sạch sau mỗi kiểm thử
- [ ] Không có sự phụ thuộc giữa các kiểm thử
```

---

## 💡 Mẹo Hay

1. **Bắt đầu nhỏ**: Bắt đầu với Value Objects (đơn giản nhất)
2. **Sao chép-dán**: Sử dụng mẫu, đừng viết từ đầu
3. **Kiểm thử sớm**: Chạy kiểm thử ngay khi bạn viết
4. **Kỹ càng**: Bao gồm cả đường đi thành công lẫn trường hợp lỗi
5. **Dùng lại**: Tham khảo các kiểm thử hiện có trong codebase
6. **Xác minh công thức**: Kiểm thử kỹ các phép tính số học
7. **Mock tất cả**: Không truy cập cơ sở dữ liệu thực trong kiểm thử
8. **Kiểm thử Guards**: Đừng quên xác thực/phân quyền

---

## 🆘 Cần Giúp Đỡ?

1. **Câu hỏi về cấu hình?** → Xem README_TEST_COVERAGE.md
2. **Cần mẫu?** → Xem TEST_TEMPLATES.md
3. **Chi tiết triển khai?** → Xem TEST_COVERAGE_ANALYSIS.md
4. **Tra cứu nhanh?** → Xem TEST_COVERAGE_QUICK_REFERENCE.md
5. **Ví dụ hiện có?** → Kiểm tra các thư mục `__tests__` của mô-đun

---

**Phiên bản tài liệu:** 1.0  
**Cập nhật lần cuối:** 2026-04-11  
**Tổng tài liệu:** 3.014 dòng trong 4 tệp  
**Độ bao phủ:** 17 tệp nguồn chưa có kiểm thử (các mô-đun Inquiries, Leads, Reviews)