goodgo-platform/docs/audits/TEST_FILES_INDEX.md

📑 Mục lục: Phân tích Tệp Kiểm thử Còn thiếu của Module Admin

📌 Tổng quan Tài liệu

Ba tài liệu toàn diện đã được tạo ra để hướng dẫn bạn viết kiểm thử cho 3 tệp handler/listener còn thiếu trong module admin:

1. ADMIN_MODULE_TEST_ANALYSIS.md (25 KB)

Mục đích: Tài liệu tham khảo đầy đủ với toàn bộ mã nguồn và các mẫu

Nội dung:

• ✅ Toàn bộ mã nguồn của 3 tệp chưa được kiểm thử
• ✅ Tất cả các lớp command/query liên quan
• ✅ Các tệp kiểm thử hoạt động hoàn chỉnh để tham khảo (approve-listing, ban-user, user-banned)
• ✅ Định nghĩa interface chi tiết
• ✅ Cấu trúc tệp đầy đủ của module admin
• ✅ Khuyến nghị kiểm thử từng bước
• ✅ Danh sách kiểm tra viết kiểm thử

Phù hợp nhất để: Đọc qua toàn bộ ngữ cảnh và các ví dụ

---

2. DETAILED_HANDLER_COMPARISON.md (15 KB)

Mục đích: So sánh song song và hướng dẫn đọc mã kiểm thử

Nội dung:

• ✅ So sánh cấu trúc tệp
• ✅ So sánh mã handler song song (approve vs reject)
• ✅ Hướng dẫn đọc mã kiểm thử có chú thích
• ✅ Cách điều chỉnh các kiểm thử hiện có cho handler mới
• ✅ Giải thích các mẫu query handler
• ✅ Bảng so sánh listener
• ✅ Ví dụ kiểm thử hoàn chỉnh sẵn sàng để điều chỉnh

Phù hợp nhất để: Hiểu các mẫu và điều chỉnh mã kiểm thử

---

3. QUICK_REFERENCE.md (3 KB)

Mục đích: Tra cứu nhanh khi đang viết kiểm thử

Nội dung:

• ✅ 3 tệp tổng quan với tất cả thông tin chi tiết quan trọng
• ✅ Vị trí và mẫu cần tuân theo cho từng tệp
• ✅ Mẫu thiết lập mock
• ✅ Danh sách kiểm tra độ phủ kiểm thử
• ✅ Tổng quan cấp cao

Phù hợp nhất để: Tra cứu nhanh khi đang tích cực viết mã kiểm thử

---

🎯 3 Tệp Kiểm thử Còn thiếu

1. reject-listing.handler.spec.ts

Loại: Kiểm thử Command Handler Vị trí: apps/api/src/modules/admin/application/__tests__/ Mẫu tham khảo: approve-listing.handler.spec.ts Độ phức tạp: Trung bình

Các điểm kiểm thử quan trọng:

• Luồng thành công: Từ chối thành công danh sách ở trạng thái PENDING_REVIEW
• Lỗi: NotFoundException khi danh sách không tồn tại
• Lỗi: ValidationException khi trạng thái danh sách không hợp lệ

---

2. get-revenue-stats.handler.spec.ts

Loại: Kiểm thử Query Handler Vị trí: apps/api/src/modules/admin/application/__tests__/ Mẫu tham khảo: get-dashboard-stats.handler.spec.ts Độ phức tạp: Thấp

Các điểm kiểm thử quan trọng:

• Query trả về RevenueStatsItem[] từ repository
• Xác minh các tham số được truyền vào (startDate, endDate, groupBy)
• Hỗ trợ cả hai giá trị groupBy là 'day' và 'month'

---

3. user-deactivated.listener.spec.ts

Loại: Kiểm thử Event Listener Vị trí: apps/api/src/modules/admin/application/__tests__/ Mẫu tham khảo: user-banned.listener.spec.ts Độ phức tạp: Trung bình

Các điểm kiểm thử quan trọng:

• Hết hạn các danh sách ACTIVE và PENDING_REVIEW của người dùng bị vô hiệu hóa
• Ghi nhật ký bắt đầu xử lý và số lượng kết quả
• Xử lý trường hợp có 0 danh sách được cập nhật

---

📖 Thứ tự Đọc Được Khuyến nghị

Để Triển khai Lần đầu:

1. Bắt đầu với QUICK_REFERENCE.md (đọc 3 phút)
2. Xem lại DETAILED_HANDLER_COMPARISON.md (đọc 10 phút)
3. Giữ ADMIN_MODULE_TEST_ANALYSIS.md mở để tham khảo mã chi tiết

Cho Handler Cụ thể:

• reject-listing: Xem ví dụ approve-listing.handler.spec.ts trong DETAILED_HANDLER_COMPARISON.md
• get-revenue-stats: Xem phần Query Handler trong DETAILED_HANDLER_COMPARISON.md
• user-deactivated: Xem phần So sánh Listener trong DETAILED_HANDLER_COMPARISON.md

---

🔍 Nội dung Của Từng Tài liệu

Các phần của ADMIN_MODULE_TEST_ANALYSIS.md:

1. Phần 1: Các tệp handler chưa được kiểm thử (với toàn bộ mã nguồn)
2. Phần 2: Cấu trúc và mẫu tệp kiểm thử hiện có
3. Phần 3: Mã handler để tham khảo (ví dụ ban-user)
4. Phần 4: Các tệp cơ sở hạ tầng (chỉ để tham khảo ngữ cảnh)
5. Phần 5: Tầng trình bày (chỉ để tham khảo ngữ cảnh)
6. Phần 6: Khuyến nghị viết kiểm thử
7. Phần 7: Cấu trúc tệp đầy đủ

Các phần của DETAILED_HANDLER_COMPARISON.md:

1. So sánh cấu trúc tệp: Bố cục thư mục
2. So sánh handler song parallel: approve vs reject
3. Hướng dẫn đọc mã kiểm thử: Kiểm thử approve-listing có chú thích
4. Cách điều chỉnh: Cho reject-listing
5. So sánh Query Handler: dashboard-stats vs revenue-stats
6. Mẫu kiểm thử Query Handler: Ví dụ đầy đủ
7. So sánh Listener: user-banned vs user-deactivated
8. Mẫu kiểm thử Listener: Ví dụ đầy đủ

Các phần của QUICK_REFERENCE.md:

1. Handler 1: Tổng quan reject-listing
2. Handler 2: Tổng quan get-revenue-stats
3. Handler 3: Tổng quan user-deactivated
4. Mẫu thiết lập Mock: Cho từng loại
5. Danh sách kiểm tra kiểm thử: Những gì cần xác minh

---

💡 Hướng dẫn Bắt đầu Nhanh

Bước 1: Chọn Handler của bạn

reject-listing → Dùng approve-listing làm mẫu
get-revenue-stats → Dùng get-dashboard-stats làm mẫu
user-deactivated → Dùng user-banned làm mẫu

Bước 2: Xem lại Kiểm thử Tham khảo

Đọc tệp kiểm thử tham khảo từ DETAILED_HANDLER_COMPARISON.md

Bước 3: Sao chép và Điều chỉnh

• Sao chép cấu trúc kiểm thử
• Thay đổi các import
• Điều chỉnh dữ liệu kiểm thử
• Xác minh các lệnh gọi mock

Bước 4: Xác minh Độ phủ

Chạy: npm test admin

---

📊 Thống kê Kiểm thử

Tệp	Loại	Số kiểm thử	Độ phức tạp
reject-listing.handler.spec.ts	Command	3	Trung bình
get-revenue-stats.handler.spec.ts	Query	3	Thấp
user-deactivated.listener.spec.ts	Listener	3	Trung bình
Tổng cộng	-	9	-

---

✅ Danh sách Kiểm tra Xác minh

Sau khi viết kiểm thử:

• Đã tạo đủ 3 tệp kiểm thử
• Tất cả các import đúng
• Tất cả các mock được thiết lập đúng cách
• Kiểm thử biên dịch không có lỗi
• npm test admin vượt qua tất cả kiểm thử
• Không có cảnh báo console
• Độ phủ mã > 85%

---

🔗 Vị trí Tệp

Tệp nguồn (cần kiểm thử):

• apps/api/src/modules/admin/application/commands/reject-listing/reject-listing.handler.ts
• apps/api/src/modules/admin/application/queries/get-revenue-stats/get-revenue-stats.handler.ts
• apps/api/src/modules/admin/application/listeners/user-deactivated.listener.ts

Tệp kiểm thử tham khảo:

• apps/api/src/modules/admin/application/__tests__/approve-listing.handler.spec.ts
• apps/api/src/modules/admin/application/__tests__/get-dashboard-stats.handler.spec.ts
• apps/api/src/modules/admin/application/__tests__/user-banned.listener.spec.ts

Nơi tạo kiểm thử mới:

• apps/api/src/modules/admin/application/__tests__/reject-listing.handler.spec.ts (MỚI)
• apps/api/src/modules/admin/application/__tests__/get-revenue-stats.handler.spec.ts (MỚI)
• apps/api/src/modules/admin/application/__tests__/user-deactivated.listener.spec.ts (MỚI)

---

📞 Những Điểm Mấu chốt

1. Cả 3 tệp đều tuân theo các mẫu đã được thiết lập trong codebase
2. Các kiểm thử tham khảo tồn tại cho từng loại handler
3. Tổng số kiểm thử cần có: 9 (3 mỗi tệp)
4. Thời gian dự kiến: 1-2 giờ để triển khai tất cả
5. Độ khó: Thấp đến Trung bình (tái sử dụng mã cao)
6. Tài liệu: Rất đầy đủ (tất cả mã đã được cung cấp)

---

Được tạo: 2026-04-11 Tất cả ví dụ kiểm thử đã sẵn sàng để điều chỉnh và triển khai.