# Sửa Lỗi Khả Năng Tiếp Cận trong Mã Nguồn - Chỉ Mục Tổng Hợp

**Tạo lúc**: 2026-04-10  
**Phạm vi**: Giao diện người dùng GoodGo (apps/web)  
**Trạng thái**: Sẵn sàng triển khai

---

## 📚 Các Tệp Tài Liệu

### 1. **ACCESSIBILITY_QUICK_SUMMARY.txt** ⚡
**Dùng cho**: Tham khảo nhanh, danh sách kiểm tra, checklist triển khai
- Liệt kê tất cả 6 vấn đề kèm vị trí chính xác
- Đường dẫn tệp và số dòng
- Mô tả sửa lỗi nhanh
- Danh sách các bước triển khai
- **Phù hợp nhất cho**: Trưởng nhóm, đánh giá nhanh

### 2. **ACCESSIBILITY_FIXES_REPORT.md** 📋
**Dùng cho**: Hiểu toàn diện từng vấn đề
- Giải thích chi tiết từng vấn đề
- Đoạn mã hiện tại
- Các bản sửa lỗi được đề xuất kèm giải thích
- Lý do cần thực hiện từng sửa lỗi
- Mức độ ưu tiên triển khai
- Danh sách kiểm tra kiểm thử
- **Phù hợp nhất cho**: Lập trình viên thực hiện sửa lỗi, xem xét mã nguồn

### 3. **ACCESSIBILITY_DETAILED_FIXES.md** 🔧
**Dùng cho**: Triển khai từng bước
- So sánh mã nguồn trước/sau
- Nhiều lựa chọn giải pháp cho một số sửa lỗi
- Giải thích chi tiết các thay đổi
- Quy trình kiểm thử
- Hướng dẫn kiểm thử với trình đọc màn hình
- Kiểm thử điều hướng bằng bàn phím
- Lệnh kiểm thử tự động
- Thời gian ước tính cho từng sửa lỗi (tổng cộng 35-45 phút)
- **Phù hợp nhất cho**: Lập trình viên viết mã, chi tiết triển khai

---

## 🎯 6 Vấn Đề Tổng Quan

| # | Vấn đề | Tệp | Dòng | Loại | Mức độ | Thời gian |
|---|--------|-----|------|------|--------|-----------|
| 1 | Input tải tệp thiếu aria-label | image-upload.tsx | 118 | aria-label | CAO | 2 phút |
| 2 | Input tìm kiếm thiếu aria-label | search/page.tsx | 189 | aria-label | CAO | 2 phút |
| 3 | Checkbox tiêu đề thiếu aria-label | moderation/page.tsx | 222 | aria-label | CAO | 2 phút |
| 4 | Checkbox hàng thiếu aria-label | moderation/page.tsx | 242 | aria-label | CAO | 3 phút |
| 5 | Hình ảnh giả thiếu alt | search.spec.tsx | 46 | alt | TRUNG BÌNH | 2 phút |
| 6 | Vùng kéo-thả không hỗ trợ bàn phím | image-upload.tsx | 86-128 | enhancement | TRUNG BÌNH | 10 phút |

---

## 📖 Cách Sử Dụng Các Tài Liệu Này

### Dành cho Quản lý Dự án
1. Đọc **ACCESSIBILITY_QUICK_SUMMARY.txt**
2. Xem lại danh sách kiểm tra
3. Ước tính khoảng 40-50 phút cho tất cả sửa lỗi + kiểm thử

### Dành cho Lập trình viên
1. Bắt đầu với **ACCESSIBILITY_FIXES_REPORT.md** để hiểu vấn đề
2. Dùng **ACCESSIBILITY_DETAILED_FIXES.md** để triển khai
3. Làm theo các ví dụ trước/sau
4. Chạy các quy trình kiểm thử

### Dành cho QA/Kiểm thử viên
1. Xem phần "Kiểm tra Sau Khi Triển khai" trong **ACCESSIBILITY_DETAILED_FIXES.md**
2. Dùng hướng dẫn kiểm thử với trình đọc màn hình
3. Dùng quy trình kiểm thử điều hướng bàn phím
4. Chạy lệnh kiểm thử tự động

### Dành cho Người Xem xét Mã nguồn
1. Tham chiếu **ACCESSIBILITY_FIXES_REPORT.md** để biết các thay đổi dự kiến
2. Xác minh từng sửa lỗi khớp với mã được đề xuất
3. Kiểm tra quy trình kiểm thử đã được thực hiện

---

## ✅ Những Gì Đã Tuân Thủ

**Những mục này KHÔNG cần thay đổi**:
- ✅ 6 component Image đã có thuộc tính alt
- ✅ 2 nút Icon đã có aria-label
- ✅ 2 Dialog đã có tiêu đề ngữ nghĩa
- ✅ 1 Checkbox đã có nhãn liên kết
- ✅ Nhiều nhãn form được liên kết đúng cách

---

## 🚀 Lộ Trình Triển Khai

### Giai đoạn 1: aria-label Ưu Tiên Cao (10 phút)
- [ ] Sửa lỗi #1: Input tải tệp (2 phút)
- [ ] Sửa lỗi #2: Input hộp thoại tìm kiếm (2 phút)
- [ ] Sửa lỗi #3: Checkbox tiêu đề (2 phút)
- [ ] Sửa lỗi #4: Checkbox hàng (3 phút)

### Giai đoạn 2: Ưu Tiên Trung Bình (12 phút)
- [ ] Sửa lỗi #5: Hình ảnh giả trong kiểm thử (2 phút)
- [ ] Sửa lỗi #6: Cải tiến kéo-thả (10 phút)

### Giai đoạn 3: Kiểm thử & Xác minh (20-30 phút)
- [ ] Kiểm thử với trình đọc màn hình
- [ ] Kiểm thử điều hướng bằng bàn phím
- [ ] Kiểm thử tự động (axe, lighthouse)
- [ ] Kiểm tra trực quan

### Giai đoạn 4: Triển khai
- [ ] Xem xét mã nguồn
- [ ] Hợp nhất vào nhánh main
- [ ] Triển khai lên môi trường sản xuất
- [ ] Cập nhật tài liệu khả năng tiếp cận

---

## 🧪 Lệnh Kiểm thử

```bash
# Chạy kiểm tra khả năng tiếp cận ESLint
npm run lint

# Chạy kiểm thử khả năng tiếp cận tự động (nếu đã cấu hình)
npm run test:a11y

# Chạy Lighthouse
npx lighthouse https://localhost:3000 --view

# Chạy tệp kiểm thử cụ thể
npm test search.spec.tsx
```

---

## 📞 Tóm Tắt Giải Quyết Vấn Đề

### Phân loại Vấn đề

**1. Khả năng Tiếp cận của Input Form** (Vấn đề #1, #2, #3, #4)
- Các input ẩn hoặc không liên kết thiếu aria-label
- Vị trí: Input form, checkbox trong hộp thoại và bảng dữ liệu
- Sửa lỗi: Thêm thuộc tính aria-label
- Tác động: Người dùng dùng trình đọc màn hình có thể truy cập các input này

**2. Khả năng Tiếp cận của Hình ảnh** (Vấn đề #5)
- Các component giả không bắt buộc thuộc tính alt
- Vị trí: Các tệp kiểm thử
- Sửa lỗi: Thêm prop alt vào component giả
- Tác động: Kiểm thử sẽ phát hiện alt bị thiếu trong quá trình phát triển

**3. Điều hướng Bằng Bàn phím** (Vấn đề #6)
- Vùng kéo-thả chưa hỗ trợ đầy đủ bàn phím
- Vị trí: Component tải ảnh lên
- Sửa lỗi: Thêm role, tabIndex, trình xử lý onKeyDown
- Tác động: Người dùng chỉ dùng bàn phím có thể truy cập vùng kéo-thả

---

## ✨ Đảm Bảo Chất Lượng

**Tuân thủ WCAG 2.1 Cấp độ AA**:
- ✅ Perceivable: Tất cả hình ảnh có văn bản alt
- ✅ Operable: Tất cả phần tử tương tác có thể dùng bàn phím
- ✅ Understandable: Tất cả input form có nhãn
- ✅ Robust: Tất cả HTML ngữ nghĩa được dùng đúng cách

**Cải Thiện Dự Kiến**:
- Tương thích trình đọc màn hình: Cải thiện đáng kể
- Điều hướng bằng bàn phím: Tất cả khu vực đều có thể truy cập
- Kiểm thử tự động: Sẽ phát hiện các hồi quy khả năng tiếp cận trong tương lai
- Trải nghiệm người dùng: Tốt hơn cho tất cả người dùng, đặc biệt người khuyết tật

---

## 📋 Danh Sách Kiểm Tra Triển Khai

### Trước Khi Bắt Đầu
- [ ] Tạo nhánh tính năng: `git checkout -b fix/accessibility-improvements`
- [ ] Xem lại cả ba tệp tài liệu
- [ ] Cài đặt trình đọc màn hình để kiểm thử (VoiceOver, NVDA, hoặc JAWS)

### Trong Quá Trình Triển Khai
- [ ] Thực hiện thay đổi theo ACCESSIBILITY_DETAILED_FIXES.md
- [ ] Kiểm thử từng sửa lỗi riêng lẻ
- [ ] Commit các thay đổi với thông điệp rõ ràng
- [ ] Chạy linter và kiểm thử

### Sau Khi Triển Khai
- [ ] Kiểm thử với trình đọc màn hình
- [ ] Kiểm thử điều hướng bàn phím
- [ ] Chạy kiểm thử khả năng tiếp cận tự động
- [ ] Nhận xem xét mã nguồn
- [ ] Hợp nhất vào nhánh main
- [ ] Cập nhật tài liệu khả năng tiếp cận nội bộ

---

## 🔗 Quan Hệ Giữa Các Tệp

```
ACCESSIBILITY_CODE_FIXES_INDEX.md (tệp này)
│
├─ ACCESSIBILITY_QUICK_SUMMARY.txt
│  └─ Danh sách kiểm tra nhanh, phù hợp cho quản lý/trưởng nhóm
│
├─ ACCESSIBILITY_FIXES_REPORT.md
│  └─ Báo cáo toàn diện kèm giải thích
│  └─ Bao gồm lý do cho từng sửa lỗi
│
└─ ACCESSIBILITY_DETAILED_FIXES.md
   └─ Hướng dẫn triển khai kèm ví dụ mã nguồn
   └─ Bao gồm quy trình kiểm thử
```

---

## 📞 Câu Hỏi?

Nếu bạn có câu hỏi về:
- **Hiểu vấn đề**: Xem ACCESSIBILITY_FIXES_REPORT.md
- **Cách triển khai**: Xem ACCESSIBILITY_DETAILED_FIXES.md
- **Tham khảo nhanh**: Xem ACCESSIBILITY_QUICK_SUMMARY.txt
- **Quy trình kiểm thử**: Xem phần "Kiểm tra Sau Khi Triển khai" trong ACCESSIBILITY_DETAILED_FIXES.md

---

## 📊 Chỉ Số Khả Năng Tiếp Cận

**Sau Khi Triển Khai**:
- Tương thích Trình đọc Màn hình: ✅ 100%
- Điều hướng Bàn phím: ✅ 100%
- WCAG 2.1 Cấp độ AA: ✅ Đạt được
- Điểm Khả năng Tiếp cận (Lighthouse): Dự kiến cải thiện 15-20 điểm

---

**Trạng thái**: ✅ SẴN SÀNG TRIỂN KHAI  
**Thời gian Ước tính**: 35-50 phút  
**Số Tệp Cần Sửa đổi**: 5  
**Số Lập trình viên Cần**: 1  
**Độ Phức tạp**: Thấp đến Trung bình

---

*Được tạo bởi kiểm tra khả năng tiếp cận toàn diện vào ngày 2026-04-10*
*Tất cả số dòng và đường dẫn tệp đã được xác minh*