Valdecir Carvalho

**Bối cảnh:**  
Tôi là một nhà phát triển vừa tham gia dự án và tôi đang nhờ bạn, một trợ lý mã hóa AI, để hiểu sâu hơn về cơ sở mã hiện có. Mục tiêu của tôi là làm việc hiệu quả 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ự hiểu biết 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 này và tạo **tài liệu Markdown chi tiết, rõ ràng và có cấu trúc tốt** giải thích kiến trúc, tính năng, quy trình chính, thành phần chính và ngăn xếp công nghệ của hệ thống.  
Tài liệu này sẽ đóng vai trò như **hướng dẫn giới thiệu kỹ thuật**.  
Bất cứ khi nào có thể, hãy cải thiện khả năng điều hướng bằng cách cung cấp **liên kết trực tiếp đến các tệp, lớp và hàm có liên quan**, cũng như các ví dụ về mã giúp làm rõ các khái niệm.

---

## **Hướng dẫn chi tiết — Vui lòng giải quyết các điểm sau:**

### 1. **README / Tóm tắt tệp hướng dẫn**
- Tìm kiếm các tệp như `README.md`, `LEIAME.md`, `CONTRIBUTING.md` hoặ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ề các phần phù hợp nhất cho nhà phát triển mới, bao gồm:
  - Tổng quan dự án
  - Cách thiết lập và chạy hệ thống cục bộ
  - Các tiêu chuẩn và quy ước được thông qua
  - Hướng dẫn đóng góp (nếu có)

---

### 2. **Ngăn xếp công nghệ chi tiết**
- Xác định và liệt kê đầy đủ các công nghệ được sử dụng trong dự án:
  - (Các) ngôn ngữ lập trình, bao gồm cá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 khung chính (phụ trợ, giao diện người dùng, v.v. - ví dụ: Spring Boot, .NET, React, Angular, Vue, Django, Rails).
  - Cơ sở dữ liệu:
    - Kiểu (SQL/NoSQL)
    - Tên (PostgreSQL, MongoDB, v.v.)
  - Phong cách kiến trúc cốt lõi (ví dụ: Monolith, Microservices, Serverless, MVC, MVVM, Clean Architecture).
  - Nền tảng đám mây (nếu có thể nhận dạng thông qua SDK hoặc cấu hình - AWS, Azure, GCP).
  - Xây dựng các công cụ và trình quản lý gói (Maven, Gradle, npm, Fiber, pip).
  - Bất kỳ công nghệ liên quan nào khác (bộ nhớ đệm, môi giới tin nhắn, container hóa — Docker, Kubernetes).
- **Tham khảo và liên kết các file cấu hình thể hiện từng mục.**

---

### 3. **Tổng quan và mục đích của hệ thống**
- Mô tả rõ ràng hệ thống làm gì và dành cho ai.
- Nó giải quyết được 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 lĩnh vực kinh doanh liên quan.
- Cung cấp một mô tả cấp cao về các tính năng chính.

---

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

---

### 5. **Thành phần chính**
- Xác định và mô tả các mô-đun, lớp, chức năng hoặc dịch vụ quan trọng hoặc trung tâm nhất.
- Nêu rõ trách nhiệm của từng thành phần.
- Mô tả trách nhiệm và sự phụ thuộc lẫn nhau của họ.
- Đối với từng thành phần:
  - Bao gồm đoạn mã đại diện
  - Cung cấp một liên kết đến nơi nó được thực hiện
- **Cung cấp liên kết trực tiếp và ví dụ về mã bất cứ khi nào có thể.**

---

### 6. **Thực thi và luồng dữ liệu**
- Mô tả các quy trình công việc hoặc quy trình kinh doanh phổ biến hoặc 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 trong hệ thống:
  - Nơi dữ liệu được lưu giữ
  - Cách nó được đọc, sửa đổi và phổ biến
- **Bất cứ khi nào có thể, hãy minh họa bằng các ví dụ và liên kết đến các hàm hoặc lớp có liên quan.**

#### 6.1 **Tổng quan về lược đồ cơ sở dữ liệu (nếu có)**
- Đối với các ứng dụng sử dụng nhiều dữ liệu:
  - Xác định các thực thể/bảng/bộ sưu tập chính
  - Nêu mối quan hệ chính của chúng
  - Dựa trên mô hình ORM, quá trình di chuyển hoặc tệp lược đồ nếu có

---

### 7. **Phụ thuộc và tích hợp**
- **Phụ thuộc:**  
  Liệt kê các thư viện, khung và SDK chính bên ngoài được sử dụng.  
  Hãy giải thích ngắn gọn vai trò của từng người.  
  **Cung cấp liên kết đến nơi chúng được định cấu hình hoặc được sử dụng phổ biến nhất.**
- **Tích hợp:**  
  Xác định và giải thích sự tích hợp với các dịch vụ bên ngoài, cơ sở dữ liệu bổ sung, API của bên thứ ba, nhà môi giới tin nhắn, v.v.  
  Giao tiếp diễn ra như thế nào?  
  **Chỉ vào các mô-đun/lớp chịu trách nhiệm và kèm theo các liên kết.**

#### 7.1 **Tài liệu API (nếu có)**
- Nếu dự án có API:
  - Có bằng chứng về các công cụ hoặc tiêu chuẩn tài liệu API (ví dụ: Swagger/OpenAPI, Javadoc, chuỗi tài liệu dành riêng cho điểm cuối) không?
  - Tài liệu này có thể được tìm thấy ở đâu hoặc có thể được tạo ra như thế nào?

---

### 8. **Sơ đồ**
- Tạo 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 (làm nổi bật các mô-đun chính và sự tương tác của chúng)
  - Sơ đồ luồng dữ liệu (thể hiện cách thông tin di chuyển trong hệ thống)
  - Sơ đồ lớp (hiển thị các lớp và mối quan hệ chính, nếu có)
  - Sơ đồ triển khai được đơn giản hóa (nơi các thành phần chạy, nếu có thể phát hiện được)
  - Sơ đồ cơ sở hạ tầng/triển khai đơn giản hóa (nếu chi tiết cơ sở hạ tầng rõ ràng)
- **Tạo các sơ đồ này bằng cú pháp Nàng tiên cá bên trong tệp Markdown.**
- Sơ đồ phải **cấp cao**; chi tiết rộng rãi là không cần thiết.

---

### 9. **Thử nghiệm**
- Có kiểm tra tự động không?
  - Kiểm tra đơn vị
  - Kiểm tra tích hợp
  - Kiểm tra từ đầu đến cuối (E2E)
- Họ nằm ở đâu trong dự án?
- Những khung thử nghiệm nào được sử dụng?
- Các bài kiểm tra thường được thực hiện như thế nào?
- Làm cách nào để chạy thử nghiệm cục bộ?
- Có chiến lược CI/CD nào liên quan đến kiểm tra không?

---

### 10. **Xử lý lỗi và ghi nhật ký**
- Ứng dụng thường xử lý lỗi như thế nào?
  - Có mẫu chuẩn nào không (ví dụ: phần mềm trung gian toàn cầu, ngoại lệ tùy chỉnh)?
- Thư viện ghi nhật ký nào được sử dụng?
- Có định dạng ghi nhật ký chuẩn không?
- Có tích hợp rõ ràng với các công cụ giám sát (ví dụ: Datadog, Sentry) không?

---

### 11. **Cân nhắc về bảo mật**
- Có cơ chế bảo mật rõ ràng trong mã không?
  - Xác thực
  - Ủy quyền (phần mềm trung gian/bộ lọc)
  - Xác thực đầu vào
- Các thư viện bảo mật cụ thể có được sử dụng phổ biến không (ví dụ: thư viện Spring Security, Passport.js, JWT)?
- Có thực tiễn bảo mật đáng chú ý nào không?
  - Quản lý bí mật
  - Bảo vệ chống lại các cuộc tấn công thông thường

---

### 12. **Các quan sát liên quan khác (Bao gồm cả Xây dựng/Triển khai)**
- Có tập tin nào liên quan đến **xây dựng hoặc triển khai** không?
  - `Dockerfile`
  - `docker-compose.yml`
  - Xây dựng/triển khai tập lệnh
  - Tệp cấu hình CI/CD (ví dụ: `.github/workflows/`, `.gitlab-ci.yml`)
- Các tệp này cho biết gì về cách ứng dụng được xây dựng và triển khai?
- Có điều gì khác quan trọng hoặc đặc biệt hữu ích cho nhà phát triển mới không?
  - Đã biết nợ kỹ thuật đề cập ở phần bình luận
  - Mẫu thiết kế khác thường
  - Các quy ước mã hóa quan trọng
  - Ghi chú hiệu suất

---

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

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

---

### **QUAN TRỌNG**
Việc phân tích phải xem xét **TẤT CẢ các tệp trong dự án**.  
Đọc và hiểu **tất cả các tệp cần thiết** cần thiết để thực hiện đầy đủ nhiệm vụ này và đạt được sự hiểu biết đầy đủ 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 yêu cầu.

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

# **Nhắc nhở phân tích mã và tạo tài liệu hệ thống**

Bạn là chuyên gia về phân tích mã và 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 này và tạo tài liệu Markdown toàn diện đóng vai trò là hướng dẫn giới thiệu cho nhiều đối tượng (điều hành, kỹ thuật, kinh doanh và sản phẩm).

## **Hướng dẫn**

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

---

## **1. Chế độ xem cấp điều hành: Tóm tắt điều hành**

### **Mục đích ứng dụng**
- Mục tiêu chính của hệ thống này là gì?
- Mục đích giải quyết vấn đề gì ở mức độ cao?

### **Cách thức hoạt động (Cấp cao)**
- Mô tả quy trình tổng thể của hệ thống một cách ngắn gọn và dễ tiếp cận đối với đối tượng 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ì?

### **Quy tắc kinh doanh cấp cao**
- Xác định và mô tả các quy tắc kinh doanh chính được thực hiện trong mã.
- Các chính sách, ràng buộc hoặc logic kinh doanh cơ bản mà hệ thống tuân theo là gì?

### **Lợi ích chính**
- Những lợi ích chính mà hệ thống này mang lại cho tổ chức hoặc người dùng là gì?

---

## **2. Chế độ xem cấp độ kỹ thuật: Tổng quan về công nghệ**

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

### **Các công nghệ được sử dụng (Ngăn xếp công nghệ)**
- Liệt kê tất cả các ngôn ngữ lập trình, framework, thư viện, cơ sở dữ liệu và các công nghệ khác được sử dụng trong dự án.

### **Các luồng kỹ thuật chính**
- Chi tiết hóa dữ liệu chính và các luồng thực thi trong hệ thống.
- Các thành phần khác nhau tương tác với nhau như thế nào?

### **Thành phần chính**
- Xác định và mô tả các thành phần hệ thống quan trọng nhất, giải thích vai trò và trách nhiệm của chúng trong kiến trúc.

### **Độ phức tạp của mã (Quan sát)**
- Dựa trên phân tích của bạn, hãy đưa ra những quan sát chung về độ phức tạp của mã (ví dụ: các khu vực có cấu trúc tốt, được mô đun hóa, có độ phức tạp rõ ràng cao hơn).

### **Sơ đồ**
- Tạo 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 (tập trung vào các module chính và sự tương tác của chúng)
  - Sơ đồ luồng dữ liệu (thể hiện cách thông tin di chuyển trong hệ thống)
  - Sơ đồ lớp (trình bày các lớp chính và mối quan hệ của chúng, nếu có)
  - Sơ đồ triển khai đơn giản hóa (hiển thị nơi các thành phần chạy, nếu có thể phát hiện được)
  - Sơ đồ cơ sở hạ tầng/triển khai đơn giản hóa (nếu chi tiết cơ sở hạ tầng rõ ràng)
- **Tạo sơ đồ trên bằng cú pháp Nàng tiên cá trong tệp Markdown. Sơ đồ phải ở mức cao và không quá chi tiết.**

---

## **3. Xem sản phẩm: Tóm tắt sản phẩm**

### **Hệ thống làm gì (Chi tiết)**
- 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 nhiệm vụ hoặc hành động nào?

### **Hệ thống dành cho ai (Người dùng / Khách hàng)**
- Xác định đố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 từ nó?

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

### **Trường hợp sử dụng / Hành trình của người dùng (Cấp cao)**
- Các trường hợp sử dụng chính của hệ thống là gì?
- Người dùng tương tác với hệ thống như thế nào để đạt được mục tiêu của mình?

### **Các tính năng cốt lõi**
- Liệt kê các tính năng quan trọng nhất của hệ thống một cách rõ ràng và chính xác.

### **Miền doanh nghiệp**
- Xác định các lĩnh vực kinh doanh chính được hệ thống bao phủ (ví dụ: bán hàng, hàng tồn kho, tài chính).

---

## **Giới hạn phân tích**

- Những hạn chế chính gặp phải trong quá trình phân tích mã là gì?
- Mô tả ngắn gọn những gì hạn chế sự hiểu biết của bạn về mã.
- Đưa ra các đề xuất nhằm giảm bớt hoặc loại bỏ những hạn chế này.

---

## **Hướng dẫn về tài liệu**

### **Định dạng tài liệu**
- Tài liệu phải được định dạng bằng Markdown, có tiêu đề và phụ đề rõ ràng cho từng phần.
- Sử dụng danh sách, bảng và các phần tử Markdown khác để cải thiện khả năng đọc và hiểu.

### **Hướng dẫn bổ sung**
- Tập trung vào việc cung cấp thông tin cấp cao, phù hợp, tránh sử dụng quá nhiều chi tiết triển khai trừ khi cần thiết để hiểu.
- Sử dụng ngôn ngữ rõ ràng, ngắn gọn, dễ tiếp cận, phù hợp với nhiều đối tượng.
- Càng cụ thể càng tốt dựa trên phân tích mã.
- Tạo phản hồi hoàn chỉnh dưới dạng **tài liệu Markdown (`.md`) được định dạng đúng**.
- Sử dụng **ngôn ngữ rõ ràng và trực tiếp**.
- Sử dụng **tiêu đề và tiêu đề phụ** theo các phần trên.

### **Tiêu đề tài liệu**
**Phân tích điều hành và kinh doanh 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ả phân tích mã nguồn của hệ thống <system-name> và bao gồm các lĩnh vực sau:

- **Chế độ xem cấp điều hành:** Tóm tắt mục đích của ứng dụng, hoạt động cấp cao, các quy tắc kinh doanh chính và các lợi ích chính.
- **Chế độ xem cấp độ kỹ thuật:** Chi tiết về kiến ​​trúc hệ thống, công nghệ được sử dụng, luồng chính, thành phần chính và sơ đồ (thành phần, luồng dữ liệu, lớp và hoạt động triển khai).
- **Chế độ xem sản phẩm:** Mô tả chi tiết về chức năng hệ thống, người dùng mục tiêu, vấn đề được giải quyết, trường hợp sử dụng chính, tính năng và lĩnh vực kinh doanh.
- **Hạn chế phân tích:** Xác định các hạn chế chính trong phân tích và đề xuất để khắc phục chúng.

Việc phân tích dựa trên các tệp mã nguồn có sẵn.

---

## **QUAN TRỌNG**
Việc phân tích phải xem xét **TẤT CẢ các tệp dự án**.  
Đọc và hiểu **tất cả các tệp cần thiết** cần thiết để thực hiện nhiệm vụ và đạt được sự hiểu biết đầy đủ 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 được yêu cầu.

Tên tệp đầu ra phải tuân theo định dạng sau:  
`<yyyy-mm-dd-project-name-app-discovery_cursor.md>`