Files
goodgo-platform/docs/audits/ADMIN_AUDIT_INDEX.md
Ho Ngoc Hai 11f2bf26e6
Some checks failed
CI / Lint → Typecheck → Test → Build (22) (push) Failing after 29s
CI / E2E Tests (push) Has been skipped
CodeQL Analysis / CodeQL (javascript-typescript) (push) Failing after 2m42s
Deploy / Build Web Image (push) Failing after 27s
Deploy / Build AI Services Image (push) Failing after 29s
E2E Tests / Playwright E2E (push) Failing after 43s
Deploy / Build API Image (push) Failing after 1m31s
Security Scanning / Dependency Audit (pnpm) (push) Failing after 6s
Security Scanning / Trivy Scan — API Image (push) Failing after 5m35s
Security Scanning / Trivy Scan — AI Services Image (push) Failing after 3m45s
Deploy / Deploy to Staging (push) Has been skipped
Deploy / Smoke Test Staging (push) Has been skipped
Deploy / Deploy to Production (push) Has been skipped
Deploy / Smoke Test Production (push) Has been skipped
Deploy / Rollback Staging (push) Has been skipped
Deploy / Rollback Production (push) Has been skipped
Security Scanning / Trivy Scan — Web Image (push) Failing after 13m51s
Security Scanning / Trivy Filesystem Scan (push) Failing after 14m46s
Security Scanning / Security Gate (push) Has been cancelled
chore: update project documentation, audit reports, and initialize IDE configuration files
2026-04-19 03:12:54 +07:00

439 lines
17 KiB
Markdown

# Ghi nhật ký kiểm tra mô-đun quản trị GoodGo Platform - Chỉ mục tài liệu đầy đủ
## 📋 Điều hướng nhanh
Khám phá toàn diện này bao gồm **3 tài liệu chi tiết** với tổng cộng ~61KB phân tích.
### Tài liệu 1: **ADMIN_AUDIT_EXPLORATION.md** (24KB)
**Mục đích**: Phân tích toàn bộ codebase và đánh giá trạng thái hiện tại
**Nội dung:**
- Cấu trúc thư mục đầy đủ của mô-đun quản trị
- Phân tích schema Prisma (các mô hình User, Listing - chưa tìm thấy mô hình audit)
- Tất cả 8 endpoint của controller quản trị với thông tin chi tiết chính xác
- Phân tích cơ sở hạ tầng sự kiện/ghi nhật ký hiện có
- Tài liệu về dịch vụ Logger với tính năng che giấu PII
- Xử lý ngoại lệ và các mẫu bộ lọc lỗi
- Triển khai bảo mật & RBAC
- Giải thích đầy đủ cấu trúc lớp DDD
- Cấu hình khởi động mô-đun
- Tóm tắt những gì đã có sẵn so với những gì cần xây dựng
**Điểm mấu chốt:**
- 13+ endpoint hành động quản trị đã thu thập ID quản trị viên từ JWT
- 7 sự kiện miền đã được các command handler phát hành
- Kiến trúc hướng sự kiện đã có sẵn (NestJS CQRS)
- Logger Pino với tính năng che giấu PII khả dụng
- Mẫu Repository đã được thiết lập và ghi chép
- Chưa có ghi nhật ký audit nào - cơ hội greenfield
**Thời gian đọc:** 15-20 phút
---
### Tài liệu 2: **ADMIN_AUDIT_QUICK_FILES.md** (9KB)
**Mục đích**: Hướng dẫn tham khảo nhanh các tệp quan trọng và danh sách kiểm tra triển khai
**Nội dung:**
- Thứ tự đọc tệp được ưu tiên (cần đọc trước)
- Số dòng chính xác cho các vị trí quan trọng
- Danh sách endpoint controller chính
- Sơ đồ luồng command handler
- Danh sách sự kiện miền
- Mẫu listener hiện có như template
- Tham khảo nhanh dịch vụ Logger
- Tham chiếu kiến trúc (mẫu repository, khởi động mô-đun, cài đặt ứng dụng)
- Vị trí schema Prisma
- Danh sách audit endpoint đầy đủ
- Các phụ thuộc đã có sẵn trong mô-đun
- Danh sách kiểm tra triển khai từng bước (5 giai đoạn)
- Các mẫu quan trọng cần tuân theo
- Cấu trúc tệp cho các bổ sung code mới
- Danh sách sự kiện cần lắng nghe
**Thời gian đọc:** 5-10 phút
**Phù hợp nhất:** Tra cứu nhanh trong quá trình triển khai
---
### Tài liệu 3: **ADMIN_AUDIT_ARCHITECTURE.md** (28KB)
**Mục đích**: Thiết kế kiến trúc đầy đủ và hướng dẫn triển khai
**Nội dung:**
- Tổng quan thiết kế hệ thống với sơ đồ ASCII
- Trình tự luồng dữ liệu với các chuyển đổi trạng thái
- **Bổ sung schema Prisma đầy đủ** (enum + mô hình AuditLog)
- Triển khai mẫu repository đầy đủ
- Định nghĩa interface miền
- Triển khai Prisma với các truy vấn
- Triển khai event listener với các handler cho tất cả 7 sự kiện
- Query handler để lấy nhật ký audit
- Code endpoint của controller
- Đăng ký dependency injection trong mô-đun
- Ví dụ unit test
- Ví dụ integration test
- Chiến lược kiểm thử
**Các phần chính:**
1. Sơ đồ ASCII trực quan về luồng dữ liệu
2. Code mô hình Prisma chính xác (sẵn sàng để sao chép-dán)
3. Interface và triển khai Repository
4. Handler listener cho tất cả sự kiện quản trị
5. Bổ sung Query và Controller
6. Code đăng ký mô-đun
7. Ví dụ kiểm thử đầy đủ
**Thời gian đọc:** 20-30 phút
**Phù hợp nhất:** Tham chiếu triển khai và kiểm thử
---
## 🎯 Thứ tự đọc được khuyến nghị
### Để hiểu ban đầu (30 phút)
1. **ADMIN_AUDIT_QUICK_FILES.md** - Tổng quan và vị trí tệp (5 phút)
2. **ADMIN_AUDIT_EXPLORATION.md** Phần 1-4 - Hiểu cấu trúc và mẫu (15 phút)
3. **ADMIN_AUDIT_ARCHITECTURE.md** - Xem luồng dữ liệu và thiết kế (10 phút)
### Để triển khai (2-3 giờ)
1. Đọc **ADMIN_AUDIT_ARCHITECTURE.md** hoàn toàn
2. Tham khảo danh sách kiểm tra **ADMIN_AUDIT_QUICK_FILES.md**
3. Sử dụng **ADMIN_AUDIT_EXPLORATION.md** để biết chi tiết về mẫu khi cần
### Để gỡ lỗi (Khi cần)
- Sử dụng **ADMIN_AUDIT_QUICK_FILES.md** để tìm vị trí tệp chính xác
- Sử dụng **ADMIN_AUDIT_EXPLORATION.md** để hiểu các mẫu hiện có
- Sử dụng **ADMIN_AUDIT_ARCHITECTURE.md** để xác minh các mẫu triển khai
---
## 🗂️ Cấu trúc dự án tổng quan
```
GoodGo Admin Module (modules/admin/)
├── Domain Layer (domain/)
│ ├── Events (7 existing events - user/listing/kyc/subscription)
│ └── Repositories (query interfaces)
├── Application Layer (application/)
│ ├── Commands (8 handlers - ban, approve, reject, adjust)
│ ├── Queries (6 handlers - stats, queues, users, revenue)
│ └── Listeners (2 existing + 1 to add for audit)
├── Infrastructure Layer (infrastructure/)
│ └── Repositories (Prisma implementations)
└── Presentation Layer (presentation/)
├── Controllers (2 controllers with 12 endpoints)
└── DTOs (input validation)
Database (PostgreSQL 16 + PostGIS)
├── User model (has isActive, kycStatus, role)
├── Listing model (has status, moderationScore)
└── [TO ADD] AuditLog model
```
---
## 🔑 Phát hiện quan trọng
### ✅ Đã triển khai
1. **Ghi nhận danh tính quản trị viên** - Tất cả hành động có @CurrentUser() để lấy ID quản trị viên
2. **Phát hành sự kiện** - Các command phát hành sự kiện miền
3. **Mẫu Event Listener** - UserBannedListener hiển thị template
4. **Dịch vụ Logger** - Pino với tính năng che giấu PII
5. **Xử lý ngoại lệ** - Bộ lọc toàn cục + ngoại lệ miền
6. **Mẫu Repository** - Mô-đun Admin hiển thị sự phân tách rõ ràng giữa interface/triển khai
7. **CQRS Module** - CqrsModule.forRoot() trong app.module.ts
8. **Hệ thống DI** - Mẫu token dựa trên Symbol rõ ràng
### ❌ Chưa triển khai
1. **Mô hình Prisma AuditLog** - Cần bảng cơ sở dữ liệu
2. **Audit Repository** - Interface + triển khai Prisma
3. **Audit Event Listener** - Để ghi nhận và lưu trữ sự kiện
4. **Query Handler** - Để lấy nhật ký audit
5. **Endpoint Controller** - GET /admin/audit-logs
6. **Ghi nhận ngữ cảnh HTTP** - Địa chỉ IP, user agent (cải tiến tùy chọn)
### 📊 Phạm vi triển khai
- **Tệp mới cần tạo**: 6-8 tệp
- **Tệp cần chỉnh sửa**: 3-4 tệp (schema.prisma, admin.module.ts, controllers)
- **Thời gian ước tính**: 4-8 giờ triển khai + 2 giờ kiểm thử
- **Độ phức tạp**: Trung bình (mẫu đơn giản, tuân theo các quy ước hiện có)
---
## 🚀 Mỗi tài liệu cung cấp gì
### ADMIN_AUDIT_EXPLORATION.md
**Sử dụng để:**
- Hiểu kiến trúc dự án
- Tìm hiểu các mẫu hiện có
- Hiểu cấu trúc lớp DDD
- Hiểu khởi động mô-đun
**Các phần chính:**
1. Cấu trúc mô-đun Admin - Phân tích thư mục đầy đủ
2. Phân tích schema Prisma - Các mô hình hiện tại và những gì còn thiếu
3. Hành động và luồng Controller quản trị - Chi tiết tất cả 12 endpoint
4. Cơ sở hạ tầng sự kiện/ghi nhật ký hiện có - Sự kiện và listener
5. Dịch vụ Logger - Cấu hình và cách sử dụng Pino
6. Xử lý ngoại lệ & Bộ lọc - Các mẫu xử lý lỗi
7. Bảo mật & Guards - Triển khai RBAC
8. Cấu trúc lớp DDD - Giải thích các Command/Query handler
9. Khởi động mô-đun - Cách admin.module.ts hoạt động
10. Các mẫu Interceptor hiện có - HttpMetricsInterceptor, CSRF middleware
11. Tóm tắt cho triển khai ghi nhật ký Audit - Những gì đã có so với những gì cần thiết
---
### ADMIN_AUDIT_QUICK_FILES.md
**Sử dụng để:**
- Tra cứu vị trí tệp nhanh
- Hiểu luồng command handler
- Tham chiếu template event listener
- Danh sách kiểm tra giai đoạn triển khai
- Cấu trúc tệp cho code mới
**Các phần chính:**
1. Phải đọc trước - 6 tệp quan trọng hàng đầu
2. Tham chiếu kiến trúc - Các mẫu cần tuân theo
3. Schema Prisma - Vị trí các thành phần
4. Các endpoint cần audit chính xác - Liệt kê tất cả 8 endpoint
5. Các phụ thuộc đã được nhập - Những gì khả dụng
6. Danh sách kiểm tra triển khai - 5 giai đoạn với các nhiệm vụ
7. Các mẫu quan trọng cần tuân theo - 4 mẫu chính
8. Nơi thêm code - Cấu trúc tệp
9. Sự kiện cần lắng nghe - Tất cả 8 sự kiện
---
### ADMIN_AUDIT_ARCHITECTURE.md
**Sử dụng để:**
- Hiểu kiến trúc chi tiết
- Code triển khai chính xác
- Thiết kế schema cơ sở dữ liệu
- Ví dụ kiểm thử
**Các phần chính:**
1. Tổng quan thiết kế hệ thống - Sơ đồ ASCII lớn về luồng đầy đủ
2. Trình tự luồng dữ liệu - Luồng sự kiện từ yêu cầu đến cơ sở dữ liệu
3. Bổ sung schema Prisma - **Sẵn sàng để sao chép-dán**
4. Lớp Repository - Code interface và triển khai
5. Triển khai Event Listener - Handler cho tất cả sự kiện
6. Query Handler để lấy dữ liệu - Lấy nhật ký audit
7. Endpoint Controller - GET /admin/audit-logs
8. Đăng ký DI - Code cài đặt mô-đun
9. Chiến lược kiểm thử - Unit và integration test
---
## 📝 Ví dụ code quan trọng có sẵn
### Trong ADMIN_AUDIT_ARCHITECTURE.md
**Sẵn sàng để sử dụng:**
1. **Schema Prisma** (dòng ~100-150)
- Mô hình AuditLog với tất cả các trường
- Enum AdminAction, AuditResourceType, AuditStatus
- Index cho hiệu suất
2. **Interface Repository** (dòng ~160-200)
- Interface IAuditLogRepository
- Interface CreateAuditLogDto
- Interface FindAuditLogsParams
3. **Triển khai Repository** (dòng ~210-260)
- Class PrismaAuditLogRepository
- Phương thức create()
- findMany() với bộ lọc
- Truy vấn theo phạm vi ngày
4. **Event Listener** (dòng ~270-330)
- Class AuditLoggingListener
- Handler @OnEvent() cho tất cả 7 sự kiện
- Xử lý lỗi
5. **Query Handler** (dòng ~340-360)
- Class GetAuditLogsQuery
- Triển khai GetAuditLogsHandler
6. **Endpoint Controller** (dòng ~370-395)
- Endpoint @Get('audit-logs')
- Tham số truy vấn với tài liệu Swagger
7. **Đăng ký DI** (dòng ~400-430)
- Cài đặt provider AdminModule
8. **Ví dụ kiểm thử** (dòng ~440-500)
- Ví dụ unit test
- Ví dụ integration test
---
## 🔗 Tham chiếu chéo giữa các tài liệu
### EXPLORATION → QUICK FILES
- Phần 1 EXPLORATION (Cấu trúc mô-đun Admin) được tóm tắt trong "MUST READ FIRST" của QUICK FILES
- Phần 3 EXPLORATION (Hành động Controller) được chi tiết trong "EXACT ENDPOINTS TO AUDIT" của QUICK FILES
### QUICK FILES → ARCHITECTURE
- Vị trí tệp của QUICK FILES được tham chiếu trong "WHERE TO ADD CODE" của ARCHITECTURE
- Danh sách sự kiện của QUICK FILES khớp với các handler listener trong ARCHITECTURE
### ARCHITECTURE → EXPLORATION
- Các mẫu ARCHITECTURE tuân theo các quy ước từ Phần 8 EXPLORATION (Cấu trúc lớp DDD)
- Cài đặt DI của ARCHITECTURE khớp với mẫu từ Phần 9 EXPLORATION (Khởi động mô-đun)
---
## 💡 Mẹo hữu ích
1. **Bắt đầu với QUICK_FILES** - Tổng quan 5 phút trước khi đi sâu
2. **Sử dụng EXPLORATION như tài liệu tham khảo** - Đánh dấu Phần 3 (Controllers) và Phần 8 (DDD)
3. **Sao chép từ ARCHITECTURE** - Hầu hết code đã sẵn sàng để dán với các điều chỉnh tối thiểu
4. **Tuân theo danh sách kiểm tra** - QUICK_FILES có danh sách kiểm tra 5 giai đoạn khớp với các phần của ARCHITECTURE
5. **Đối sánh mẫu** - AuditLoggingListener trong ARCHITECTURE phản chiếu UserBannedListener hiện có
6. **Template kiểm thử** - ARCHITECTURE có ví dụ unit và integration test
---
## 🎓 Lộ trình học tập
### Người mới bắt đầu (Chỉ muốn tổng quan)
1. Phần "MUST READ FIRST" của QUICK_FILES (5 phút)
2. "System Design Overview" trong ARCHITECTURE (10 phút)
3. Tổng cộng: 15 phút
### Trung cấp (Muốn hiểu cấu trúc)
1. QUICK_FILES (10 phút)
2. Phần 1, 2, 3 của EXPLORATION (20 phút)
3. "Data Flow Sequence" trong ARCHITECTURE (10 phút)
4. Tổng cộng: 40 phút
### Nâng cao (Sẵn sàng triển khai)
1. Tất cả ba tài liệu theo thứ tự (60 phút)
2. Danh sách kiểm tra triển khai của QUICK_FILES (5 phút)
3. Bắt đầu code theo các phần code của ARCHITECTURE
---
## 📞 Liên kết tham chiếu nhanh
### Tên sự kiện cần lắng nghe
- 'user.banned' ← UserBannedEvent
- 'user.unbanned' ← UserUnbannedEvent
- 'listing.approved' ← ListingApprovedEvent
- 'listing.rejected' ← ListingRejectedEvent
- 'kyc.approved' ← KycApprovedEvent
- 'kyc.rejected' ← KycRejectedEvent
- 'subscription.adjusted' ← SubscriptionAdjustedEvent
### Các endpoint quản trị cần audit
1. PATCH /admin/users/status (UpdateUserStatusCommand)
2. POST /admin/users/ban (BanUserCommand)
3. POST /admin/subscriptions/adjust (AdjustSubscriptionCommand)
4. POST /admin/moderation/approve (ApproveListingCommand)
5. POST /admin/moderation/reject (RejectListingCommand)
6. POST /admin/moderation/bulk (BulkModerateListingsCommand)
7. POST /admin/kyc/approve (ApproveKycCommand)
8. POST /admin/kyc/reject (RejectKycCommand)
### Các tệp chính
- Controllers: `presentation/controllers/admin*.controller.ts`
- Events: `domain/events/*.event.ts`
- Listeners: `application/listeners/*.listener.ts`
- Handlers: `application/commands/*/handler.ts`
- Schema: `prisma/schema.prisma`
---
## 🏗️ Tóm tắt kiến trúc
```
HTTP Request
Controller (validate, extract admin ID from JWT)
CommandBus.execute(Command)
CommandHandler (business logic + publish event)
EventBus.publish(Event)
↓ branches to:
├─ UserBannedListener (existing - side effects)
└─ AuditLoggingListener (NEW - persist to database)
AuditLogRepository.create(AuditLog)
Prisma.auditLog.create()
PostgreSQL AuditLog table
Later:
GET /admin/audit-logs
QueryHandler
AuditLogRepository.findMany()
Return paginated results
```
---
## ✅ Danh sách kiểm tra xác minh
Sử dụng danh sách này để xác minh bạn đã đọc và hiểu mọi thứ:
- [ ] Đọc phần "MUST READ FIRST" của ADMIN_AUDIT_QUICK_FILES.md
- [ ] Đọc Phần 1-4 của ADMIN_AUDIT_EXPLORATION.md
- [ ] Xem lại sơ đồ "System Design Overview" của ADMIN_AUDIT_ARCHITECTURE.md
- [ ] Hiểu các endpoint hành động quản trị (12 endpoint được liệt kê)
- [ ] Xác định các sự kiện miền (7 sự kiện cần lắng nghe)
- [ ] Tìm mẫu listener hiện có (UserBannedListener)
- [ ] Tìm vị trí schema Prisma (prisma/schema.prisma)
- [ ] Hiểu mẫu repository (interface + triển khai Prisma)
- [ ] Thấy mẫu đăng ký DI (token dựa trên Symbol)
- [ ] Xem lại các mẫu endpoint controller (decorator @Get, @Post)
---
## 📚 Tổng tài liệu được cung cấp
- **3 tệp Markdown** (tổng ~61KB)
- **11+ phần chính** với giải thích chi tiết
- **Sơ đồ ASCII** để hiểu trực quan
- **Code sẵn sàng sử dụng** để triển khai ngay lập tức
- **Ví dụ kiểm thử** cho unit và integration test
- **Danh sách kiểm tra triển khai 5 giai đoạn**
- **Ánh xạ sự kiện** đến tên handler
- **Vị trí tệp** với số dòng khi áp dụng
- **Giải thích mẫu DDD** với ví dụ
- **Các mẫu cần tuân theo** với template code
---
## 🎯 Các bước tiếp theo
1. **Đọc ADMIN_AUDIT_QUICK_FILES.md** (5 phút)
2. **Xem lại ADMIN_AUDIT_EXPLORATION.md** (20 phút)
3. **Nghiên cứu ADMIN_AUDIT_ARCHITECTURE.md** (30 phút)
4. **Tuân theo danh sách kiểm tra triển khai** từ QUICK_FILES
5. **Sao chép ví dụ code** từ ARCHITECTURE
6. **Chạy kiểm thử** sử dụng ví dụ từ ARCHITECTURE
7. **Triển khai tự tin** - các mẫu đã được chứng minh trong codebase
---
Generated: 2026-04-10
Total Exploration Time: ~3 hours
Documentation Quality: Comprehensive with examples
Implementation Confidence: Very High (follows existing patterns)