Prompt Khám Phá Mã Nguồn Kỹ Thuật & Hội Nhập Dự Án (Onboarding)

**Ngữ cảnh:**  
Tôi là một lập trình viên vừa mới gia nhập dự án và tôi đang sử dụng bạn, một trợ lý lập trình AI, để nắm bắt sâu sắc kho mã nguồn hiện có. Mục tiêu của tôi là bắt nhịp công việc đạt năng suất cao nhanh nhất có thể và đưa ra các quyết định kỹ thuật sáng suốt dựa trên sự am hiểu vững chắc về hệ thống hiện tại.

**Mục tiêu Chính:**  
Phân tích mã nguồn được cung cấp trong dự án/không gian làm việc (workspace) này và tạo ra một **tài liệu Markdown chi tiết, rõ ràng và có cấu trúc chặt chẽ** giải thích kiến trúc của hệ thống, các tính năng, luồng hoạt động chính, thành phần cốt lõi và ngăn xếp công nghệ (technology stack).  
Tài liệu này sẽ đóng vai trò như một **cẩm nang hướng dẫn hội nhập kỹ thuật (technical onboarding guide)**.  
Bất cứ khi nào có thể, hãy nâng cao khả năng điều hướng tra cứu bằng cách cung cấp **các liên kết trực tiếp đến các tệp, lớp (classes) và hàm có liên quan**, cũng như các ví dụ mã nguồn giúp làm sáng tỏ các khái niệm.

---

## **Hướng Dẫn Chi Tiết — Vui lòng giải quyết đầy đủ các điểm sau:**

### 1. **Tóm Tắt Các Tệp README / Hướng Dẫn**
- Tìm kiếm các tệp như `README.md`, `LEIAME.md`, `CONTRIBUTING.md`, hoặc các tài liệu tương tự.
- Cung cấp bản tóm tắt khách quan nhưng chi tiết về những phần quan trọng nhất đối với một lập trình viên mới, bao gồm:
  - Tổng quan về dự án
  - Cách thiết lập và chạy hệ thống trên máy cục bộ
  - Các tiêu chuẩn và quy ước đang được áp dụng
  - Nguyên tắc đóng góp mã nguồn (nếu có)

---

### 2. **Ngăn Xếp Công Nghệ Chi Tiết (Detailed Technology Stack)**
- Xác định và liệt kê toàn bộ ngăn xếp công nghệ được sử dụng trong dự án:
  - (Các) ngôn ngữ lập trình, bao gồm cả phiên bản khi có thể phát hiện được (ví dụ: từ `package.json`, `pom.xml`, `.tool-versions`, `requirements.txt`, `build.gradle`, v.v.).
  - Các framework chính (backend, frontend, v.v. — ví dụ: Spring Boot, .NET, React, Angular, Vue, Django, Rails).
  - (Các) cơ sở dữ liệu:
    - Loại (SQL / NoSQL)
    - Tên (PostgreSQL, MongoDB, v.v.)
  - Phong cách kiến trúc cốt lõi (ví dụ: Nguyên khối - Monolith, Vi dịch vụ - Microservices, Serverless, MVC, MVVM, Clean Architecture).
  - Nền tảng đám mây (nếu nhận diện được qua các SDK hoặc tệp cấu hình — AWS, Azure, GCP).
  - Công cụ biên dịch (build tools) và trình quản lý gói (Maven, Gradle, npm, yarn, pip).
  - Bất kỳ công nghệ có liên quan nào khác (bộ nhớ đệm - caching, hệ thống hàng đợi thông điệp - message brokers, container hóa — Docker, Kubernetes).
- **Tham chiếu và gắn liên kết tới các tệp cấu hình chứng minh cho từng hạng mục.**

---

### 3. **Tổng Quan Hệ Thống và Mục Đích**
- Mô tả rõ ràng hệ thống này làm gì và phục vụ đối tượng nào.
- Hệ thống giải quyết những bài toán/vấn đề gì?
- Liệt kê các chức năng cốt lõi.
- Nếu có thể, hãy liên hệ hệ thống với các miền nghiệp vụ (business domains) có liên quan.
- Cung cấp mô tả tổng quan ở cấp độ cao về các tính năng chính.

---

### 4. **Cấu Trúc Dự Án và Khuyến Nghị Đọc Hiểu**
- **Điểm Khởi Đầu (Entry Point):**  
  Tôi nên bắt đầu khám phá mã nguồn từ đâu? Xác định các điểm vào chính của chương trình (ví dụ: `main.go`, `index.js`, `Program.cs`, `app.py`, `Application.java`).  
  **Cung cấp liên kết trực tiếp đến các tệp này.**
- **Tổ Chức Tổng Thể:**  
  Giải thích cấu trúc thư mục và tệp tổng thể. Làm nổi bật các quy ước quan trọng.  
  **Sử dụng các ví dụ tên thư mục và tên tệp thực tế trong dự án.**
- **Cấu Hình:**  
  Có các tệp cấu hình chính nào không? (ví dụ: `config.yaml`, `.env`, `appsettings.json`)  
  Những thông số cấu hình nào là tối quan trọng?  
  **Cung cấp các liên kết.**
- **Khuyến Nghị Lộ Trình Đọc Mã:**  
  Đề xuất thứ tự đọc hoặc một tập hợp các tệp/mô-đun then chốt nên được đọc trước tiên để nhanh chóng nắm bắt các khái niệm cốt lõi của dự án.

---

### 5. **Các Thành Phần Cốt Lõi (Key Components)**
- Xác định và mô tả các mô-đun, lớp (classes), hàm hoặc dịch vụ quan trọng nhất hay giữ vai trò trung tâm.
- Giải thích trách nhiệm của từng thành phần.
- Mô tả trách nhiệm cũng như sự phụ thuộc lẫn nhau giữa chúng.
- Đối với mỗi thành phần:
  - Đưa vào một đoạn mã nguồn tiêu biểu (code snippet)
  - Cung cấp liên kết đến nơi thành phần đó được triển khai
- **Cung cấp liên kết trực tiếp và ví dụ mã nguồn bất cứ khi nào có thể.**

---

### 6. **Luồng Thực Thi và Luồng Dữ Liệu**
- Mô tả các luồng công việc (workflows) hoặc quy trình nghiệp vụ phổ biến nhất hay quan trọng nhất (ví dụ: xử lý đơn hàng, xác thực người dùng).
- Giải thích cách dữ liệu di chuyển xuyên suốt hệ thống:
  - Dữ liệu được lưu trữ lâu dài (persisted) ở đâu
  - Dữ liệu được đọc, sửa đổi và lan truyền như thế nào
- **Bất cứ khi nào có thể, hãy minh họa bằng các ví dụ và gắn liên kết tới các hàm hoặc lớp có liên quan.**

#### 6.1 **Tổng Quan Lược Đồ Cơ Sở Dữ Liệu (nếu áp dụng)**
- Đối với các ứng dụng xử lý nhiều dữ liệu:
  - Xác định các thực thể (entities)/bảng (tables)/bộ sưu tập (collections) chính
  - Mô tả các mối quan hệ chính giữa chúng
  - Dựa trên các mô hình ORM, tệp di trú dữ liệu (migrations), hoặc tệp định nghĩa lược đồ (schema files) nếu có sẵn

---

### 7. **Các Thư Viện Phụ Thuộc và Tích Hợp Bên Ngoài**
- **Thư viện Phụ thuộc (Dependencies):**  
  Liệt kê các thư viện bên ngoài, framework và SDK chính được sử dụng.  
  Giải thích ngắn gọn vai trò của từng thư viện.  
  **Cung cấp liên kết đến nơi chúng được cấu hình hoặc được sử dụng phổ biến nhất.**
- **Tích hợp (Integrations):**  
  Xác định và giải thích các điểm tích hợp với dịch vụ bên ngoài, cơ sở dữ liệu bổ sung, API của bên thứ ba, message brokers, v.v.  
  Việc giao tiếp diễn ra như thế nào?  
  **Chỉ rõ các mô-đun/lớp chịu trách nhiệm và đính kèm liên kết.**

#### 7.1 **Tài Liệu API (nếu áp dụng)**
- Nếu dự án có cung cấp các API:
  - Có bằng chứng nào về việc sử dụng các công cụ hoặc tiêu chuẩn tài liệu hóa API không (ví dụ: Swagger/OpenAPI, Javadoc, docstring riêng cho từng điểm cuối)?
  - Có thể tìm thấy tài liệu này ở đâu hoặc làm thế nào để sinh ra nó?

---

### 8. **Sơ Đồ (Diagrams)**
- Tạo các sơ đồ ở cấp độ cao để trực quan hóa kiến trúc và hành vi của hệ thống:
  - Sơ đồ thành phần (Component diagram - làm nổi bật các mô-đun chính và sự tương tác giữa chúng)
  - Sơ đồ luồng dữ liệu (Data flow diagram - hiển thị cách thông tin di chuyển qua hệ thống)
  - Sơ đồ lớp (Class diagram - hiển thị các lớp chính và mối quan hệ, nếu áp dụng)
  - Sơ đồ triển khai rút gọn (Simplified deployment diagram - nơi các thành phần chạy thực thi, nếu phát hiện được)
  - Sơ đồ hạ tầng/triển khai rút gọn (nếu các chi tiết về hạ tầng thể hiện rõ ràng)
- **Tạo các sơ đồ này bằng cú pháp Mermaid ngay bên trong tệp Markdown.**
- Các sơ đồ nên ở **cấp độ tổng quan cao (high-level)**; không bắt buộc phải đi vào chi tiết quá vụn vặt.

---

### 9. **Kiểm Thử (Testing)**
- Dự án có các bài kiểm thử tự động không?
  - Kiểm thử đơn vị (Unit tests)
  - Kiểm thử tích hợp (Integration tests)
  - Kiểm thử đầu-cuối (End-to-end / E2E tests)
- Chúng nằm ở đâu trong dự án?
- (Các) framework kiểm thử nào đang được sử dụng?
- Các bài kiểm thử thường được thực thi như thế nào?
- Làm thế nào để chạy kiểm thử trên máy cục bộ?
- Có chiến lược CI/CD nào liên quan đến việc chạy kiểm thử không?

---

### 10. **Xử Lý Lỗi và Ghi Nhật Ký (Error Handling and Logging)**
- Ứng dụng thường xử lý lỗi như thế nào?
  - Có tuân theo một khuôn mẫu chuẩn nào không (ví dụ: middleware toàn cục, các lớp ngoại lệ tùy chỉnh - custom exceptions)?
- Thư viện ghi nhật ký (logging) nào đang được sử dụng?
- Có định dạng ghi nhật ký tiêu chuẩn nào không?
- Có dấu hiệu tích hợp rõ ràng với các công cụ giám sát (monitoring tools) nào không (ví dụ: Datadog, Sentry)?

---

### 11. **Các Cân Nhắc Về Bảo Mật**
- Có các cơ chế bảo mật hiển hiện rõ trong mã nguồn không?
  - Xác thực (Authentication)
  - Phân quyền (Authorization - middleware/bộ lọc)
  - Xác thực dữ liệu đầu vào (Input validation)
- Có các thư viện bảo mật cụ thể nào được sử dụng nổi bật không (ví dụ: Spring Security, Passport.js, các thư viện JWT)?
- Có các thực hành bảo mật đáng chú ý nào không?
  - Quản lý thông tin bí mật (Secrets management)
  - Bảo vệ chống lại các cuộc tấn công phổ biến

---

### 12. **Các Quan Sát Liên Quan Khác (Bao Gồm Biên Dịch/Triển Khai)**
- Có các tệp liên quan đến quá trình **biên dịch (build) hoặc triển khai (deployment)** không?
  - `Dockerfile`
  - `docker-compose.yml`
  - Các kịch bản build/deploy
  - Các tệp cấu hình CI/CD (ví dụ: `.github/workflows/`, `.gitlab-ci.yml`)
- Những tệp này cho biết điều gì về cách ứng dụng được biên dịch và triển khai?
- Còn điều gì khác tối quan trọng hoặc đặc biệt hữu ích cho một lập trình viên mới không?
  - Nợ kỹ thuật (technical debt) đã biết được đề cập trong các dòng chú thích
  - Các mẫu thiết kế (design patterns) khác thường
  - Các quy ước viết mã quan trọng
  - Các ghi chú về hiệu năng

---

## **Định Dạng Đầu Ra Cuối Cùng**
- Tạo toàn bộ câu trả lời dưới dạng một **tài liệu Markdown (`.md`) được định dạng chuẩn chỉnh**.
- Sử dụng **ngôn ngữ rõ ràng và trực diện**.
- Tổ chức nội dung bằng **các tiêu đề chính và tiêu đề phụ** bám sát theo các phần đánh số ở trên.
- **Đưa vào các đoạn mã nguồn có liên quan** (ngắn gọn và mang tính đại diện).
- **Đưa vào các liên kết có thể nhấp (clickable links)** trỏ tới các tệp, hàm, lớp và định nghĩa bất cứ khi nào một phần tử mã nguồn cụ thể được nhắc tới.
- Cấu trúc tài liệu theo đúng các phần đánh số ở trên để dễ đọc.

**Bất cứ khi nào có thể:**
- Đính kèm **các liên kết có thể nhấp** trỏ tới tệp, hàm và lớp.
- Hiển thị **các đoạn mã nguồn ngắn gọn, tiêu biểu**.
- Sử dụng **danh sách gạch đầu dòng hoặc bảng biểu** cho các mục liệt kê.

---

### **QUAN TRỌNG**
Quá trình phân tích bắt buộc phải xem xét **TẤT CẢ các tệp trong dự án**.  
Hãy đọc và hiểu **tất cả các tệp cần thiết** để thực thi trọn vẹn nhiệm vụ này và đạt được sự thấu hiểu toàn diện về hệ thống.

---

### **Hành Động**
Vui lòng phân tích mã nguồn hiện có trong môi trường/không gian làm việc của tôi và tạo tài liệu Markdown theo đúng yêu cầu.

Tên tệp đầu ra bắt buộc phải tuân theo định dạng này:  
`<yyyy-mm-dd-project-name-app-dev-discovery_cursor.md>`