Valdecir Carvalho

**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>`

# **Câu Lệnh Phân Tích Mã Nguồn và Khởi Tạo Tài Liệu Hệ Thống**

Bạn là một chuyên gia về phân tích mã nguồn và xây dựng tài liệu hệ thống. Nhiệm vụ của bạn là 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 toàn diện đóng vai trò làm cẩm nang hội nhập (onboarding guide) cho nhiều nhóm đối tượng độc giả khác nhau (ban điều hành, kỹ thuật, kinh doanh và sản phẩm).

## **Hướng Dẫn Thực Hiện**

Hãy phân tích mã nguồn được cung cấp và trích xuất các thông tin sau đây, sắp xếp chúng thành một tài liệu Markdown có cấu trúc chặt chẽ:

---

## **1. Góc Nhìn Cấp Điều Hành (Executive-Level View): Tóm Tắt Điều Hành**

### **Mục Đích Của Ứng Dụng (Application Purpose)**
- Mục tiêu chính của hệ thống này là gì?
- Ở cấp độ tổng thể, hệ thống này hướng tới giải quyết bài toán hay vấn đề gì?

### **Cách Thức Hoạt Động (Ở Cấp Độ Tổng Quan)**
- Mô tả luồng hoạt động tổng thể của hệ thống một cách ngắn gọn và dễ hiểu đối với những người đọc không chuyên về kỹ thuật.
- Các bước hoặc quy trình chính mà hệ thống thực hiện là gì?

### **Các Quy Tắc Nghiệp Vụ Cấp Cao (High-Level Business Rules)**
- Xác định và mô tả các quy tắc nghiệp vụ chính đang được triển khai bên trong mã nguồn.
- Những chính sách kinh doanh, ràng buộc hoặc logic nền tảng nào mà hệ thống đang tuân theo?

### **Các Lợi Ích Cốt Lõi (Key Benefits)**
- Những lợi ích chính yếu mà hệ thống này mang lại cho tổ chức hoặc người dùng của nó là gì?

---

## **2. Góc Nhìn Cấp Kỹ Thuật (Technical-Level View): Tổng Quan Công Nghệ**

### **Kiến Trúc Hệ Thống (System Architecture)**
- Mô tả kiến trúc tổng thể của hệ thống dựa trên kết quả phân tích mã nguồn.
- Hệ thống có tuân theo một mẫu kiến trúc cụ thể nào không (ví dụ: Nguyên khối Monolithic, Vi dịch vụ Microservices, v.v.)?
- Các thành phần hoặc module chính được xác định trong hệ thống là gì?

### **Các Công Nghệ Được Sử Dụng (Technology Stack)**
- Liệt kê toàn bộ các ngôn ngữ lập trình, frameworks, thư viện, cơ sở dữ liệu và những công nghệ khác được sử dụng trong dự án.

### **Các Luồng Kỹ Thuật Chính (Main Technical Flows)**
- Trình bày chi tiết các luồng dữ liệu và luồng thực thi chính bên trong hệ thống.
- Các thành phần khác nhau tương tác và giao tiếp với nhau như thế nào?

### **Các Thành Phần Trọng Yếu (Key Components)**
- Xác định và mô tả những thành phần hệ thống quan trọng nhất, giải thích rõ vai trò và trách nhiệm của từng thành phần bên trong kiến trúc chung.

### **Độ Phức Tạp Của Mã Nguồn (Nhận Xét Đánh Giá)**
- Dựa trên quá trình phân tích của bạn, hãy đưa ra những nhận xét tổng quan về độ phức tạp của mã nguồn (ví dụ: cấu trúc tốt, phân chia module rõ ràng, hoặc chỉ ra những khu vực có độ phức tạp cao dễ nhận thấy).

### **Sơ Đồ Trực Quan (Diagrams)**
- Khởi 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 - tập trung vào các module lớn và sự tương tác giữa chúng)
  - Sơ đồ luồng dữ liệu (Data flow diagram - thể hiện cách thông tin di chuyển xuyên suốt hệ thống)
  - Sơ đồ lớp (Class diagram - trình bày các lớp chính và mối quan hệ giữa chúng, nếu áp dụng)
  - Sơ đồ triển khai rút gọn (Simplified deployment diagram - thể hiện nơi các thành phần chạy thực tế, nếu có thể nhận biết từ mã nguồn)
  - Sơ đồ hạ tầng/triển khai rút gọn (nếu các chi tiết cấu hình hạ tầng hiện diện rõ trong dự án)
- **Hãy tạo các sơ đồ nêu trên bằng cú pháp Mermaid ngay bên trong tệp Markdown. Các sơ đồ nên giữ ở mức tổng quan cấp cao, tránh vẽ quá chi tiết gây rối mắt.**

---

## **3. Góc Nhìn Sản Phẩm (Product View): Tóm Tắt Sản Phẩm**

### **Chức Năng Chi Tiết Của Hệ Thống (What the System Does)**
- Mô tả chi tiết các chức năng chính của hệ thống.
- Người dùng có thể thực hiện những tác vụ hoặc hành động cụ thể nào trên hệ thống?

### **Đối Tượng Phục Vụ Của Hệ Thống (Người Dùng / Khách Hàng)**
- Xác định nhóm đối tượng mục tiêu chính của hệ thống.
- Ai là người dùng cuối hoặc khách hàng được hưởng lợi trực tiếp từ hệ thống này?

### **Các Vấn Đề Hệ Thống Giải Quyết (Nhu Cầu Được Đáp Ứng)**
- Hệ thống giúp giải quyết những vấn đề cụ thể nào cho người dùng hoặc cho tổ chức?
- Nó đáp ứng những nhu cầu thực tế nào?

### **Các Ca Sử Dụng / Hành Trình Người Dùng (Ở Cấp Độ Tổng Quan)**
- Các ca sử dụng (use cases) chính của hệ thống là gì?
- Người dùng tương tác với hệ thống theo trình tự như thế nào để đạt được mục tiêu của họ?

### **Các Tính Năng Cốt Lõi (Core Features)**
- Liệt kê những tính năng quan trọng nhất của hệ thống một cách rõ ràng và súc tích.

### **Các Miền Nghiệp Vụ (Business Domains)**
- Xác định các miền nghiệp vụ chính mà hệ thống bao quát (ví dụ: bán hàng, quản lý kho vận, tài chính kế toán).

---

## **Các Giới Hạn Trong Quá Trình Phân Tích (Analysis Limitations)**

- Những hạn chế chính gặp phải trong quá trình phân tích mã nguồn này là gì?
- Mô tả ngắn gọn những yếu tố nào đã giới hạn mức độ hiểu biết đầy đủ của bạn về mã nguồn (ví dụ: thiếu tài liệu ngoài, dịch vụ bên thứ ba, cấu hình môi trường ẩn).
- Đưa ra các đề xuất thiết thực nhằm giảm thiểu hoặc loại bỏ những hạn chế này.

---

## **Nguyên Tắc Trình Bày Tài Liệu (Document Guidelines)**

### **Định Dạng Tài Liệu**
- Tài liệu bắt buộc phải được định dạng bằng chuẩn Markdown, với các tiêu đề chính và tiêu đề phụ rõ ràng cho từng phần.
- Sử dụng danh sách gạch đầu dòng, bảng biểu và các phần tử Markdown khác để tăng tính dễ đọc và khả năng tiếp thu thông tin.

### **Hướng Dẫn Bổ Sung**
- Tập trung cung cấp thông tin có giá trị ở cấp độ tổng quan, tránh sa đà vào các chi tiết triển khai mã nguồn quá nhỏ nhặt trừ khi chúng thực sự then chốt để hiểu hệ thống.
- Sử dụng ngôn từ rõ ràng, cô đọng và dễ tiếp cận đối với nhiều nhóm độc giả khác nhau.
- Trình bày cụ thể và sát thực tế nhất có thể dựa trên bằng chứng từ việc phân tích mã nguồn.
- 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 chỉn chu**.
- Sử dụng **ngôn ngữ mạch lạc và trực diện**.
- Sử dụng **các cấp tiêu đề (headings và subheadings)** bám sát theo đúng cấu trúc các phần ở trên.

### **Tiêu Đề Tài Liệu**
**Phân Tích Điều Hành và Nghiệp Vụ Của Ứng Dụng – "<application-name>"**

### **Tóm Tắt Tài Liệu**
Tài liệu này là kết quả của quá trình phân tích mã nguồn hệ thống <system-name> và bao gồm các lĩnh vực sau:

- **Góc nhìn Cấp Điều hành:** Tóm tắt mục đích của ứng dụng, cách thức vận hành tổng quan, các quy tắc nghiệp vụ chính và những lợi ích cốt lõi.
- **Góc nhìn Cấp Kỹ thuật:** Chi tiết về kiến trúc hệ thống, các công nghệ được sử dụng, luồng xử lý chính, các thành phần trọng yếu và hệ thống sơ đồ (thành phần, luồng dữ liệu, lớp và triển khai).
- **Góc nhìn Sản phẩm:** Mô tả chi tiết chức năng hệ thống, người dùng mục tiêu, các vấn đề được giải quyết, các ca sử dụng chính, tính năng cốt lõi và miền nghiệp vụ.
- **Các Giới hạn Phân tích:** Xác định những rào cản chính trong quá trình phân tích và đề xuất giải pháp khắc phục.

Quá trình phân tích được thực hiện hoàn toàn dựa trên các tệp mã nguồn hiện có.

---

## **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à nắm bắt **mọi tệp cần thiết** để thực hiện nhiệm vụ và đạt được sự hiểu biết toàn diện về hệ thống.

---

## **Hành Động (Action)**
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à khởi 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 sau:  
`<yyyy-mm-dd-project-name-app-discovery_cursor.md>`