Prompt Kiểm toán Toàn diện & Khắc phục Lỗi Kho Mã nguồn (Repository)

## Mục tiêu
Thực hiện phân tích kỹ lưỡng toàn bộ kho mã nguồn (repository) để xác định, sắp xếp mức độ ưu tiên, khắc phục và lập tài liệu cho TẤT CẢ các lỗi (bugs) có thể kiểm chứng được, các lỗ hổng bảo mật và các vấn đề nghiêm trọng trên bất kỳ ngôn ngữ lập trình, framework hoặc ngăn xếp công nghệ nào.

## Giai đoạn 1: Đánh giá Kho Mã nguồn Ban đầu

### 1.1 Lập Bản đồ Kiến trúc
- Lập bản đồ cấu trúc dự án hoàn chỉnh (`src/`, `lib/`, `tests/`, `docs/`, `config/`, `scripts/`, v.v.)
- Xác định ngăn xếp công nghệ và các gói phụ thuộc (`package.json`, `requirements.txt`, `go.mod`, `pom.xml`, `Gemfile`, v.v.)
- Tài liệu hóa các điểm khởi đầu chính (entry points), các luồng xử lý trọng yếu và ranh giới hệ thống
- Phân tích cấu hình biên dịch (build) và đường ống tích hợp/triển khai liên tục (CI/CD pipelines)
- Rà soát các tài liệu hiện có (README, tài liệu API, sơ đồ kiến trúc)

### 1.2 Phân tích Môi trường Phát triển
- Xác định các framework kiểm thử (Jest, pytest, PHPUnit, Go test, JUnit, RSpec, v.v.)
- Rà soát các cấu hình kiểm tra quy tắc mã/định dạng (ESLint, Prettier, Black, RuboCop, v.v.)
- Kiểm tra hệ thống theo dõi vấn đề hiện có (GitHub Issues, các ghi chú `TODO`/`FIXME`/`HACK`/`XXX` trong mã)
- Phân tích lịch sử commit để tìm các khu vực thường xuyên phát sinh sự cố gần đây
- Xem xét các báo cáo độ bao phủ kiểm thử (test coverage) hiện có nếu khả dụng

## Giai đoạn 2: Phát hiện Lỗi Có Hệ thống

### 2.1 Các Danh mục Lỗi Cần Xác định
**Lỗi Nghiêm trọng (Critical Bugs):**
- Các lỗ hổng bảo mật (SQL injection, XSS, CSRF, vượt qua xác thực - auth bypass, v.v.)
- Rủi ro hỏng dữ liệu hoặc mất mát dữ liệu
- Sập hệ thống (crashes) hoặc khóa chết (deadlocks)
- Rò rỉ bộ nhớ (memory leaks) hoặc cạn kiệt tài nguyên

**Lỗi Chức năng (Functional Bugs):**
- Lỗi logic (điều kiện không chính xác, tính toán sai, lỗi lệch một đơn vị - off-by-one errors)
- Các vấn đề quản lý trạng thái (điều kiện tranh đua - race conditions, trạng thái không nhất quán, biến đổi dữ liệu sai cách)
- Hợp đồng giao tiếp API hoặc ánh xạ dữ liệu không chính xác
- Thiếu hoặc sai quy trình xác thực dữ liệu đầu vào (validations)
- Quy tắc nghiệp vụ hoặc luồng công việc bị hỏng

**Lỗi Tích hợp (Integration Bugs):**
- Sử dụng API bên ngoài không chính xác
- Lỗi truy vấn cơ sở dữ liệu hoặc truy vấn kém hiệu quả
- Các vấn đề xử lý hàng đợi tin nhắn (message queue)
- Sự cố khi thao tác với hệ thống tệp tin
- Lỗi giao tiếp mạng

**Trường hợp Biên & Xử lý Lỗi (Edge Cases & Error Handling):**
- Xử lý giá trị `null`/`undefined`/`nil`
- Các trường hợp biên với tập hợp rỗng hoặc giá trị bằng không
- Các điều kiện biên và vi phạm giới hạn
- Thiếu cơ chế lan truyền lỗi hoặc nuốt ngoại lệ (swallowing exceptions)
- Các vấn đề trong logic hết thời gian chờ (timeout) và thử lại (retry)

**Các Vấn đề Chất lượng Mã nguồn (Code Quality Issues):**
- Lệch kiểu dữ liệu hoặc ép kiểu không an toàn
- Sử dụng các API đã ngừng hỗ trợ (deprecated)
- Mã chết (dead code) hoặc các nhánh điều kiện không bao giờ chạm tới được
- Phụ thuộc vòng tròn (circular dependencies)
- Điểm nghẽn hiệu năng (truy vấn N+1, thuật toán kém hiệu quả)

### 2.2 Phương pháp Phát hiện
- Phân tích mã tĩnh (static code analysis) sử dụng các công cụ chuyên biệt cho từng ngôn ngữ
- Đối sánh mẫu (pattern matching) để tìm các phản mẫu (anti-patterns) phổ biến
- Quét lỗ hổng bảo mật trong các thư viện phụ thuộc
- Phân tích luồng thực thi mã để tìm các đoạn mã không thể chạm tới hoặc chưa được kiểm thử
- Xác thực cấu hình hệ thống
- Đối chiếu chéo tài liệu hướng dẫn với mã nguồn triển khai thực tế

## Giai đoạn 3: Tài liệu hóa & Sắp xếp Ưu tiên Lỗi

### 3.1 Mẫu Báo cáo Lỗi (Bug Report Template)
Đối với mỗi lỗi được xác định, hãy ghi chép theo mẫu sau:
```
BUG-ID: [Mã định danh tuần tự]
Severity: [CRITICAL | HIGH | MEDIUM | LOW]
Category: [Security | Functional | Performance | Integration | Code Quality]
File(s): [Đường dẫn tệp đầy đủ và số dòng]
Component: [Mô-đun/Dịch vụ/Tính năng bị ảnh hưởng]

Description:
- Hành vi hiện tại (điểm đang bị sai)
- Hành vi kỳ vọng (điều lẽ ra phải xảy ra)
- Phân tích nguyên nhân gốc rễ (Root cause analysis)

Impact Assessment:
- Tác động tới người dùng (suy giảm trải nghiệm UX, mất dữ liệu, lộ lọt bảo mật)
- Tác động tới hệ thống (hiệu năng, độ ổn định, khả năng mở rộng)
- Tác động tới kinh doanh (tuân thủ pháp lý, doanh thu, uy tín)

Reproduction Steps:
1. [Hướng dẫn tái hiện lỗi từng bước]
2. [Bao gồm dữ liệu/điều kiện kiểm thử nếu cần]
3. [Kết quả kỳ vọng so với kết quả thực tế]

Verification Method:
- [Đoạn mã hoặc bài kiểm thử chứng minh sự tồn tại của lỗi]
- [Các chỉ số hoặc nhật ký (logs) cho thấy vấn đề]

Dependencies:
- Các lỗi liên quan: [Danh sách các mã BUG-ID có liên quan]
- Các vấn đề gây chặn: [Những gì cần phải được sửa trước]
```

### 3.2 Ma trận Sắp xếp Thứ tự Ưu tiên
Xếp hạng các lỗi dựa trên:
- **Mức độ Nghiêm trọng (Severity)**: Critical > High > Medium > Low
- **Tác động tới Người dùng (User Impact)**: Số lượng người dùng/tính năng bị ảnh hưởng
- **Độ Phức tạp khi Sửa lỗi (Fix Complexity)**: Đơn giản < Trung bình < Phức tạp
- **Rủi ro Lỗi Hồi quy (Risk of Regression)**: Thấp < Trung bình < Cao

## Giai đoạn 4: Triển khai Khắc phục Lỗi

### 4.1 Chiến lược Khắc phục
**Đối với từng lỗi:**
1. Tạo nhánh (branch) sửa lỗi độc lập (nếu sử dụng hệ thống quản lý phiên bản)
2. Viết bài kiểm thử báo lỗi TRƯỚC TIÊN (cách tiếp cận TDD)
3. Triển khai bản sửa lỗi tối giản, tập trung đúng trọng tâm
4. Xác minh bài kiểm thử đã vượt qua thành công (pass)
5. Chạy các bài kiểm thử hồi quy (regression tests)
6. Cập nhật tài liệu nếu cần thiết

### 4.2 Nguyên tắc Khắc phục Lỗi
- **Nguyên tắc Thay đổi Tối thiểu**: Thực hiện thay đổi nhỏ nhất nhưng khắc phục chính xác vấn đề
- **Không Phình to Phạm vi (No Scope Creep)**: Tránh việc tái cấu trúc (refactoring) hoặc cải tiến những phần không liên quan
- **Bảo toàn Tính Tương thích Ngược**: Trừ khi bản thân lỗi đó chính là một API gây lỗi tương thích
- **Tuân thủ Tiêu chuẩn Dự án**: Sử dụng phong cách viết mã và các mẫu thiết kế hiện có của dự án
- **Bổ sung Lập trình Phòng vệ (Defensive Programming)**: Ngăn chặn các lỗi tương tự tái diễn trong tương lai

### 4.3 Danh sách Kiểm tra Đánh giá Mã nguồn (Code Review Checklist)
- [ ] Bản sửa lỗi giải quyết tận gốc nguyên nhân gốc rễ, chứ không chỉ xử lý triệu chứng bề nổi
- [ ] Tất cả các trường hợp biên đều đã được xử lý
- [ ] Thông báo lỗi rõ ràng và có tính hướng dẫn hành động
- [ ] Tác động về mặt hiệu năng ở mức chấp nhận được
- [ ] Đã cân nhắc kỹ các hệ quả về bảo mật
- [ ] Không làm phát sinh thêm cảnh báo (warnings) hoặc lỗi kiểm tra quy tắc mã (linting errors) mới

## Giai đoạn 5: Kiểm thử & Xác thực

### 5.1 Yêu cầu Kiểm thử
**Đối với MỌI lỗi đã được khắc phục, hãy cung cấp:**
1. **Kiểm thử Đơn vị (Unit Test)**: Bài kiểm thử độc lập cho riêng bản sửa lỗi cụ thể đó
2. **Kiểm thử Tích hợp (Integration Test)**: Nếu lỗi liên quan đến sự phối hợp giữa nhiều thành phần
3. **Kiểm thử Hồi quy (Regression Test)**: Đảm bảo bản sửa lỗi không làm hỏng các chức năng hiện có
4. **Kiểm thử Trường hợp Biên (Edge Case Tests)**: Bao phủ các điều kiện biên có liên quan

### 5.2 Cấu trúc Bài Kiểm thử
```[language-specific]
describe('BUG-[ID]: [Bug description]', () => {
  test('should fail with original bug', () => {
    // Bài kiểm thử này sẽ thất bại trước khi áp dụng bản sửa lỗi
    // Chứng minh sự tồn tại của lỗi
  });
  
  test('should pass after fix', () => {
    // Bài kiểm thử này sẽ vượt qua sau khi áp dụng bản sửa lỗi
    // Xác minh hành vi hoạt động chính xác
  });
  
  test('should handle edge cases', () => {
    // Bao phủ bổ sung các trường hợp biên
  });
});
```

### 5.3 Các Bước Xác thực
1. Chạy toàn bộ bộ kiểm thử: `[npm test | pytest | go test ./... | mvn test | etc.]`
2. Kiểm tra sự thay đổi về độ bao phủ mã nguồn (code coverage)
3. Chạy các công cụ phân tích mã tĩnh
4. Xác minh các chỉ số kiểm chuẩn hiệu năng (nếu có áp dụng)
5. Kiểm thử trên các môi trường khác nhau (nếu có thể)

## Giai đoạn 6: Tài liệu hóa & Báo cáo

### 6.1 Tài liệu hóa Bản sửa lỗi
Đối với mỗi lỗi đã được khắc phục:
- Cập nhật chú thích trực tiếp trong mã nguồn (inline comments) giải thích rõ bản sửa lỗi
- Thêm/cập nhật tài liệu API nếu hành vi hoạt động có thay đổi
- Tạo mới/cập nhật hướng dẫn xử lý sự cố (troubleshooting guides)
- Tài liệu hóa bất kỳ giải pháp tạm thời (workarounds) nào cho các vấn đề chưa được sửa triệt để

### 6.2 Báo cáo Tóm tắt Điều hành (Executive Summary Report)
```markdown
# Báo cáo Khắc phục Lỗi - [Repository Name]
Ngày: [YYYY-MM-DD]
Người/Công cụ Phân tích: [Tool/Person Name]

## Tổng quan
- Tổng số Lỗi Phát hiện: [X]
- Tổng số Lỗi Đã sửa: [Y]
- Chưa sửa/Tạm hoãn: [Z]
- Thay đổi Độ bao phủ Kiểm thử: [Before]% → [After]%

## Các Phát hiện Nghiêm trọng
[Liệt kê top 3-5 lỗi nghiêm trọng nhất đã được phát hiện và khắc phục]

## Tóm tắt Khắc phục theo Danh mục
- Bảo mật (Security): [X lỗi đã sửa]
- Chức năng (Functional): [Y lỗi đã sửa]
- Hiệu năng (Performance): [Z lỗi đã sửa]
- Tích hợp (Integration): [W lỗi đã sửa]
- Chất lượng Mã nguồn (Code Quality): [V lỗi đã sửa]

## Danh sách Khắc phục Chi tiết
[Bảng có cấu trúc gồm các cột: BUG-ID | File | Description | Status | Test Added]

## Đánh giá Rủi ro
- Các Vấn đề Ưu tiên Cao Còn tồn đọng: [Danh sách]
- Các Bước Tiếp theo Được Khuyến nghị: [Hành động]
- Nợ Kỹ thuật (Technical Debt) Đã Xác định: [Tóm tắt]

## Kết quả Kiểm thử
- Lệnh Kiểm thử: [câu lệnh chính xác đã sử dụng]
- Số bài Kiểm thử Vượt qua: [X/Y]
- Số bài Kiểm thử Mới Đã thêm: [Số lượng]
- Tác động Độ bao phủ: [Chi tiết]
```

### 6.3 Danh sách Kiểm tra Hạng mục Bàn giao
- [ ] Tất cả các lỗi đã được ghi nhận theo đúng định dạng tiêu chuẩn
- [ ] Các bản sửa lỗi đã được triển khai và kiểm thử
- [ ] Bộ kiểm thử đã được cập nhật và chạy thành công 100%
- [ ] Tài liệu đã được cập nhật
- [ ] Đã hoàn tất đánh giá mã nguồn (code review)
- [ ] Đã đánh giá tác động về mặt hiệu năng
- [ ] Đã thực hiện rà soát bảo mật (đối với các bản sửa lỗi liên quan đến bảo mật)
- [ ] Đã chuẩn bị sẵn ghi chú triển khai (deployment notes)

## Giai đoạn 7: Cải tiến Liên tục

### 7.1 Phân tích Quy luật Lỗi
- Xác định các mẫu lỗi thường gặp lặp đi lặp lại
- Đề xuất các biện pháp phòng ngừa
- Khuyến nghị cải tiến bộ công cụ phát triển
- Đề xuất các thay đổi về mặt kiến trúc để ngăn chặn các vấn đề tương tự phát sinh

### 7.2 Khuyến nghị Giám sát
- Đề xuất các chỉ số (metrics) cần theo dõi
- Khuyến nghị các quy tắc cảnh báo (alerting rules)
- Đề xuất cải thiện hệ thống ghi nhật ký (logging)
- Xác định các khu vực cần nâng cao độ bao phủ kiểm thử

## Các Ràng buộc & Thực hành Tốt nhất

1. **Không bao giờ thỏa hiệp về bảo mật** chỉ để đổi lấy sự đơn giản
2. **Duy trì dấu vết kiểm toán (audit trail)** cho mọi thay đổi
3. **Tuân thủ quy tắc đánh số phiên bản ngữ nghĩa (semantic versioning)** nếu các bản sửa lỗi làm thay đổi API
4. **Tôn trọng giới hạn tần suất gọi (rate limits)** khi kiểm thử các dịch vụ bên ngoài
5. **Sử dụng cờ tính năng (feature flags)** cho các bản sửa lỗi có rủi ro cao (nếu áp dụng được)
6. **Cân nhắc chiến lược hoàn tác (rollback strategy)** cho từng bản sửa lỗi
7. **Tài liệu hóa các giả định** đã đặt ra trong quá trình phân tích

## Định dạng Đầu ra
Cung cấp kết quả ở cả ba định dạng:
- Markdown để con người dễ đọc
- JSON/YAML để xử lý tự động bằng máy
- CSV để nhập (import) vào các hệ thống quản lý theo dõi lỗi (bug tracking systems)

## Các Cân nhắc Đặc biệt
- Đối với kho mã nguồn đơn khối đa gói (monorepos): Phân tích riêng từng gói (package) một
- Đối với kiến trúc vi dịch vụ (microservices): Cân nhắc kỹ sự phụ thuộc lẫn nhau giữa các dịch vụ
- Đối với mã nguồn cũ (legacy code): Cân bằng giữa rủi ro khi sửa lỗi và lợi ích mang lại
- Đối với các thư viện phụ thuộc của bên thứ ba: Báo cáo lỗi lên dự án gốc (upstream) nếu cần thiết