goodgo-platform/docs/audits/README_INQUIRIES_EXPLORATION.md

📚 Mô-đun Inquiries - Tài Liệu Khám Phá Toàn Diện

Ngày tạo: 11 tháng 4, 2026
Mô-đun: apps/api/src/modules/inquiries/
Trạng thái: ✅ Phân tích Đầy đủ & Kỹ lưỡng

---

📖 CÁC TỆP TÀI LIỆU

Bộ khám phá này bao gồm 3 tệp tài liệu toàn diện được thiết kế cho các trường hợp sử dụng khác nhau:

1. INQUIRIES_MODULE_EXPLORATION.md (23 KB)

Mục đích: Tài liệu tham khảo chuyên sâu
Phù hợp nhất: Hiểu kiến trúc, các mẫu thiết kế và mô tả tệp đầy đủ

Nội dung:

• 📁 Cấu trúc thư mục đầy đủ
• 📄 Danh sách tệp hoàn chỉnh kèm mô tả
• 🏗️ Sơ đồ kiến trúc mô-đun
• 🔑 Phân tích các lớp và trình xử lý chính
• 🎯 Phân tích tầng DDD
• 📊 Tóm tắt tệp kiểm thử
• 🛠️ Phụ thuộc và bảo mật
• 📝 Hợp đồng API

Đọc khi: Bạn cần hiểu toàn diện về mô-đun

---

2. INQUIRIES_MODULE_QUICK_REFERENCE.md (9.3 KB)

Mục đích: Tài liệu tra cứu nhanh
Phù hợp nhất: Nắm bắt nhanh, tìm thông tin cụ thể

Nội dung:

• 📊 Tổng quan mô-đun
• 📁 Các tệp theo tầng tổng quan
• 🔄 Sơ đồ luồng yêu cầu
• 🔑 Bảng các lớp chính
• 📝 Các giao diện chính
• 🧪 Thống kê kiểm thử
• 🔐 Ma trận phân quyền
• 🎯 Nguyên tắc DDD
• 📌 Các mẫu phổ biến
• 🔍 Hướng dẫn tìm kiếm theo chủ đề

Đọc khi: Bạn cần câu trả lời nhanh hoặc mới làm quen với mô-đun

---

3. INQUIRIES_COMPLETE_FILE_INDEX.md (23 KB)

Mục đích: Tài liệu tham chiếu tệp đầy đủ
Phù hợp nhất: Tìm các tệp cụ thể, hiểu phụ thuộc, lập kế hoạch sửa đổi

Nội dung:

• 📋 Danh sách tệp đầy đủ theo đường dẫn
• 📊 Bảng thống kê tệp
• 🔍 Hướng dẫn khám phá tệp
• 🔗 Đồ thị phụ thuộc
• 📝 Tham chiếu chéo tệp
• 🎯 Điểm vào để sửa đổi
• Số dòng của từng tệp
• Mô tả phương thức chi tiết

Đọc khi: Bạn cần chi tiết từng tệp hoặc đang lập kế hoạch thay đổi

---

🎯 KHỞI ĐẦU NHANH THEO TRƯỜNG HỢP SỬ DỤNG

Tôi muốn hiểu kiến trúc tổng thể

→ Bắt đầu với Quick Reference → Đi sâu vào Exploration

Tôi mới làm quen với mô-đun này

→ Bắt đầu với Quick Reference → Duyệt File Index khi cần

Tôi cần thêm một endpoint mới

→ Xem File Index → Mục Entry Points → Làm theo hướng dẫn

Tôi cần hiểu một tầng cụ thể

→ Tìm kiếm trong Quick Reference theo tầng → Đọc chi tiết đầy đủ trong Exploration

Tôi đang tìm một lớp hoặc phương thức cụ thể

→ Dùng File Index → Mục File Discovery Guide

Tôi cần hiểu luồng dữ liệu

→ Quick Reference → Mục Request Flows

Tôi đang sửa lỗi hoặc tái cấu trúc

→ File Index → Dependency Graph & Cross-References

---

📊 TỔNG QUAN MÔ-ĐUN

Location:    apps/api/src/modules/inquiries/
Files:       25 total (19 source + 6 test files)
LOC:         1,212 lines of code
Pattern:     CQRS + DDD (Clean Architecture)
Tests:       24 test cases across 6 suites
Endpoints:   4 HTTP endpoints

Phân Tích Theo Tầng

Tầng	Tệp	Mục đích
Presentation	5	Điểm cuối HTTP + xác thực
Application	8	Lệnh/Truy vấn + điều phối
Domain	6	Logic nghiệp vụ + hợp đồng
Infrastructure	1	Lưu trữ Prisma
Module	2	Cấu hình + xuất

---

🗂️ CÂY TỆP

inquiries/
├── 📄 index.ts                              [Barrel export]
├── 📄 inquiries.module.ts                   [NestJS Module]
│
├── 📁 presentation/
│   ├── controllers/
│   │   └── inquiries.controller.ts          [4 endpoints]
│   ├── dto/
│   │   ├── create-inquiry.dto.ts            [Input validation]
│   │   └── list-inquiries.dto.ts            [Pagination]
│   └── __tests__/
│       └── inquiries.controller.spec.ts     [6 tests]
│
├── 📁 application/
│   ├── commands/
│   │   ├── create-inquiry/
│   │   │   ├── create-inquiry.command.ts
│   │   │   └── create-inquiry.handler.ts
│   │   └── mark-inquiry-read/
│   │       ├── mark-inquiry-read.command.ts
│   │       └── mark-inquiry-read.handler.ts
│   ├── queries/
│   │   ├── get-inquiries-by-agent/
│   │   │   ├── get-inquiries-by-agent.query.ts
│   │   │   └── get-inquiries-by-agent.handler.ts
│   │   └── get-inquiries-by-listing/
│   │       ├── get-inquiries-by-listing.query.ts
│   │       └── get-inquiries-by-listing.handler.ts
│   └── __tests__/
│       ├── create-inquiry.handler.spec.ts
│       ├── mark-inquiry-read.handler.spec.ts
│       ├── get-inquiries-by-listing.handler.spec.ts
│       └── get-inquiries-by-agent.handler.spec.ts
│
├── 📁 domain/
│   ├── entities/
│   │   └── inquiry.entity.ts                [Aggregate Root]
│   ├── events/
│   │   ├── inquiry-created.event.ts
│   │   └── inquiry-read.event.ts
│   ├── repositories/
│   │   ├── inquiry.repository.ts            [Interface]
│   │   └── inquiry-read.dto.ts              [Read DTO]
│   └── __tests__/
│       └── inquiry-domain.spec.ts           [5 tests]
│
└── 📁 infrastructure/
    └── repositories/
        └── prisma-inquiry.repository.ts     [Implementation]

---

🔄 LUỒNG YÊU CẦU

Tạo Yêu Cầu

POST /inquiries
→ Controller xác thực JWT
→ CreateInquiryCommand được gửi đi
→ CreateInquiryHandler thực thi:
  • Xác thực listing tồn tại
  • Tạo InquiryEntity
  • Lưu vào repository
  • Phát hành InquiryCreatedEvent
→ Response: { id, listingId, createdAt }

Đánh Dấu Đã Đọc

PATCH /inquiries/:id/read (chỉ AGENT)
→ Controller xác thực JWT + vai trò AGENT
→ MarkInquiryReadCommand được gửi đi
→ MarkInquiryReadHandler thực thi:
  • Tải entity yêu cầu
  • Xác minh agent sở hữu listing
  • Cập nhật trạng thái entity
  • Lưu thay đổi
  • Phát hành InquiryReadEvent
→ Response: { success: true }

Liệt Kê Yêu Cầu

GET /inquiries/listing/:id or /agent/me
→ Controller xác thực JWT (+ AGENT cho /agent/me)
→ Truy vấn được gửi đi
→ Handler xử lý phân trang
→ Repository thực thi truy vấn phân trang
→ Response: PaginatedResult<InquiryReadDto>

---

🔑 CÁC KHÁI NIỆM CHÍNH

DDD (Thiết Kế Hướng Miền)

• Domain Entity: InquiryEntity đóng gói logic yêu cầu
• Domain Events: InquiryCreatedEvent, InquiryReadEvent
• Repository Pattern: Giao diện ở tầng domain, triển khai ở tầng infrastructure
• Aggregate Root: InquiryEntity quản lý các chuyển đổi trạng thái

CQRS (Phân Tách Trách Nhiệm Lệnh - Truy Vấn)

• Commands: CreateInquiryCommand, MarkInquiryReadCommand (thao tác ghi)
• Queries: GetInquiriesByListingQuery, GetInquiriesByAgentQuery (thao tác đọc)
• Handlers: Các lớp riêng biệt cho từng lệnh/truy vấn

Các Tầng Clean Architecture

1. Presentation: Điểm cuối HTTP, DTO, decorator
2. Application: Lệnh/Truy vấn, trình xử lý, điều phối
3. Domain: Logic nghiệp vụ, entity, sự kiện, giao diện
4. Infrastructure: Cơ sở dữ liệu, triển khai lưu trữ

---

🧪 ĐỘ PHỦ KIỂM THỬ

Tổng cộng: 24 kiểm thử trên 6 bộ kiểm thử

Bộ kiểm thử	Kiểm thử	Trọng tâm
Domain Entity	5	Hành vi aggregate, sự kiện
CreateInquiryHandler	4	Luồng thành công, xác thực, sự kiện
MarkInquiryReadHandler	5	Luồng thành công, xác thực, lỗi
GetInquiriesByListingHandler	2	Phân trang, kết quả rỗng
GetInquiriesByAgentHandler	2	Kết quả, tra cứu agent
InquiriesController	6	Tất cả endpoint, giá trị mặc định

---

🔐 Bảo Mật

Xác thực: Tất cả endpoint yêu cầu token JWT
Phân quyền: RBAC với vai trò AGENT cho các endpoint nhất định

Ma Trận Bảo Mật Endpoint

Endpoint	Xác thực	Vai trò	Kiểm tra thêm
POST /inquiries	JWT	Bất kỳ	Listing tồn tại
GET /listing/:id	JWT	Bất kỳ	-
GET /agent/me	JWT	AGENT	-
PATCH /:id/read	JWT	AGENT	Agent sở hữu listing

---

📡 HỢP ĐỒNG API

POST /inquiries

Request:  { listingId: string, message: string, phone?: string }
Response: { id: string, listingId: string, createdAt: string }
Status:   201 | 400 | 401 | 404

GET /inquiries/listing/:listingId

Query:    { page?: number, limit?: number }
Response: PaginatedResult<InquiryReadDto>
Status:   200 | 401

GET /inquiries/agent/me

Query:    { page?: number, limit?: number }
Response: PaginatedResult<InquiryReadDto>
Status:   200 | 401 | 403

PATCH /inquiries/:id/read

Response: { success: boolean }
Status:   200 | 401 | 403 | 404

---

🚀 BẮT ĐẦU

Để Hiểu Mã Nguồn

1. Đọc Quick Reference (5 phút)
2. Xem lại Request Flows (5 phút)
3. Khám phá các tầng cụ thể trong Exploration khi cần

Để Thêm Tính Năng

1. Xem File Index → Mục Entry Points (2 phút)
2. Làm theo hướng dẫn sửa đổi (thời gian khác nhau)
3. Kiểm tra các kiểm thử hiện có để học theo mẫu

Để Gỡ Lỗi

1. Xác định tầng (presentation/application/domain/infrastructure)
2. Tìm tệp trong File Index
3. Kiểm tra kiểm thử để biết hành vi mong đợi

---

📋 CÁC MẪU PHỔ BIẾN

Thêm một Command

1. Tạo application/commands/[name]/[name].command.ts
2. Tạo application/commands/[name]/[name].handler.ts
3. Triển khai ICommandHandler<YourCommand>
4. Đăng ký trong mảng CommandHandlers của inquiries.module.ts
5. Thêm kiểm thử vào application/__tests__/

Thêm một Query

1. Tạo application/queries/[name]/[name].query.ts
2. Tạo application/queries/[name]/[name].handler.ts
3. Triển khai IQueryHandler<YourQuery>
4. Đăng ký trong mảng QueryHandlers của inquiries.module.ts
5. Thêm kiểm thử vào application/__tests__/

Thêm một Endpoint

1. Thêm phương thức vào InquiriesController
2. Thêm DTO nếu cần vào presentation/dto/
3. Gửi command/query qua bus
4. Thêm kiểm thử vào presentation/__tests__/

---

🔗 PHỤ THUỘC BÊN NGOÀI

Cốt lõi:

• @nestjs/common - Framework
• @nestjs/cqrs - CQRS bus
• @prisma/client - ORM

Xác thực:

• class-validator - Xác thực DTO
• class-transformer - Chuyển đổi kiểu

Tài liệu:

• @nestjs/swagger - Tài liệu OpenAPI

Nội bộ:

• @modules/shared - AggregateRoot, exceptions
• @modules/auth - JWT guards, decorators

---

📈 CHỈ SỐ CHẤT LƯỢNG

Khía cạnh	Đánh giá	Ghi chú
Kiến trúc	⭐⭐⭐⭐⭐	DDD + CQRS sạch
Tổ chức	⭐⭐⭐⭐⭐	Phân tách tầng rõ ràng
An toàn kiểu	⭐⭐⭐⭐⭐	TypeScript đầy đủ
Kiểm thử	⭐⭐⭐⭐☆	24 kiểm thử, chiều sâu tốt
Xác thực	⭐⭐⭐⭐⭐	RBAC đúng chuẩn
Khả năng bảo trì	⭐⭐⭐⭐⭐	Dễ mở rộng

---

💡 ĐIỂM NỔI BẬT VỀ KIẾN TRÚC

✅ Phân tách mối quan tâm - Mỗi tầng có trách nhiệm đơn lẻ
✅ Đảo ngược phụ thuộc - Phụ thuộc vào trừu tượng, không phải triển khai cụ thể
✅ Hướng sự kiện - Sự kiện miền cho ý nghĩa nghiệp vụ
✅ CQRS - Luồng đọc/ghi tách biệt và có thể tối ưu hóa
✅ An toàn kiểu - TypeScript đầy đủ, không có kiểu any
✅ Khả năng kiểm thử - Tất cả tầng có thể kiểm thử độc lập
✅ Khả năng mở rộng - Dễ thêm command/query mới

---

🎓 LỘ TRÌNH HỌC TẬP

Người mới bắt đầu: Đọc Quick Reference → Hiểu các tầng → Xem controller
Trung cấp: Nghiên cứu các handler → Xem lại entity → Kiểm tra kiểm thử
Nâng cao: Đi sâu vào event sourcing → Phân trang → Các mẫu tối ưu hóa

---

📞 LIÊN KẾT THAM CHIẾU NHANH

Trong các tệp tài liệu:

Quick Reference:

• Các tệp theo tầng
• Luồng yêu cầu
• Ma trận phân quyền
• Điểm vào để thay đổi

File Index:

• Mô tả tệp đầy đủ
• Đồ thị phụ thuộc
• Tham chiếu chéo
• Hướng dẫn sửa đổi

Exploration:

• Sơ đồ kiến trúc
• Các mẫu thiết kế
• Chi tiết bảo mật
• Phân tích độ phủ kiểm thử

---

✨ Bước Tiếp Theo

1. Đọc Quick Reference để định hướng
2. Chọn tệp tài liệu phù hợp với nhu cầu của bạn
3. Dùng hướng dẫn khám phá để tìm thông tin cụ thể
4. Làm theo hướng dẫn sửa đổi khi thực hiện thay đổi
5. Kiểm tra kiểm thử để biết hành vi mong đợi

---

Khám phá vui vẻ! 🚀

Ngày tạo: 11 tháng 4, 2026
Trạng thái tài liệu: ✅ Hoàn chỉnh