goodgo-platform/docs/audits/TEST_COVERAGE_QUICK_REFERENCE.md

# Kiểm Toán Độ Phủ Kiểm Thử - Tài Liệu Tham Khảo Nhanh

**Ngày tạo:** 10 tháng 4 năm 2026  
**Kho lưu trữ:** GoodGo Platform AI Monorepo  
**Các module được kiểm toán:** Listings, Auth, Search

---

## 📊 Tổng Quan Độ Phủ

| Module | Tệp nguồn | Tệp kiểm thử | Độ phủ | Trạng thái |
|--------|:----:|:----:|:---:|:---:|
| **Listings** | 42 | 13 | **31%** | ⚠️ Thấp |
| **Auth** | 56 | 21 | **38%** | ⚠️ Thấp |
| **Search** | 22 | 10 | **45%** | ⚠️ Thấp |
| **TỔNG CỘNG** | **120** | **44** | **37%** | ⚠️ Thấp |

---

## 🔴 NGHIÊM TRỌNG - Phải Kiểm Thử Trước (11 tệp)

### Module AUTH - Nghiêm trọng về Bảo mật (4 tệp)
```
1. presentation/guards/jwt-auth.guard.ts
   └─ Lý do: Bảo mật xác thực token
   └─ Kiểm thử: Token hợp lệ, đã hết hạn, chữ ký không hợp lệ

2. presentation/guards/roles.guard.ts
   └─ Lý do: Thực thi phân quyền
   └─ Kiểm thử: Truy cập admin, truy cập người dùng, truy cập bị từ chối

3. infrastructure/repositories/prisma-user.repository.ts
   └─ Lý do: Truy cập dữ liệu người dùng chính
   └─ Kiểm thử: Các thao tác CRUD, truy vấn tìm kiếm người dùng

4. infrastructure/strategies/jwt.strategy.ts
   └─ Lý do: Xác thực JWT
   └─ Kiểm thử: Xác thực token, trích xuất thông tin người dùng
```

### Module LISTINGS - Nghiêm trọng về Logic Nghiệp vụ (4 tệp)
```
5. infrastructure/services/prisma-duplicate-detector.ts
   └─ Lý do: Phát hiện trùng lặp cốt lõi
   └─ Kiểm thử: Truy vấn cơ sở dữ liệu, logic tương đồng

6. infrastructure/services/prisma-price-validator.ts
   └─ Lý do: Logic xác thực giá
   └─ Kiểm thử: Khoảng giá, quy tắc xác thực

7. infrastructure/repositories/prisma-listing.repository.ts
   └─ Lý do: Truy cập dữ liệu tin đăng chính
   └─ Kiểm thử: Các thao tác CRUD, truy vấn phức tạp

8. domain/services/moderation.service.ts
   └─ Lý do: Quy tắc nghiệp vụ kiểm duyệt
   └─ Kiểm thử: Logic phê duyệt/từ chối, chấm điểm
```

### Module SEARCH - Nghiêm trọng về Tích hợp (2 tệp)
```
9. infrastructure/services/typesense-client.service.ts
   └─ Lý do: Tích hợp công cụ tìm kiếm
   └─ Kiểm thử: Khởi tạo client, kết nối, lỗi

10. infrastructure/services/postgres-search.repository.ts
    └─ Lý do: Triển khai tìm kiếm dự phòng
    └─ Kiểm thử: Xây dựng truy vấn, logic dự phòng
```

---

## 📋 Danh Sách Đầy Đủ Tệp Module Listings

### ✅ Đã Kiểm Thử (13 tệp)

**Tầng Application (8):**
- ✓ create-listing.handler.spec.ts
- ✓ get-listing.handler.spec.ts
- ✓ get-pending-moderation.handler.spec.ts
- ✓ moderate-listing.handler.spec.ts
- ✓ price-validator.spec.ts
- ✓ search-listings.handler.spec.ts
- ✓ update-listing-status.handler.spec.ts
- ✓ upload-media.handler.spec.ts

**Tầng Domain (5):**
- ✓ duplicate-detector.spec.ts
- ✓ listing-events.spec.ts
- ✓ listing.entity.spec.ts
- ✓ property.entity.spec.ts
- ✓ value-objects.spec.ts

### ❌ Chưa Có Kiểm Thử (29 tệp)

**Tầng Domain (10):**
- ✗ domain/services/moderation.service.ts [TIER 1]
- ✗ domain/repositories/listing.repository.ts (interface)
- ✗ domain/repositories/property.repository.ts (interface)
- ✗ domain/repositories/listing-read.dto.ts
- ✗ domain/events/listing-approved.event.ts
- ✗ domain/events/listing-sold.event.ts
- ✗ domain/events/listing-status-changed.event.ts
- ✗ domain/entities/* (đã có kiểm thử - hợp nhất nếu cần)
- ✗ domain/value-objects/* (đã có kiểm thử - hợp nhất nếu cần)
- ✗ domain/services/duplicate-detector.ts (có kiểm thử handler, cần kiểm thử đơn vị)

**Tầng Application (0 - Đã Phủ Toàn Bộ):**
Tất cả các handler và command đều đã được kiểm thử.

**Tầng Infrastructure (6):**
- ✗ infrastructure/services/prisma-duplicate-detector.ts [TIER 1]
- ✗ infrastructure/services/prisma-price-validator.ts [TIER 1]
- ✗ infrastructure/services/media-storage.service.ts
- ✗ infrastructure/repositories/prisma-listing.repository.ts [TIER 1]
- ✗ infrastructure/repositories/prisma-property.repository.ts
- ✗ infrastructure/repositories/listing-read.queries.ts

**Tầng Presentation (13):**
- ✗ listings.module.ts
- ✗ presentation/controllers/listings.controller.ts
- ✗ presentation/dto/create-listing.dto.ts
- ✗ presentation/dto/moderate-listing.dto.ts
- ✗ presentation/dto/search-listings.dto.ts
- ✗ presentation/dto/update-listing-status.dto.ts

---

## 📋 Danh Sách Đầy Đủ Tệp Module Auth

### ✅ Đã Kiểm Thử (21 tệp)

**Tầng Application (12):**
- ✓ cancel-user-deletion.handler.spec.ts
- ✓ export-user-data.handler.spec.ts
- ✓ force-delete-user.handler.spec.ts
- ✓ get-agent-by-user-id.handler.spec.ts
- ✓ get-profile.handler.spec.ts
- ✓ login-user.handler.spec.ts
- ✓ process-scheduled-deletions.handler.spec.ts
- ✓ refresh-token.handler.spec.ts
- ✓ register-user.handler.spec.ts
- ✓ request-user-deletion.handler.spec.ts
- ✓ verify-kyc.handler.spec.ts

**Tầng Infrastructure (4):**
- ✓ google-oauth.strategy.spec.ts
- ✓ oauth.service.spec.ts
- ✓ token.service.spec.ts
- ✓ zalo-oauth.strategy.spec.ts

**Tầng Domain (5):**
- ✓ auth-events.spec.ts
- ✓ email.vo.spec.ts
- ✓ hashed-password.vo.spec.ts
- ✓ phone.vo.spec.ts
- ✓ user.entity.spec.ts

**Tích hợp (1):**
- ✓ auth.integration.spec.ts

### ❌ Chưa Có Kiểm Thử (35 tệp)

**Tầng Infrastructure (6):**
- ✗ infrastructure/strategies/jwt.strategy.ts [TIER 1]
- ✗ infrastructure/strategies/local.strategy.ts
- ✗ infrastructure/repositories/prisma-user.repository.ts [TIER 1]
- ✗ infrastructure/repositories/prisma-refresh-token.repository.ts

**Tầng Presentation (14):**
- ✗ presentation/guards/jwt-auth.guard.ts [TIER 1 - NGHIÊM TRỌNG]
- ✗ presentation/guards/roles.guard.ts [TIER 1 - NGHIÊM TRỌNG]
- ✗ presentation/guards/local-auth.guard.ts
- ✗ presentation/guards/google-oauth.guard.ts
- ✗ presentation/decorators/current-user.decorator.ts
- ✗ presentation/decorators/roles.decorator.ts
- ✗ presentation/controllers/auth.controller.ts
- ✗ presentation/controllers/oauth.controller.ts
- ✗ presentation/controllers/user-data.controller.ts
- ✗ presentation/dto/login.dto.ts
- ✗ presentation/dto/register.dto.ts
- ✗ presentation/dto/refresh-token.dto.ts
- ✗ presentation/dto/verify-kyc.dto.ts
- ✗ presentation/dto/force-delete-user.dto.ts
- ✗ presentation/dto/request-deletion.dto.ts

**Khác (15):**
- ✗ auth.module.ts

---

## 📋 Danh Sách Đầy Đủ Tệp Module Search

### ✅ Đã Kiểm Thử (10 tệp)

**Tầng Application (4):**
- ✓ geo-search.handler.spec.ts
- ✓ reindex-all.handler.spec.ts
- ✓ search-properties.handler.spec.ts
- ✓ sync-listing.handler.spec.ts

**Tầng Infrastructure (4):**
- ✓ listing-approved.handler.spec.ts
- ✓ listing-indexer.service.spec.ts
- ✓ resilient-search.repository.spec.ts
- ✓ typesense-search.repository.spec.ts

**Tầng Domain (1):**
- ✓ search-domain.spec.ts

**Tầng Presentation (1):**
- ✓ search.controller.spec.ts

### ❌ Chưa Có Kiểm Thử (12 tệp)

**Tầng Infrastructure (3):**
- ✗ infrastructure/services/typesense-client.service.ts [TIER 1]
- ✗ infrastructure/services/postgres-search.repository.ts [TIER 1]
- ✗ infrastructure/event-handlers/listing-status-changed.handler.ts

**Tầng Presentation (2):**
- ✗ presentation/dto/geo-search.dto.ts
- ✗ presentation/dto/search-properties.dto.ts

**Khác (1):**
- ✗ search.module.ts

---

## 🎯 Lộ Trình Triển Khai

### Tuần 1 - Bảo mật Nghiêm trọng & Logic Nghiệp vụ (11 tệp)
**Thời gian: ~20-25 giờ**

- [ ] **AUTH** - jwt-auth.guard.spec.ts (3h)
- [ ] **AUTH** - roles.guard.spec.ts (3h)
- [ ] **AUTH** - prisma-user.repository.spec.ts (3h)
- [ ] **AUTH** - jwt.strategy.spec.ts (3h)
- [ ] **LISTINGS** - prisma-duplicate-detector.spec.ts (2.5h)
- [ ] **LISTINGS** - prisma-price-validator.spec.ts (2.5h)
- [ ] **LISTINGS** - prisma-listing.repository.spec.ts (3h)
- [ ] **LISTINGS** - moderation.service.spec.ts (2.5h)
- [ ] **SEARCH** - typesense-client.service.spec.ts (2.5h)
- [ ] **SEARCH** - postgres-search.repository.spec.ts (2.5h)

### Tuần 2-3 - Infrastructure Ưu tiên Cao (9 tệp)
**Thời gian: ~15-18 giờ**

- [ ] **AUTH** - local.strategy.spec.ts (2.5h)
- [ ] **AUTH** - prisma-refresh-token.repository.spec.ts (2.5h)
- [ ] **AUTH** - local-auth.guard.spec.ts (2.5h)
- [ ] **AUTH** - google-oauth.guard.spec.ts (2.5h)
- [ ] **LISTINGS** - prisma-property.repository.spec.ts (2.5h)
- [ ] **LISTINGS** - listing-read.queries.spec.ts (2.5h)
- [ ] **LISTINGS** - media-storage.service.spec.ts (2h)
- [ ] **SEARCH** - listing-status-changed.handler.spec.ts (2h)

### Tuần 4 - Ưu tiên Trung bình (Controller, Decorator)
**Thời gian: ~12-15 giờ**

- [ ] **AUTH** - auth.controller.spec.ts (2.5h)
- [ ] **AUTH** - oauth.controller.spec.ts (2.5h)
- [ ] **AUTH** - user-data.controller.spec.ts (2h)
- [ ] **AUTH** - current-user.decorator.spec.ts (1.5h)
- [ ] **AUTH** - roles.decorator.spec.ts (1.5h)
- [ ] **LISTINGS** - listings.controller.spec.ts (2.5h)
- [ ] **SEARCH** - Không có gì ở đây (controller đã được kiểm thử)

### Tuần 5+ - DTO, Cấu hình Module, Kiểm thử E2E
**Thời gian: ~10+ giờ**

- [ ] Tất cả kiểm thử xác thực DTO (3-4 tệp mỗi module)
- [ ] Kiểm thử cấu hình module
- [ ] Kiểm thử tích hợp end-to-end
- [ ] Kiểm thử luồng người dùng hoàn chỉnh

---

## 🧪 Hướng Dẫn Loại Kiểm Thử

### Kiểm Thử Đơn Vị (trung bình 50 phút mỗi tệp)
**Dành cho:** Service, repository, value object, entity
```typescript
// Cấu trúc kiểm thử
describe('ServiceName', () => {
  let service: ServiceName;
  let mockDependency: Mock;
  
  beforeEach(() => {
    mockDependency = mock();
    service = new ServiceName(mockDependency);
  });
  
  it('should handle success case', () => {});
  it('should handle error case', () => {});
});
```

### Kiểm Thử Tích Hợp (trung bình 60 phút mỗi tệp)
**Dành cho:** Repository, event handler, strategy
```typescript
// Cấu trúc kiểm thử - thường dùng với cơ sở dữ liệu/dịch vụ thực
describe('RepositoryName', () => {
  let repository: RepositoryName;
  let prisma: PrismaClient; // hoặc client thực
  
  beforeEach(async () => {
    await setupTestDatabase();
    repository = new RepositoryName(prisma);
  });
  
  afterEach(async () => {
    await cleanupTestDatabase();
  });
});
```

### Kiểm Thử Guard/Decorator (trung bình 30 phút mỗi tệp)
**Dành cho:** Guard, decorator, middleware
```typescript
// Cấu trúc kiểm thử
describe('GuardName', () => {
  let guard: GuardName;
  let mockExecutionContext: Mock;
  
  it('should allow authorized requests', () => {});
  it('should deny unauthorized requests', () => {});
});
```

### Kiểm Thử Controller (trung bình 40 phút mỗi tệp)
**Dành cho:** REST controller
```typescript
// Cấu trúc kiểm thử
describe('ControllerName', () => {
  let controller: ControllerName;
  let mockService: Mock;
  
  it('should handle POST request', () => {});
  it('should return 400 for invalid input', () => {});
});
```

### Kiểm Thử DTO (trung bình 20 phút mỗi tệp)
**Dành cho:** Đối tượng xác thực dữ liệu
```typescript
// Cấu trúc kiểm thử - tập trung vào xác thực
describe('DtoName', () => {
  it('should validate correct data', () => {});
  it('should reject invalid email', () => {});
  it('should reject short password', () => {});
});
```

---

## 📊 Độ Phủ theo Tầng Kiến Trúc

### Tầng Domain
| Danh mục | Listings | Auth | Search | Tổng | Độ phủ |
|----------|:---:|:---:|:---:|:---:|:---:|
| Entity | 3/3 ✓ | 1/1 ✓ | - | 4/4 | **100%** |
| Value Object | 3/3 ✓ | 3/3 ✓ | 2/2 ✓ | 8/8 | **100%** |
| Service | 2/3 | - | - | 2/3 | **67%** |
| Repository | 0/3 | 0/2 | 0/1 | 0/6 | **0%** |
| Event | 1/4 | 1/4 | - | 2/8 | **25%** |
| **Tổng Domain** | **9/16** | **5/10** | **2/3** | **16/29** | **55%** |

### Tầng Application
| Danh mục | Listings | Auth | Search | Tổng | Độ phủ |
|----------|:---:|:---:|:---:|:---:|:---:|
| Handler | 8/8 ✓ | 12/12 ✓ | 8/8 ✓ | 28/28 | **100%** |
| Command | - | - | - | - | **100%** |
| Query | - | - | - | - | **100%** |
| **Tổng App** | **8/8** | **12/12** | **8/8** | **28/28** | **100%** |

### Tầng Infrastructure
| Danh mục | Listings | Auth | Search | Tổng | Độ phủ |
|----------|:---:|:---:|:---:|:---:|:---:|
| Repository | 0/3 | 0/2 | 0/2 | 0/7 | **0%** |
| Service | 1/3 | 2/2 ✓ | 3/5 | 6/10 | **60%** |
| Strategy | - | 2/4 | - | 2/4 | **50%** |
| Event Handler | - | - | 1/2 | 1/2 | **50%** |
| **Tổng Infra** | **1/6** | **4/8** | **4/9** | **9/23** | **39%** |

### Tầng Presentation
| Danh mục | Listings | Auth | Search | Tổng | Độ phủ |
|----------|:---:|:---:|:---:|:---:|:---:|
| Controller | 0/1 | 0/3 | 1/1 ✓ | 1/5 | **20%** |
| Guard | - | 0/4 | - | 0/4 | **0%** |
| Decorator | - | 0/2 | - | 0/2 | **0%** |
| DTO | 0/4 | 0/6 | 0/2 | 0/12 | **0%** |
| **Tổng Presentation** | **0/5** | **0/15** | **1/3** | **1/23** | **4%** |

### Tóm Tắt
| Tầng | Tệp | Đã kiểm thử | Độ phủ |
|-------|:---:|:---:|:---:|
| **Domain** | 29 | 16 | 55% |
| **Application** | 28 | 28 | 100% ✓ |
| **Infrastructure** | 23 | 9 | 39% |
| **Presentation** | 23 | 1 | 4% |
| **TỔNG CỘNG** | **103** | **54** | **52%** |

---

## 📝 Ghi Chú

- Tỷ lệ phần trăm độ phủ không tính các tệp barrel index.ts
- Command/Query được kiểm thử thông qua các handler tương ứng
- Các interface repository trừu tượng không được kiểm thử (chỉ kiểm thử phần triển khai)
- Kiểm thử tích hợp được đánh dấu riêng biệt so với kiểm thử đơn vị
- Thời gian ước tính giả định có kinh nghiệm với Vitest/Jest