docs: consolidate audit and analysis reports into docs/audits/

Move 36 root-level audit/analysis documents and 7 web app audit documents into docs/audits/ directory to declutter the project root. Remove stale EXPLORATION_SUMMARY.txt. Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-04-11 01:37:50 +07:00
parent 64c6074735
commit b8512ebff4
44 changed files with 21507 additions and 301 deletions
--- a/docs/audits/TESTING_INDEX.md
+++ b/docs/audits/TESTING_INDEX.md
@@ -0,0 +1,383 @@
+# Test Coverage Documentation Index
+
+**Generated:** 2026-04-11  
+**Total Lines of Documentation:** 3,014  
+**Total Files Analyzed:** 17 untested source files  
+
+---
+
+## 📚 Documentation Files
+
+### 1. **README_TEST_COVERAGE.md** (9.1 KB)
+Start here for complete overview and roadmap.
+
+**Contains:**
+- Overview of all 4 documentation files
+- File organization by module (Inquiries, Leads, Reviews)
+- Priority testing levels (Critical 🔴, High 🟡, Medium 🟢)
+- 3-week testing roadmap with time estimates
+- Key testing patterns for each file type
+- Critical formulas to verify in tests
+- Common test data and import statements
+- Troubleshooting guide
+- Quick start instructions
+
+**Time to read:** 5-10 minutes
+
+---
+
+### 2. **TEST_COVERAGE_ANALYSIS.md** (55 KB)
+Complete reference with all 17 source files and full implementations.
+
+**Contains:**
+- Executive summary
+- **PART 1: INQUIRIES MODULE** (4 files)
+  - PrismaInquiryRepository (146 lines)
+  - InquiriesController (120 lines)
+  - CreateInquiryDto (20 lines)
+  - ListInquiriesDto (20 lines)
+  
+- **PART 2: LEADS MODULE** (6 files)
+  - PrismaLeadRepository (151 lines)
+  - LeadScore ValueObject (16 lines)
+  - LeadsController (126 lines)
+  - CreateLeadDto (35 lines)
+  - ListLeadsDto (30 lines)
+  - UpdateLeadStatusDto (14 lines)
+  
+- **PART 3: REVIEWS MODULE** (5 files)
+  - PrismaReviewRepository (162 lines)
+  - Rating ValueObject (16 lines)
+  - ReviewsController (122 lines)
+  - CreateReviewDto (26 lines)
+  - ListReviewsDto (42 lines)
+
+- **PART 4: REFERENCE TEST PATTERNS** (3 test files)
+  - CreateInquiryHandler test pattern
+  - CreateLeadHandler test pattern
+  - ReviewsController test pattern
+
+- Summary table of all files
+- Testing priorities
+- Test coverage goals
+
+**Time to read:** 30-45 minutes for complete review
+
+**How to use:**
+1. Find the file you want to test
+2. Read the full implementation
+3. Review the "Key Methods to Test" section
+4. Check "Test Scenarios" section
+5. Cross-reference with templates in TEST_TEMPLATES.md
+
+---
+
+### 3. **TEST_COVERAGE_QUICK_REFERENCE.md** (9.1 KB)
+Checklists and quick lookup reference.
+
+**Contains:**
+- 17 files overview with line counts
+- Quick test scenarios by type:
+  - Repositories (3 files) - checklist + specific notes
+  - Value Objects (2 files) - validation ranges
+  - Controllers (2 files) - endpoint checklist
+  - DTOs (10 files) - validation rules
+  
+- Test priority matrix:
+  - Critical: 4 items (business logic)
+  - High: 5 items (data integrity)
+  - Medium: 3 items (validation/guards)
+
+- Test execution order recommendation
+- Mock setup templates (4 examples)
+- Key formulas to verify
+- File locations reference
+
+**Time to read:** 3-5 minutes for lookup
+
+**How to use:**
+1. Find the file type you're testing
+2. Check the quick checklist
+3. Jump to detailed section in Analysis for more info
+4. Copy the mock template from this file
+
+---
+
+### 4. **TEST_TEMPLATES.md** (16 KB)
+Ready-to-use code templates for all file types.
+
+**Contains:**
+- Repository Test Template
+  - Setup with mocked Prisma
+  - Test findById()
+  - Test save()
+  - Test findByListing() with pagination
+
+- Value Object Test Template
+  - Test create() with valid values
+  - Test boundary values
+  - Test invalid values
+  - Test error messages
+  - Test getters
+
+- DTO Test Template
+  - Test required fields validation
+  - Test optional fields
+  - Test field constraints (email, range)
+  - Test type transformation
+
+- Controller Test Template
+  - Setup with mocked buses
+  - Test command dispatch
+  - Test parameter mapping
+  - Test null handling
+  - Test default values
+
+- Helper Tests
+  - Pagination calculation tests
+  - Aggregation formula tests
+  - DTO pagination tests
+
+**Time to read:** 10-15 minutes while writing tests
+
+**How to use:**
+1. Copy the appropriate template for your file type
+2. Paste into your test file
+3. Replace generic names with your specific file names
+4. Update imports and test data
+5. Run and verify tests pass
+
+---
+
+## 🎯 Quick Navigation by Task
+
+### "I want to understand what needs testing"
+→ Start with **README_TEST_COVERAGE.md** (5 min)  
+→ Then **TEST_COVERAGE_QUICK_REFERENCE.md** (3 min)
+
+### "I want to write tests for a specific file"
+→ Find the file in **TEST_COVERAGE_QUICK_REFERENCE.md**  
+→ Read detailed implementation in **TEST_COVERAGE_ANALYSIS.md**  
+→ Copy template from **TEST_TEMPLATES.md**  
+→ Adapt template to your file
+
+### "I want to understand a specific component"
+→ Look up file in **TEST_COVERAGE_ANALYSIS.md**  
+→ Find section with "Key Methods to Test"  
+→ Find section with "Test Scenarios"  
+→ Check **TEST_TEMPLATES.md** for pattern
+
+### "I want formulas and calculations"
+→ **TEST_COVERAGE_QUICK_REFERENCE.md** - "Key Formulas to Verify"  
+→ **TEST_TEMPLATES.md** - Aggregation Test Helper  
+→ **TEST_COVERAGE_ANALYSIS.md** - Specific repo section
+
+### "I need mock setup examples"
+→ **TEST_COVERAGE_QUICK_REFERENCE.md** - Mock Setup Template  
+→ **TEST_TEMPLATES.md** - First section for each type
+
+---
+
+## 📋 17 Files at a Glance
+
+### Inquiries (4 files)
+| File | Type | Key Test |
+|------|------|----------|
+| prisma-inquiry.repository.ts | Repository | Pagination, relationships |
+| inquiries.controller.ts | Controller | 4 endpoints, guards |
+| create-inquiry.dto.ts | DTO | 3 validations |
+| list-inquiries.dto.ts | DTO | Pagination validation |
+
+### Leads (6 files)
+| File | Type | Key Test |
+|------|------|----------|
+| prisma-lead.repository.ts | Repository | Stats aggregation |
+| lead-score.vo.ts | ValueObject | Range 0-100 |
+| leads.controller.ts | Controller | 5 endpoints, role guard |
+| create-lead.dto.ts | DTO | 6 validations |
+| list-leads.dto.ts | DTO | Status enum |
+| update-lead-status.dto.ts | DTO | Status validation |
+
+### Reviews (5 files)
+| File | Type | Key Test |
+|------|------|----------|
+| prisma-review.repository.ts | Repository | Distribution stats |
+| rating.vo.ts | ValueObject | Integer 1-5 only |
+| reviews.controller.ts | Controller | 5 endpoints, mixed auth |
+| create-review.dto.ts | DTO | 4 validations |
+| list-reviews.dto.ts | DTO | 2 DTOs, pagination |
+
+---
+
+## ⏱️ Time Estimates
+
+### By File Type
+- **Value Objects** (2 files): 30-45 minutes
+- **DTOs** (10 files): 2-3 hours (using templates)
+- **Controllers** (2 files): 1.5-2 hours
+- **Repositories** (3 files): 2.5-3.5 hours
+
+### Total: 9-14 hours
+
+### Recommended Order
+1. Value Objects (fastest, builds confidence)
+2. DTOs (quick, many file repetition)
+3. Controllers (medium complexity)
+4. Repositories (most complex, worth doing last)
+
+---
+
+## 🔍 What Each File Tests
+
+### Value Objects
+- **LeadScore.vo**
+  - ✓ Valid range 0-100
+  - ✓ Rejection of invalid values
+  - ✓ Error message in Vietnamese
+  
+- **Rating.vo**
+  - ✓ Valid integers 1-5 only
+  - ✓ Rejection of 0, 6, floats
+  - ✓ Error message in Vietnamese
+
+### DTOs
+- **Pagination DTOs** (4 files)
+  - ✓ Page/limit validation
+  - ✓ Type transformation
+  - ✓ Default values
+  
+- **Status DTOs** (2 files)
+  - ✓ Enum validation
+  - ✓ Only valid statuses accepted
+  
+- **Create DTOs** (4 files)
+  - ✓ Required field validation
+  - ✓ Optional field handling
+  - ✓ Field constraints (email, length, range)
+
+### Controllers
+- **InquiriesController**
+  - ✓ 4 endpoints with correct dispatch
+  - ✓ JWT authentication
+  - ✓ Role-based guards (AGENT)
+  
+- **LeadsController**
+  - ✓ 5 endpoints with correct dispatch
+  - ✓ Class-level role guard (AGENT)
+  - ✓ Optional field handling
+  
+- **ReviewsController**
+  - ✓ 5 endpoints with correct dispatch
+  - ✓ Mixed authentication (some endpoints public)
+  - ✓ User ownership verification
+
+### Repositories
+- **PrismaInquiryRepository**
+  - ✓ CRUD: findById, save, markAsRead
+  - ✓ Paginated: findByListing, findByAgent
+  - ✓ Aggregation: countUnreadByAgent
+  - ✓ Data mapping: toDomain
+  
+- **PrismaLeadRepository**
+  - ✓ CRUD: findById, save, update, delete
+  - ✓ Pagination with optional status filter
+  - ✓ Aggregation: getStatsByAgent (conversion rate, avg score)
+  - ✓ Data mapping including LeadScore VO
+  
+- **PrismaReviewRepository**
+  - ✓ CRUD: findById, findByUserAndTarget, save, delete
+  - ✓ Pagination: findByTarget, findByUserId
+  - ✓ Aggregation: getStats (distribution, average rating)
+  - ✓ Data mapping including Rating VO
+
+---
+
+## 📖 Reference Examples
+
+### Working Test Patterns
+Three complete test files are included as references:
+
+1. **create-inquiry.handler.spec.ts** (99 lines)
+   - Mock repository, EventBus, Prisma
+   - Happy path test
+   - Error handling test
+   - Event publishing verification
+
+2. **create-lead.handler.spec.ts** (121 lines)
+   - Similar pattern to create-inquiry
+   - Tests optional field handling
+   - Tests ValueObject validation
+
+3. **reviews.controller.spec.ts** (135 lines)
+   - Controller endpoint testing
+   - Bus dispatch verification
+   - Query parameter handling
+   - Default value application
+
+---
+
+## ✅ Testing Checklist Template
+
+```
+Module: ___________________
+File: _____________________
+
+Imports:
+- [ ] Test framework imported
+- [ ] Classes imported
+- [ ] Mocks ready
+
+Setup:
+- [ ] beforeEach creates fresh mocks
+- [ ] Dependencies injected
+- [ ] Test data prepared
+
+Happy Path:
+- [ ] Basic functionality test
+- [ ] Return values verified
+- [ ] Methods called correctly
+
+Edge Cases:
+- [ ] Null/undefined handling
+- [ ] Empty results handling
+- [ ] Boundary values
+
+Error Cases:
+- [ ] Invalid input rejection
+- [ ] Error messages verified
+- [ ] Guard validation
+
+Cleanup:
+- [ ] Mocks cleaned after each test
+- [ ] No test interdependencies
+```
+
+---
+
+## 💡 Pro Tips
+
+1. **Start Small**: Begin with Value Objects (simplest)
+2. **Copy-Paste**: Use templates, don't write from scratch
+3. **Test Early**: Run tests as you write them
+4. **Be Thorough**: Include both happy and error paths
+5. **Use Existing**: Reference existing tests in the codebase
+6. **Verify Formulas**: Test arithmetic calculations carefully
+7. **Mock Everything**: Don't hit real database in tests
+8. **Test Guards**: Don't forget authentication/authorization
+
+---
+
+## 🆘 Need Help?
+
+1. **Configuration question?** → See README_TEST_COVERAGE.md
+2. **Template needed?** → See TEST_TEMPLATES.md
+3. **Implementation details?** → See TEST_COVERAGE_ANALYSIS.md
+4. **Quick lookup?** → See TEST_COVERAGE_QUICK_REFERENCE.md
+5. **Existing example?** → Check modules' `__tests__` directories
+
+---
+
+**Document Version:** 1.0  
+**Last Updated:** 2026-04-11  
+**Total Documentation:** 3,014 lines across 4 files  
+**Coverage:** 17 untested source files (Inquiries, Leads, Reviews modules)