İzzet Emre Arı

---
name: ast-code-analysis-superpower
description: Phân tích mẫu mã nguồn dựa trên cây cú pháp trừu tượng (AST) bằng công cụ ast-grep để phát hiện các vấn đề về bảo mật, hiệu năng và cấu trúc. Sử dụng khi (1) rà soát mã nguồn để tìm lỗ hổng bảo mật, (2) phân tích các phụ thuộc của React hook hoặc các mẫu hiệu năng, (3) phát hiện các phản mẫu cấu trúc trên các kho mã nguồn lớn, (4) cần đối sánh mẫu có hệ thống vượt ra ngoài khả năng kiểm tra thủ công bằng mắt thường.
---

# Phân tích Mã nguồn bằng AST-Grep

Kỹ thuật đối sánh mẫu AST xác định các vấn đề trong mã nguồn thông qua việc nhận diện cấu trúc cú pháp thay vì đọc từng dòng chữ đơn thuần. Cấu trúc mã nguồn hé lộ những mối quan hệ ẩn, các lỗ hổng và các phản mẫu (anti-patterns) mà việc kiểm tra bề mặt dễ dàng bỏ sót.

## Cấu hình

- **Ngôn ngữ Mục tiêu**: javascript
- **Trọng tâm Phân tích**: security
- **Mức độ Nghiêm trọng**: ERROR
- **Framework**: React
- **Độ sâu Lồng nhau Tối đa**: 3

## Điều kiện Tiên quyết

```bash
# Install ast-grep (if not available)
npm install -g @ast-grep/cli
# Or: mise install -g ast-grep
```

## Cây Quyết định: Khi nào Nên Dùng Phân tích AST

```
Cần rà soát mã nguồn (Code review)?
|
+-- Mã đơn giản (<50 dòng, cấu trúc hiển nhiên) --> Rà soát thủ công
|
+-- Mã phức tạp (lồng nhau sâu, trải trên nhiều tệp, nhiều tầng trừu tượng)
    |
    +-- Cần rà soát bảo mật? --> Sử dụng các mẫu bảo mật (security patterns)
    +-- Phân tích hiệu năng? --> Sử dụng các mẫu hiệu năng (performance patterns)
    +-- Chất lượng cấu trúc? --> Sử dụng các mẫu cấu trúc (structure patterns)
    +-- Tìm mẫu xuyên qua nhiều tệp? --> Chạy kèm cờ --include glob
```

## Các Danh mục Mẫu (Pattern Categories)

| Danh mục | Trọng tâm | Các Phát hiện Thường gặp |
|----------|-------|-----------------|
| Bảo mật (Security) | Các hàm mật mã học, luồng xác thực | Thông tin bí mật gắn cứng trong mã, tạo token yếu |
| Hiệu năng (Performance) | Hooks, vòng lặp, xử lý bất đồng bộ | Vòng lặp kết xuất lại (re-renders) vô hạn, rò rỉ bộ nhớ |
| Cấu trúc (Structure) | Độ sâu lồng nhau, độ phức tạp | Câu lệnh điều kiện lồng quá sâu, khó bảo trì |

## Các Mẫu Thiết yếu

### Bảo mật: Thông tin Bí mật Gắn cứng trong Mã (Hardcoded Secrets)

```yaml
# sg-rules/security/hardcoded-secrets.yml
id: hardcoded-secrets
language: javascript
rule:
  pattern: |
    const $VAR = '$LITERAL';
    $FUNC($VAR, ...)
  meta:
    severity: ERROR
    message: "Potential hardcoded secret detected"
```

### Bảo mật: Khởi tạo Token Không An toàn

```yaml
# sg-rules/security/insecure-tokens.yml
id: insecure-token-generation
language: javascript
rule:
  pattern: |
    btoa(JSON.stringify($OBJ) + '.' + $SECRET)
  meta:
    severity: ERROR
    message: "Insecure token generation using base64"
```

### Hiệu năng: Phụ thuộc của Hook trong React

```yaml
# sg-rules/performance/react-hook-deps.yml
id: react-hook-dependency-array
language: typescript
rule:
  pattern: |
    useEffect(() => {
      $BODY
    }, [$FUNC])
  meta:
    severity: WARNING
    message: "Function dependency may cause infinite re-renders"
```

### Cấu trúc: Lồng nhau Quá sâu (Deep Nesting)

```yaml
# sg-rules/structure/deep-nesting.yml
id: deep-nesting
language: javascript
rule:
  any:
    - pattern: |
        if ($COND1) {
          if ($COND2) {
            if ($COND3) {
              $BODY
            }
          }
        }
    - pattern: |
        for ($INIT) {
          for ($INIT2) {
            for ($INIT3) {
              $BODY
            }
          }
        }
  meta:
    severity: WARNING
    message: "Deep nesting (>3 levels) - consider refactoring"
```

## Chạy Phân tích

```bash
# Security scan
ast-grep run -r sg-rules/security/

# Performance scan on React files
ast-grep run -r sg-rules/performance/ --include="*.tsx,*.jsx"

# Full scan with JSON output
ast-grep run -r sg-rules/ --format=json > analysis-report.json

# Interactive mode for investigation
ast-grep run -r sg-rules/ --interactive
```

## Danh sách Kiểm tra Khi Viết Mẫu (Pattern Writing)

- [ ] Mẫu khớp chính xác với phản mẫu cụ thể, không bắt nhầm mã nguồn thông thường
- [ ] Sử dụng `inside` hoặc `has` để giới hạn ràng buộc ngữ cảnh
- [ ] Bao gồm các mệnh đề phủ định `not` nhằm giảm thiểu báo động giả (false positives)
- [ ] Tách riêng quy tắc cho từng ngôn ngữ (JS so với TS)
- [ ] Gán mức độ nghiêm trọng phù hợp (ERROR/WARNING/INFO)

## Các Lỗi Thường gặp

| Lỗi | Triệu chứng | Cách khắc phục |
|---------|---------|-----|
| Mẫu quá chung chung | Xuất hiện nhiều báo động giả | Bổ sung các ràng buộc ngữ cảnh |
| Thiếu ràng buộc `inside` | Khớp nhầm ở các vị trí không mong muốn | Giới hạn phạm vi bằng ngữ cảnh nút cha |
| Không có mệnh đề `not` | Bắt luôn cả các đoạn mã hợp lệ | Loại trừ các trường hợp chuẩn đã biết |
| Chạy mẫu JS trên mã TS | Chú thích kiểu dữ liệu (type annotations) làm hỏng kết quả khớp | Tạo bộ quy tắc riêng biệt cho từng ngôn ngữ |

## Các Bước Xác minh

1. **Kiểm thử độ chính xác của mẫu**: Chạy thử trên các mẫu mã nguồn đã biết trước là có lỗ hổng
2. **Kiểm tra tỷ lệ báo động giả**: Rà soát thủ công 10 kết quả khớp đầu tiên
3. **Xác thực mức độ nghiêm trọng**: Xác nhận các phát hiện ở mức ERROR thực sự cần và có thể xử lý ngay
4. **Độ bao phủ xuyên tệp**: Xác minh mẫu quét qua đúng toàn bộ phạm vi dự kiến

## Ví dụ Kết quả Đầu ra

```
$ ast-grep run -r sg-rules/
src/components/UserProfile.jsx:15: ERROR [insecure-tokens] Insecure token generation
src/hooks/useAuth.js:8: ERROR [hardcoded-secrets] Potential hardcoded secret
src/components/Dashboard.tsx:23: WARNING [react-hook-deps] Function dependency
src/utils/processData.js:45: WARNING [deep-nesting] Deep nesting detected

Found 4 issues (2 errors, 2 warnings)
```

## Thiết lập Dự án

```bash
# Initialize ast-grep in project
ast-grep init

# Create rule directories
mkdir -p sg-rules/{security,performance,structure}

# Add to CI pipeline
# .github/workflows/lint.yml
# - run: ast-grep run -r sg-rules/ --format=json
```

## Mẫu Tự Tạo Quy tắc Tùy chỉnh

### Các Mẫu Đặc thù cho React

```yaml
# Missing key in list rendering
id: missing-list-key
language: typescript
rule:
  pattern: |
    $ARRAY.map(($ITEM) => <$COMPONENT $$$PROPS />)
  constraints:
    $PROPS:
      not:
        has:
          pattern: 'key={$_}'
  meta:
    severity: WARNING
    message: "Missing key prop in list rendering"
```

### Các Mẫu Bất đồng bộ (Async/Await)

```yaml
# Missing error handling in async
id: unhandled-async
language: javascript
rule:
  pattern: |
    async function $NAME($$$) {
      $$$BODY
    }
  constraints:
    $BODY:
      not:
        has:
          pattern: 'try { $$$ } catch'
  meta:
    severity: WARNING
    message: "Async function without try-catch error handling"
```

## Tích hợp vào CI/CD

```yaml
# GitHub Actions example
name: AST Analysis
on: [push, pull_request]
jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install ast-grep
        run: npm install -g @ast-grep/cli
      - name: Run analysis
        run: |
          ast-grep run -r sg-rules/ --format=json > report.json
          if grep -q '"severity": "ERROR"' report.json; then
            echo "Critical issues found!"
            exit 1
          fi
```

---
name: aws-cloud-expert
description: |
  Thiết kế và triển khai kiến trúc đám mây AWS tập trung vào Khung Kiến trúc Tối ưu (Well-Architected Framework), tối ưu hóa chi phí và bảo mật. Sử dụng khi:
  1. Thiết kế hoặc rà soát kiến trúc hạ tầng AWS
  2. Di chuyển các tải công việc (workloads) lên AWS hoặc giữa các dịch vụ AWS
  3. Tối ưu hóa chi phí AWS (chọn đúng kích cỡ tài nguyên, Reserved Instances, Savings Plans)
  4. Triển khai bảo mật, tuân thủ hoặc khôi phục sau thảm họa trên AWS
  5. Khắc phục sự cố dịch vụ AWS hoặc các vấn đề về hiệu năng
---

**Khu vực (Region)**: us-east-1
**Khu vực Dự phòng (Secondary Region)**: us-west-2
**Môi trường (Environment)**: production
**VPC CIDR**: 10.0.0.0/16
**Loại Phiên bản (Instance Type)**: t3.medium

# Khung Quyết định Kiến trúc AWS

## Ma trận Lựa chọn Dịch vụ

| Loại Tải công việc (Workload) | Dịch vụ Chính | Phương án Thay thế | Yếu tố Quyết định |
|---------------|-----------------|-------------|-----------------|
| API không lưu trạng thái (Stateless) | Lambda + API Gateway | ECS Fargate | Thời gian xử lý yêu cầu >15 phút -> ECS |
| Ứng dụng web có lưu trạng thái (Stateful) | ECS/EKS | EC2 Auto Scaling | Chuyên môn về container -> ECS/EKS |
| Xử lý theo lô (Batch processing) | Step Functions + Lambda | AWS Batch | Cần GPU/chạy thời gian dài -> Batch |
| Truyền luồng thời gian thực | Kinesis Data Streams | MSK (Kafka) | Đang có sẵn hệ thống Kafka -> MSK |
| Trang web tĩnh | S3 + CloudFront | Amplify | Ứng dụng Full-stack -> Amplify |
| Cơ sở dữ liệu quan hệ | Aurora | RDS | Độ sẵn sàng cao -> Aurora |
| Kho lưu trữ khóa-giá trị (Key-value) | DynamoDB | ElastiCache | Độ trễ dưới một mili-giây -> ElastiCache |
| Kho dữ liệu (Data warehouse) | Redshift | Athena | Truy vấn đột xuất (Ad-hoc queries) -> Athena |

## Cây Quyết định Tài nguyên Tính toán (Compute)

```
Bắt đầu: Đặc điểm tải công việc của bạn là gì?
|
+-> Hướng sự kiện (Event-driven), thời gian chạy <15 phút
|   +-> Lambda
|       Cân nhắc: Bộ nhớ 512MB, số lượng thực thi đồng thời, khởi động lạnh (cold starts)
|
+-> Các container chạy liên tục dài hạn
|   +-> Có cần dùng Kubernetes không?
|       +-> Có: EKS (được quản lý) hoặc tự quản lý K8s trên EC2
|       +-> Không: ECS Fargate (serverless) hoặc ECS EC2 (tối ưu hóa chi phí)
|
+-> Yêu cầu GPU/HPC/AMI tùy chỉnh
|   +-> EC2 với dòng máy (instance family) phù hợp
|       g4dn/p4d (Học máy ML), c6i (tính toán), r6i (bộ nhớ), i3en (lưu trữ)
|
+-> Các tác vụ chạy theo lô, dựa trên hàng đợi
    +-> AWS Batch kết hợp Spot instances (tiết kiệm tới 90% chi phí)
```

## Kiến trúc Mạng (Networking Architecture)

### Mẫu Thiết kế VPC

```
VPC Môi trường production (10.0.0.0/16)
|
+-- Các Mạng con Công cộng - Public Subnets (10.0.0.0/24, 10.0.1.0/24, 10.0.2.0/24)
|   +-- ALB, NAT Gateways, máy chủ Bastion (nếu cần)
|
+-- Các Mạng con Riêng tư - Private Subnets (10.0.10.0/24, 10.0.11.0/24, 10.0.12.0/24)
|   +-- Tầng ứng dụng (ECS, EC2, Lambda VPC)
|
+-- Các Mạng con Dữ liệu - Data Subnets (10.0.20.0/24, 10.0.21.0/24, 10.0.22.0/24)
    +-- RDS, ElastiCache, các kho dữ liệu khác
```

### Quy tắc Nhóm Bảo mật (Security Group Rules)

| Tầng | Lưu lượng Đi vào Từ | Cổng (Ports) |
|------|--------------|-------|
| ALB | 0.0.0.0/0 | 443 |
| App | ALB SG | 8080 |
| Data | App SG | 5432 |

### Điểm cuối VPC (VPC Endpoints - Tối ưu hóa Chi phí)

Luôn khởi tạo cho các dịch vụ có lưu lượng truy cập cao:
- S3 Gateway Endpoint (miễn phí)
- DynamoDB Gateway Endpoint (miễn phí)
- Interface Endpoints: ECR, Secrets Manager, SSM, CloudWatch Logs

## Danh sách Kiểm tra Tối ưu hóa Chi phí

### Hành động Thực hiện Ngay (Tuần 1)
- [ ] Bật Cost Explorer và thiết lập ngân sách kèm cảnh báo
- [ ] Rà soát và chấm dứt các tài nguyên không sử dụng (báo cáo tài nguyên nhàn rỗi trên Cost Explorer)
- [ ] Tinh chỉnh đúng kích cỡ các máy ảo EC2 (theo khuyến nghị từ AWS Compute Optimizer)
- [ ] Xóa các ổ đĩa EBS không được gắn vào máy nào và các bản chụp nhanh (snapshots) cũ
- [ ] Rà soát phí xử lý dữ liệu qua NAT Gateway

### Tham khảo Nhanh Ước tính Chi phí

| Tài nguyên | Chi phí Ước tính Hàng tháng |
|----------|----------------------|
| t3.medium (theo nhu cầu on-demand) | ~$30 |
| t3.medium (cam kết 1 năm RI) | ~$18 |
| Lambda (1 triệu lượt gọi, 1 giây, 512MB) | ~$8 |
| RDS db.t3.medium (Đa vùng khả dụng Multi-AZ) | ~$100 |
| Aurora Serverless v2 (trung bình 8 ACU) | ~$350 |
| NAT Gateway + 100GB dữ liệu | ~$50 |
| S3 (1TB gói Standard) | ~$23 |
| CloudFront (1TB dung lượng truyền tải) | ~$85 |

## Triển khai Bảo mật

### Các Thực hành Tốt nhất về IAM

```
Nguyên tắc: Đặc quyền tối thiểu kết hợp từ chối tường minh (explicit deny)

1. Sử dụng vai trò IAM (IAM roles) thay vì người dùng (users) cho các ứng dụng
2. Bắt buộc xác thực đa yếu tố (MFA) đối với mọi người dùng là con người
3. Sử dụng ranh giới quyền hạn (permission boundaries) khi ủy quyền quản trị
4. Triển khai Chính sách Kiểm soát Dịch vụ (SCPs) ở cấp độ Tổ chức (Organization)
5. Rà soát quyền truy cập định kỳ bằng IAM Access Analyzer
```

### Mẫu Chính sách IAM Ví dụ

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowS3BucketAccess",
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject"],
      "Resource": "arn:aws:s3:::my-bucket/*",
      "Condition": {
        "StringEquals": {"aws:PrincipalTag/Environment": "production"}
      }
    }
  ]
}
```

### Danh sách Kiểm tra Bảo mật

- [ ] Bật CloudTrail ở tất cả các khu vực kèm tính năng xác thực tính toàn vẹn tệp nhật ký
- [ ] Cấu hình các quy tắc AWS Config để giám sát tính tuân thủ
- [ ] Bật GuardDuty để phát hiện mối đe dọa
- [ ] Sử dụng Secrets Manager hoặc Parameter Store để lưu thông tin bí mật (không lưu trong biến môi trường)
- [ ] Bật mã hóa dữ liệu khi lưu trữ (encryption at rest) cho tất cả các kho dữ liệu
- [ ] Bắt buộc sử dụng chuẩn TLS 1.2 trở lên cho mọi kết nối
- [ ] Triển khai VPC Flow Logs để giám sát lưu lượng mạng
- [ ] Sử dụng Security Hub để có cái nhìn bảo mật tập trung

## Các Mẫu Độ Sẵn sàng Cao (High Availability)

### Kiến trúc Đa Vùng Khả dụng - Multi-AZ (mục tiêu 99.99%)

```
Khu vực (Region): us-east-1
|
+-- AZ-a                    +-- AZ-b                    +-- AZ-c
    |                           |                           |
    ALB (đang hoạt động)        ALB (đang hoạt động)        ALB (đang hoạt động)
    |                           |                           |
    ECS Tasks (2)  ECS Tasks (2)  ECS Tasks (2)
    |                           |                           |
    Aurora Writer (Ghi)         Aurora Reader (Đọc)         Aurora Reader (Đọc)
```

### Kiến trúc Đa Khu vực - Multi-Region (mục tiêu 99.999%)

```
Khu vực Chính: us-east-1     Khu vực Dự phòng: us-west-2
|                               |
Route 53 (định tuyến dự phòng)  Route 53 (kiểm tra trạng thái hoạt động)
|                               |
CloudFront                      CloudFront
|                               |
Toàn bộ ngăn xếp (Full stack)   Toàn bộ ngăn xếp (thụ động hoặc chủ động)
|                               |
Aurora Global Database -------> Bản sao Đọc Aurora (Aurora Read Replica)
      (nhân bản bất đồng bộ)
```

### Ma trận Quyết định RTO/RPO

| Phân tầng | Mục tiêu RTO | Mục tiêu RPO | Chiến lược |
|------|------------|------------|----------|
| Tầng 1 (Trọng yếu) | <15 min | <1 min | Đa khu vực chủ động-chủ động (active-active) |
| Tầng 2 (Quan trọng) | <1 giờ | <15 phút | Đa khu vực chủ động-thụ động (active-passive) |
| Tầng 3 (Tiêu chuẩn) | <4 giờ | <1 giờ | Đa vùng khả dụng (Multi-AZ) kèm sao lưu liên khu vực |
| Tầng 4 (Không trọng yếu) | <24 giờ | <24 giờ | Một khu vực duy nhất, sao lưu/khôi phục |

## Giám sát và Quan sát Hệ thống (Observability)

### Triển khai CloudWatch

| Loại Chỉ số | Dịch vụ | Các Chỉ số Quan trọng |
|-------------|---------|-------------|
| Tính toán (Compute) | EC2/ECS | CPUUtilization, MemoryUtilization, NetworkIn/Out |
| Cơ sở dữ liệu | RDS/Aurora | DatabaseConnections, ReadLatency, WriteLatency |
| Không máy chủ (Serverless) | Lambda | Duration, Errors, Throttles, ConcurrentExecutions |
| API | API Gateway | 4XXError, 5XXError, Latency, Count |
| Lưu trữ (Storage) | S3 | BucketSizeBytes, NumberOfObjects, 4xxErrors |

### Ngưỡng Cảnh báo

| Tài nguyên | Cảnh báo (Warning) | Nguy kịch (Critical) | Hành động |
|----------|---------|----------|--------|
| CPU của EC2 | >70% trong 5 phút | >90% trong 5 phút | Mở rộng quy mô ngang (Scale out), điều tra nguyên nhân |
| CPU của RDS | >80% trong 5 phút | >95% trong 5 phút | Nâng cấp cấu hình (Scale up), tối ưu hóa truy vấn |
| Lỗi Lambda | >1% | >5% | Điều tra nguyên nhân, hoàn tác (rollback) |
| Lỗi 5xx trên ALB | >0.1% | >1% | Kiểm tra hệ thống backend |
| Bóp băng thông DynamoDB | Bất kỳ | Kéo dài liên tục | Tăng dung lượng cấp phát |

## Danh sách Kiểm tra Xác minh

### Trước khi Ra mắt Môi trường Production

- [ ] Đã hoàn tất Đánh giá Khung Kiến trúc Tối ưu (Well-Architected Review - đủ cả 6 trụ cột)
- [ ] Đã hoàn tất kiểm thử chịu tải ở mức đỉnh dự kiến + 50% khoảng dự phòng
- [ ] Đã diễn tập khôi phục sau thảm họa với chỉ số RTO/RPO được ghi nhận rõ ràng
- [ ] Đã vượt qua đánh giá bảo mật (kiểm thử xâm nhập nếu có yêu cầu)
- [ ] Đã xác minh các biện pháp kiểm soát tuân thủ (nếu áp dụng)
- [ ] Đã cấu hình bảng điều khiển giám sát và hệ thống cảnh báo
- [ ] Đã lập tài liệu sổ tay vận hành (runbooks) cho các thao tác thường gặp
- [ ] Đã xác thực dự phóng chi phí và thiết lập ngân sách
- [ ] Đã triển khai chiến lược gắn thẻ (tagging) cho toàn bộ tài nguyên
- [ ] Đã kiểm thử quy trình sao lưu và khôi phục dữ liệu

---
name: accessibility-expert
description: Kiểm thử và khắc phục các vấn đề về khả năng tiếp cận (accessibility) nhằm tuân thủ chuẩn WCAG và tương thích với công nghệ hỗ trợ. Sử dụng khi (1) kiểm toán giao diện UI để tìm các vi phạm về khả năng tiếp cận, (2) triển khai điều hướng bằng bàn phím hoặc hỗ trợ trình đọc màn hình, (3) sửa lỗi độ tương phản màu sắc hoặc chỉ báo tiêu điểm (focus indicator), (4) đảm bảo khả năng tiếp cận cho biểu mẫu (form) và xử lý lỗi, (5) xây dựng các triển khai ARIA.
---

# Kiểm thử và Khắc phục Khả năng Tiếp cận (Accessibility)

## Cấu hình

- **Cấp độ WCAG**: AA
- **Thành phần Mục tiêu**: Application
- **Tiêu chuẩn Tuân thủ**: WCAG 2.1
- **Phạm vi Kiểm thử**: full-audit
- **Trình đọc Màn hình**: NVDA

## Tham khảo Nhanh WCAG 2.1

### Các Cấp độ Tuân thủ
| Cấp độ | Yêu cầu | Các Vấn đề Thường gặp |
|-------|-------------|---------------|
| A | Mức cơ sở tối thiểu | Thiếu văn bản thay thế (alt text), không truy cập được bằng bàn phím, thiếu nhãn biểu mẫu (form labels) |
| AA | Mục tiêu tiêu chuẩn | Độ tương phản < 4.5:1, thiếu chỉ báo tiêu điểm (focus indicators), cấu trúc thẻ tiêu đề (heading) kém |
| AAA | Nâng cao | Độ tương phản < 7:1, ngôn ngữ ký hiệu, mô tả âm thanh mở rộng |

### Bốn Nguyên tắc (POUR)
1. **Có thể cảm nhận được (Perceivable)**: Nội dung tiếp nhận được qua các giác quan (văn bản thay thế alt text, phụ đề captions, độ tương phản)
2. **Có thể thao tác được (Operable)**: Giao diện UI điều hướng được bằng mọi phương thức đầu vào (bàn phím, cảm ứng, giọng nói)
3. **Có thể hiểu được (Understandable)**: Nội dung và giao diện UI dễ đoán và dễ đọc
4. **Vững chắc (Robust)**: Hoạt động tốt với các công nghệ hỗ trợ hiện tại và tương lai

## Ma trận Mức độ Nghiêm trọng của Vi phạm

```
CRITICAL - NGUY KỊCH (sửa ngay lập tức):
  - Không thể truy cập bằng bàn phím tới các phần tử tương tác
  - Thiếu nhãn biểu mẫu (form labels)
  - Hình ảnh không có văn bản thay thế (alt text)
  - Âm thanh tự động phát không có nút điều khiển
  - Bẫy bàn phím (Keyboard traps)

HIGH - CAO (sửa trước khi phát hành):
  - Tỷ lệ tương phản dưới 4.5:1 (văn bản thường) hoặc 3:1 (văn bản cỡ lớn)
  - Thiếu liên kết bỏ qua điều hướng (skip links)
  - Sai phân cấp thẻ tiêu đề (heading hierarchy)
  - Không nhìn thấy viền tiêu điểm (focus)
  - Thiếu nhận diện lỗi khi nhập liệu

MEDIUM - TRUNG BÌNH (sửa trong sprint tiếp theo):
  - Điều hướng thiếu nhất quán
  - Thiếu các vùng mốc trang (landmarks)
  - Văn bản liên kết kém rõ ràng ("nhấp vào đây" / "click here")
  - Thiếu thuộc tính ngôn ngữ (lang)
  - Bảng phức tạp không có ô tiêu đề (headers)

LOW - THẤP (đưa vào backlog):
  - Điều chỉnh thời gian chờ
  - Nhiều cách khác nhau để tìm kiếm nội dung
  - Trợ giúp theo ngữ cảnh
```

## Cây Quyết định Kiểm thử

```
Bắt đầu: Bạn đang kiểm thử thành phần nào?
|
+-- Thành phần Mới (New Component)
|   +-- Có các phần tử tương tác? --> Danh sách kiểm tra Điều hướng Bàn phím
|   +-- Có nội dung văn bản? --> Kiểm tra độ tương phản + cấu trúc tiêu đề heading
|   +-- Có hình ảnh? --> Xác minh tính phù hợp của văn bản thay thế alt text
|   +-- Có biểu mẫu (forms)? --> Danh sách kiểm tra Khả năng Tiếp cận Biểu mẫu
|
+-- Trang/Tính năng Hiện có (Existing Page/Feature)
|   +-- Chạy quét tự động trước (axe-core, Lighthouse)
|   +-- Duyệt kiểm tra thủ công bằng bàn phím
|   +-- Xác minh bằng trình đọc màn hình
|   +-- Kiểm tra điểm độ tương phản màu sắc
|
+-- Tiện ích Bên thứ ba (Third-party Widget)
    +-- Kiểm tra cách triển khai ARIA
    +-- Xác minh hỗ trợ bàn phím
    +-- Kiểm thử với trình đọc màn hình
    +-- Lập tài liệu ghi nhận các giới hạn
```

## Danh sách Kiểm tra Điều hướng Bàn phím

```markdown
[ ] Tất cả các phần tử tương tác đều di chuyển tới được bằng phím Tab
[ ] Thứ tự phím Tab tuân theo luồng thị giác/logic hợp lý
[ ] Chỉ báo tiêu điểm (focus indicator) hiển thị rõ (đường viền từ 2px trở lên, độ tương phản 3:1)
[ ] Không có bẫy bàn phím (có thể nhấn Tab thoát ra khỏi mọi phần tử)
[ ] Liên kết bỏ qua (Skip link) là phần tử đầu tiên nhận tiêu điểm
[ ] Phím Enter kích hoạt được các nút bấm và liên kết
[ ] Phím Space kích hoạt được các hộp kiểm (checkboxes) và nút bấm
[ ] Các phím mũi tên điều hướng bên trong các thành phần phức hợp (tabs, menus, radio groups)
[ ] Phím Escape đóng các cửa sổ modal và danh sách thả xuống (dropdowns)
[ ] Cửa sổ modal giữ tiêu điểm bên trong cho đến khi được đóng lại
```

## Các Mẫu Kiểm thử Trình đọc Màn hình

### Các Thông báo Thiết yếu Cần Xác minh
```
Phần tử Tương tác:
  Button: "[label], button"
  Link: "[text], link"
  Checkbox: "[label], checkbox, [checked/unchecked]"
  Radio: "[label], radio button, [selected], [position] of [total]"
  Combobox: "[label], combobox, [collapsed/expanded]"

Nội dung Động:
  Loading: Sử dụng aria-busy="true" trên phần tử chứa (container)
  Status: Sử dụng role="status" cho các cập nhật không khẩn cấp
  Alert: Sử dụng role="alert" cho các thông báo quan trọng/khẩn cấp
  Live regions: aria-live="polite"

Biểu mẫu (Forms):
  Required: đọc thông báo "required" cùng với nhãn
  Invalid: đọc "invalid entry" kèm theo thông báo lỗi
  Instructions: đọc hướng dẫn cùng với nhãn thông qua aria-describedby
```

### Trình tự Kiểm thử
1. Điều hướng toàn bộ trang bằng phím Tab, lắng nghe các thông báo đọc lên
2. Kiểm thử điều hướng theo thẻ tiêu đề (phím H trong trình đọc màn hình)
3. Kiểm thử điều hướng theo vùng mốc landmark (phím D / bộ xoay rotor)
4. Kiểm thử bảng biểu (phím T, các phím mũi tên bên trong bảng)
5. Kiểm thử biểu mẫu (phím F, hoàn tất việc gửi biểu mẫu)
6. Kiểm thử cập nhật nội dung động (xác minh các vùng live regions)

## Yêu cầu về Độ tương phản Màu sắc

| Loại Văn bản | Tỷ lệ Tối thiểu | Nâng cao (AAA) |
|-----------|---------------|----------------|
| Văn bản thường (<18pt) | 4.5:1 | 7:1 |
| Văn bản lớn (>=18pt hoặc 14pt in đậm) | 3:1 | 4.5:1 |
| Thành phần UI & đồ họa | 3:1 | N/A |
| Chỉ báo tiêu điểm (Focus indicators) | 3:1 | N/A |

### Quy trình Kiểm tra Độ tương phản
```
1. Xác định tất cả các cặp màu tiền cảnh (chữ/biểu tượng) và hậu cảnh (nền)
2. Tính tỷ lệ tương phản: (L1 + 0.05) / (L2 + 0.05)
   trong đó L1 = độ chói (luminance) sáng hơn, L2 = độ chói tối hơn
3. Các lỗi thường gặp cần kiểm tra:
   - Văn bản gợi ý giữ chỗ (Placeholder text - thường quá nhạt)
   - Trạng thái vô hiệu hóa (Disabled state - được miễn trừ nhưng vẫn nên cân nhắc tính dễ dùng)
   - Liên kết nằm trong đoạn văn bản (phải phân biệt được với văn bản thường)
   - Trạng thái lỗi/thành công trên nền màu
   - Văn bản đặt đè lên hình ảnh (cần dùng lớp phủ tối hoặc bóng đổ chữ)
```

## Hướng dẫn Triển khai ARIA

### Quy tắc Đầu tiên của ARIA
Sử dụng các phần tử HTML nguyên bản (native) bất cứ khi nào có thể. ARIA chỉ dành cho các tiện ích tùy chỉnh (custom widgets).

```html
<!-- WRONG: ARIA on native element -->
<div role="button" tabindex="0">Submit</div>

<!-- RIGHT: Native button -->
<button type="submit">Submit</button>
```

### Khi nào Cần dùng ARIA
```html
<!-- Custom tabs -->
<div role="tablist">
  <button role="tab" aria-selected="true" aria-controls="panel1">Tab 1</button>
  <button role="tab" aria-selected="false" aria-controls="panel2">Tab 2</button>
</div>
<div role="tabpanel" id="panel1">Content 1</div>
<div role="tabpanel" id="panel2" hidden>Content 2</div>

<!-- Expandable section -->
<button aria-expanded="false" aria-controls="content">Show details</button>
<div id="content" hidden>Expandable content</div>

<!-- Modal dialog -->
<div role="dialog" aria-modal="true" aria-labelledby="title">
  <h2 id="title">Dialog Title</h2>
  <!-- content -->
</div>

<!-- Live region for dynamic updates -->
<div aria-live="polite" aria-atomic="true">
  <!-- Status messages injected here -->
</div>
```

### Các Lỗi ARIA Thường gặp
```
- Gán role="button" nhưng không hỗ trợ bàn phím (phím Enter/Space)
- Thuộc tính aria-label lặp lại y hệt văn bản đang hiển thị trên màn hình
- Đặt aria-hidden="true" trên các phần tử có thể nhận tiêu điểm (focusable)
- Thiếu aria-expanded trên các nút đóng/mở nội dung ẩn (disclosure buttons)
- Tham chiếu aria-controls bị sai ID
- Sử dụng aria-describedby cho những thông tin thiết yếu bắt buộc phải thấy
```

## Các Mẫu Khả năng Tiếp cận cho Biểu mẫu (Form)

### Cấu trúc Biểu mẫu Bắt buộc
```html
<form>
  <!-- Explicit label association -->
  <label for="email">Email address</label>
  <input type="email" id="email" name="email"
         aria-required="true"
         aria-describedby="email-hint email-error">
  <span id="email-hint">We'll never share your email</span>
  <span id="email-error" role="alert"></span>

  <!-- Group related fields -->
  <fieldset>
    <legend>Shipping address</legend>
    <!-- address fields -->
  </fieldset>

  <!-- Clear submit button -->
  <button type="submit">Complete order</button>
</form>
```

### Yêu cầu Xử lý Lỗi
```
1. Xác định rõ trường đang bị lỗi (tô sáng + biểu tượng cảnh báo)
2. Mô tả lỗi bằng văn bản (không chỉ dựa vào màu sắc)
3. Liên kết thông báo lỗi với trường nhập liệu (dùng aria-describedby)
4. Phát thông báo lỗi cho trình đọc màn hình (dùng role="alert")
5. Di chuyển tiêu điểm (focus) tới trường lỗi đầu tiên khi gửi biểu mẫu thất bại
6. Cung cấp gợi ý sửa lỗi khi có thể
```

## Danh sách Kiểm tra Khả năng Tiếp cận trên Thiết bị Di động

```markdown
Vùng Chạm Cảm ứng (Touch Targets):
[ ] Kích thước tối thiểu 44x44 CSS pixels
[ ] Khoảng cách hợp lý giữa các vùng chạm (từ 8px trở lên)
[ ] Thao tác chạm không phụ thuộc vào quỹ đạo vuốt phức tạp

Cử chỉ (Gestures):
[ ] Có phương án thay thế cho các cử chỉ đa ngón tay
[ ] Có phương án thay thế cho các cử chỉ theo đường dẫn (vuốt swipe)
[ ] Các hành động dựa trên cảm biến chuyển động (lắc/nghiêng máy) đều có nút bấm thay thế

Trình đọc Màn hình (iOS/Android):
[ ] Đã thiết lập accessibilityLabel cho hình ảnh và biểu tượng
[ ] Có accessibilityHint cho các tương tác phức tạp
[ ] accessibilityRole khớp với hành vi của phần tử
[ ] Thứ tự tiêu điểm (focus order) tuân theo bố cục thị giác
```

## Tích hợp Kiểm thử Tự động

### Pre-commit Hook
```bash
#!/bin/bash
# Run axe-core on changed files
npx axe-core-cli --exit src/**/*.html

# Check for common issues
grep -r "onClick.*div\|onClick.*span" src/ && \
  echo "Warning: Click handler on non-interactive element" && exit 1
```

### Kiểm tra trong Đường ống CI (CI Pipeline Checks)
```yaml
accessibility-audit:
  script:
    - npx pa11y-ci --config .pa11yci.json
    - npx lighthouse --accessibility --output=json
  artifacts:
    paths:
      - accessibility-report.json
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
```

### Ngưỡng Tối thiểu trong CI
```
axe-core: 0 vi phạm mức nguy kịch (critical), 0 vi phạm mức nghiêm trọng (serious)
Điểm accessibility trên Lighthouse: >= 90
pa11y: 0 lỗi (chấp nhận cảnh báo warnings)
```

## Khung Ưu tiên Khắc phục

```
Ưu tiên 1 (Ngay trong Sprint này):
  - Chặn người dùng hoàn thành tác vụ
  - Rủi ro vi phạm pháp lý
  - Ảnh hưởng đến nhiều người dùng

Ưu tiên 2 (Sprint tiếp theo):
  - Làm suy giảm đáng kể trải nghiệm
  - Công cụ tự động gắn cờ báo lỗi
  - Vi phạm yêu cầu cấp độ AA

Ưu tiên 3 (Đưa vào Backlog):
  - Bất tiện nhỏ
  - Chỉ vi phạm cấp độ AAA
  - Ảnh hưởng đến các trường hợp biên hiếm gặp

Ưu tiên 4 (Cải tiến nâng cao):
  - Cải thiện khả năng sử dụng cho tất cả mọi người
  - Thực hành tốt nhất, không phải yêu cầu bắt buộc
  - Đón đầu tương lai (Future-proofing)
```

## Danh sách Kiểm tra Xác minh

Trước khi đánh dấu công việc về khả năng tiếp cận là hoàn thành:

```markdown
Tự động (Automated):
[ ] axe-core: 0 vi phạm
[ ] Điểm accessibility trên Lighthouse: từ 90 trở lên
[ ] Vượt qua bước kiểm tra hợp lệ HTML
[ ] Không có cảnh báo accessibility nào trên bảng điều khiển (console)

Bàn phím (Keyboard):
[ ] Hoàn thành mọi tác vụ khi chỉ dùng bàn phím
[ ] Tiêu điểm (focus) luôn hiển thị rõ ràng mọi lúc
[ ] Thứ tự phím Tab hợp lý
[ ] Không có bẫy bàn phím

Trình đọc Màn hình (kiểm thử với ít nhất một trình đọc):
[ ] Toàn bộ nội dung đều được đọc thông báo
[ ] Các phần tử tương tác đều có nhãn đầy đủ
[ ] Các lỗi và cập nhật trạng thái đều được thông báo
[ ] Điều hướng hiệu quả

Thị giác (Visual):
[ ] Toàn bộ văn bản đạt chuẩn độ tương phản
[ ] Các thành phần UI đạt chuẩn độ tương phản
[ ] Hoạt động tốt ở mức thu phóng 200%
[ ] Hoạt động tốt ở chế độ tương phản cao (high contrast mode)
[ ] Không có hiệu ứng nhấp nháy gây co giật

Biểu mẫu (Forms):
[ ] Tất cả các trường đều được gắn nhãn
[ ] Nhận diện rõ ràng được các lỗi
[ ] Các trường bắt buộc được chỉ báo rõ
[ ] Có sẵn hướng dẫn nhập liệu
```

## Mẫu Tài liệu Tuyên bố

```markdown
# Tuyên bố về Khả năng Tiếp cận (Accessibility Statement)

## Trạng thái Tuân thủ
[website/application] này tuân thủ [fully/partially] tiêu chuẩn WCAG 2.1 Cấp độ AA.

## Các Giới hạn Đã biết
| Tính năng | Vấn đề | Giải pháp Tạm thời | Lộ trình Khắc phục |
|---------|-------|------------|----------|
| [Feature] | [Description] | [Alternative] | [Fix date] |

## Công nghệ Hỗ trợ Đã Kiểm thử
- NVDA [version] trên Firefox [version]
- VoiceOver trên Safari [version]
- JAWS [version] trên Chrome [version]

## Phản hồi Góp ý
Liên hệ [email] nếu gặp các vấn đề về khả năng tiếp cận.
Cập nhật lần cuối: [date]
```

---
name: accessibility-testing-superpower
description: |
  Thực hiện kiểm toán mức độ tuân thủ chuẩn WCAG và khắc phục các lỗi khả năng tiếp cận (accessibility) cho ứng dụng web.
  Sử dụng khi: 1) Kiểm toán giao diện UI theo chuẩn WCAG 2.1/2.2 2) Khắc phục lỗi trình đọc màn hình hoặc điều hướng bằng bàn phím 3) Triển khai đúng các mẫu ARIA 4) Đánh giá độ tương phản màu sắc và khả năng tiếp cận thị giác 5) Tạo biểu mẫu hoặc thành phần tương tác dễ tiếp cận
---

# Quy Trình Kiểm Thử Khả Năng Tiếp Cận (Accessibility Testing Workflow)

## Cấu Hình (Configuration)

- **Cấp độ WCAG (WCAG Level)**: AA
- **Thành phần Đang Kiểm thử (Component Under Test)**: Page
- **Tiêu chuẩn Tuân thủ (Compliance Standard)**: WCAG 2.1
- **Điểm Lighthouse Tối thiểu (Minimum Lighthouse Score)**: 90
- **Trình Đọc Màn Hình Chính (Primary Screen Reader)**: NVDA
- **Framework Kiểm thử (Test Framework)**: jest-axe

## Cây Quyết Định Kiểm Toán (Audit Decision Tree)

```
Nhận được yêu cầu kiểm tra khả năng tiếp cận (Accessibility)
|
+-- Thành phần/trang mới?
|   +-- Chạy quét tự động trước tiên (axe-core, Lighthouse)
|   +-- Kiểm thử điều hướng bằng bàn phím
|   +-- Kiểm tra thông báo phát ra trên trình đọc màn hình
|   +-- Xác minh độ tương phản màu sắc
|
+-- Sửa lỗi vi phạm hiện có?
|   +-- Xác định tiêu chí thành công WCAG tương ứng
|   +-- Kiểm tra xem HTML ngữ nghĩa (semantic HTML) có giải quyết được không
|   +-- Chỉ áp dụng ARIA khi HTML thuần túy không đáp ứng đủ
|   +-- Xác minh bản sửa lỗi bằng công nghệ hỗ trợ (assistive technology)
|
+-- Kiểm toán tuân thủ tổng thể (Compliance audit)?
    +-- Quét tự động (phát hiện được ~30% số lỗi)
    +-- Kiểm thử thủ công theo danh sách kiểm tra (checklist)
    +-- Ghi nhận các vi phạm theo mức độ nghiêm trọng
    +-- Xây dựng lộ trình khắc phục (remediation roadmap)
```

## Tham Khảo Nhanh Chuẩn WCAG

### Phân Loại Mức Độ Nghiêm Trọng (Severity Classification)

| Mức độ (Severity) | Tác động (Impact) | Ví dụ (Examples) | Thời hạn khắc phục (Fix Timeline) |
|----------|--------|----------|--------------|
| Nghiêm trọng (Critical) | Chặn hoàn toàn khả năng truy cập | Không thể focus bằng bàn phím, nút bấm rỗng không nhãn, thiếu thuộc tính alt trên hình ảnh chức năng | Ngay lập tức (Immediate) |
| Nặng (Serious) | Gây rào cản lớn | Độ tương phản kém, thiếu nhãn biểu mẫu (form labels), không có liên kết bỏ qua điều hướng (skip links) | Ngay trong sprint hiện tại |
| Trung bình (Moderate) | Gây khó khăn nhưng vẫn dùng được | Điều hướng thiếu nhất quán, thông báo lỗi không rõ ràng | Bản phát hành tiếp theo |
| Nhẹ (Minor) | Gây bất tiện nhỏ | Văn bản alt bị dư thừa lặp lại, lỗi nhỏ về thứ tự thẻ tiêu đề (heading order) | Đưa vào danh sách chờ (Backlog) |

### Các Lỗi Vi Phạm Phổ Biến và Cách Khắc Phục

**Thiếu tên định danh hỗ trợ tiếp cận (Missing accessible name)**
```html
<!-- Violation -->
<button><svg>...</svg></button>

<!-- Fix: aria-label -->
<button aria-label="Close dialog"><svg>...</svg></button>

<!-- Fix: visually hidden text -->
<button><span class="sr-only">Close dialog</span><svg>...</svg></button>
```

**Liên kết nhãn biểu mẫu (Form label association)**
```html
<!-- Violation -->
<label>Email</label>
<input type="email">

<!-- Fix: explicit association -->
<label for="email">Email</label>
<input type="email" id="email">

<!-- Fix: implicit association -->
<label>Email <input type="email"></label>
```

**Lỗi độ tương phản màu sắc (Color contrast failure)**
```
Tỷ lệ tương phản tối thiểu (WCAG AA):
- Văn bản thường (<18px hoặc <14px in đậm): 4.5:1
- Văn bản cỡ lớn (>=18px hoặc >=14px in đậm): 3:1
- Các thành phần giao diện UI và đồ họa: 3:1

Công cụ kiểm tra: WebAIM Contrast Checker, công cụ DevTools của trình duyệt
```

**Khả năng nhìn rõ trạng thái tiêu điểm (Focus visibility)**
```css
/* Never do this without alternative */
:focus { outline: none; }

/* Proper custom focus */
:focus-visible {
  outline: 2px solid #005fcc;
  outline-offset: 2px;
}
```

## Khung Quyết Định Sử Dụng ARIA (ARIA Decision Framework)

```
Cần truyền tải thông tin tới công nghệ hỗ trợ (assistive technology)?
|
+-- HTML ngữ nghĩa (semantic HTML) có làm được không?
|   +-- CÓ: Sử dụng thẻ HTML chuẩn (<button>, <nav>, <main>, <article>)
|   +-- KHÔNG: Tiếp tục chuyển sang dùng ARIA
|
+-- Cần sử dụng loại thuộc tính ARIA nào?
    +-- Vai trò (Role): Phần tử này LÀ gì? (role="dialog", role="tab")
    +-- Trạng thái (State): Đang ở tình trạng nào? (aria-expanded, aria-checked)
    +-- Thuộc tính (Property): Có mối quan hệ gì? (aria-labelledby, aria-describedby)
    +-- Vùng cập nhật trực tiếp (Live region): Nội dung thay đổi động? (aria-live="polite")
```

### Các Mẫu ARIA Cho Các Thành Phần Tương Tác Phổ Biến

**Khối đóng/mở nội dung (Disclosure - show/hide)**
```html
<button aria-expanded="false" aria-controls="content-1">
  Show details
</button>
<div id="content-1" hidden>
  Content here
</div>
```

**Giao diện chuyển thẻ (Tab interface)**
```html
<div role="tablist" aria-label="Settings">
  <button role="tab" aria-selected="true" aria-controls="panel-1" id="tab-1">
    General
  </button>
  <button role="tab" aria-selected="false" aria-controls="panel-2" id="tab-2" tabindex="-1">
    Privacy
  </button>
</div>
<div role="tabpanel" id="panel-1" aria-labelledby="tab-1">...</div>
<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>...</div>
```

**Hộp thoại Modal (Modal dialog)**
```html
<div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
  <h2 id="dialog-title">Confirm action</h2>
  <p>Are you sure you want to proceed?</p>
  <button>Cancel</button>
  <button>Confirm</button>
</div>
```

## Danh Sách Kiểm Tra Điều Hướng Bằng Bàn Phím

```
[ ] Tất cả các phần tử tương tác đều có thể di chuyển tiêu điểm (focus) tới bằng phím Tab
[ ] Thứ tự di chuyển tiêu điểm (focus order) khớp với thứ tự thị giác/logic
[ ] Trạng thái tiêu điểm (focus) luôn hiển thị rõ ràng bằng mắt thường trên mọi phần tử
[ ] Không có bẫy bàn phím (luôn có thể nhấn Tab để thoát ra ngoài)
[ ] Liên kết bỏ qua tới nội dung chính (Skip link) là phần tử nhận focus đầu tiên trên trang
[ ] Phím Escape đóng được các hộp thoại modal/danh sách thả xuống (dropdowns)
[ ] Các phím mũi tên điều hướng mượt mà bên trong các tiện ích (tabs, menus, grids)
[ ] Phím Enter/Space kích hoạt được các nút bấm và liên kết
[ ] Các phím tắt tùy chỉnh đều có tài liệu hướng dẫn và cho phép cấu hình lại
```

### Các Mẫu Quản Lý Tiêu Điểm (Focus Management Patterns)

**Giữ tiêu điểm bên trong hộp thoại Modal (Modal focus trap)**
```javascript
// On modal open:
// 1. Save previously focused element
// 2. Move focus to first focusable in modal
// 3. Trap Tab within modal boundaries

// On modal close:
// 1. Return focus to saved element
```

**Nội dung cập nhật động (Dynamic content)**
```javascript
// After adding content:
// - Announce via aria-live region, OR
// - Move focus to new content heading

// After removing content:
// - Move focus to logical next element
// - Never leave focus on removed element
```

## Kiểm Thử Với Trình Đọc Màn Hình (Screen Reader Testing)

### Xác Minh Nội Dung Đọc Thông Báo

| Phần tử (Element) | Nội dung Cần Đọc Lên (Should Announce) |
|---------|-----------------|
| Nút bấm (Button) | Vai trò + tên + trạng thái ("Submit button" / "Nút Gửi") |
| Liên kết (Link) | Tên + "link" ("Home page link" / "Liên kết Trang chủ") |
| Hình ảnh (Image) | Văn bản thay thế (Alt text) HOẶC coi là ảnh trang trí (bỏ qua không đọc) |
| Tiêu đề (Heading) | Cấp độ tiêu đề + nội dung chữ ("Heading level 2, About us") |
| Trường biểu mẫu (Form field) | Nhãn + loại trường + trạng thái + hướng dẫn nhập liệu |
| Thông báo lỗi (Error) | Nội dung lỗi + gắn kết rõ với trường bị lỗi |

### Các Phím Lệnh Kiểm Thử (Tham Khảo Nhanh)

**VoiceOver (macOS)**
- VO = Ctrl + Option
- VO + A: Đọc toàn bộ từ vị trí hiện tại
- VO + Mũi tên Phải/Trái: Di chuyển qua các phần tử
- VO + Cmd + H: Chuyển tới tiêu đề (heading) tiếp theo
- VO + Cmd + J: Chuyển tới phần tử điều khiển biểu mẫu tiếp theo

**NVDA (Windows)**
- NVDA + Mũi tên Xuống: Đọc toàn bộ
- Tab: Chuyển tới phần tử nhận focus tiếp theo
- H: Chuyển tới tiêu đề (heading) tiếp theo
- F: Chuyển tới trường biểu mẫu tiếp theo
- B: Chuyển tới nút bấm tiếp theo

## Tích Hợp Kiểm Thử Tự Động

### Sử dụng axe-core trong bài kiểm thử
```javascript
// jest-axe
import { axe, toHaveNoViolations } from 'jest-axe';
expect.extend(toHaveNoViolations);

test('component is accessible', async () => {
  const { container } = render(<MyComponent />);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});
```

### Ngưỡng điểm Lighthouse CI
```javascript
// lighthouserc.js
module.exports = {
  assertions: {
    'categories:accessibility': ['error', { minScore: 90 / 100 }],
  },
};
```

## Ma Trận Ưu Tiên Khắc Phục Lỗi (Remediation Priority Matrix)

```
Mức độ Tác động so với Công sức Bỏ ra:
                      Công sức Thấp       Công sức Cao
Tác động Cao    |   LÀM NGAY ĐẦU TIÊN |   LÊN KẾ HOẠCH TIẾP |
                |   văn bản alt       |   thiết kế lại UI   |
                |   nhãn biểu mẫu     |   làm lại thanh nav |
----------------|---------------------|---------------------|
Tác động Thấp   |   THẮNG NHANH       |   ĐƯA VÀO BACKLOG   |
                |   chỉnh tương phản  |   cải tiến phụ      |
                |   tinh chỉnh nhỏ    |   có thì tốt        |
```

## Danh Sách Kiểm Tra Xác Minh Cuối Cùng

Trước khi đánh dấu hoàn thành công việc đảm bảo khả năng tiếp cận:

```
Kiểm thử Tự động:
[ ] axe-core báo cáo không còn bất kỳ vi phạm nào (zero violations)
[ ] Điểm khả năng tiếp cận trên Lighthouse >= 90
[ ] Trình kiểm tra HTML hợp lệ vượt qua hoàn toàn (ảnh hưởng trực tiếp tới cách công nghệ hỗ trợ phân tích cú pháp)

Kiểm thử Bàn phím:
[ ] Hoàn thành trọn vẹn mọi tác vụ mà không cần dùng chuột
[ ] Viền tiêu điểm (focus) luôn nhìn thấy rõ ở mọi thời điểm
[ ] Thứ tự nhấn phím Tab hợp lý, mạch lạc
[ ] Không có bẫy bàn phím

Kiểm thử Trình đọc Màn hình:
[ ] Đã kiểm thử thực tế với ít nhất một trình đọc màn hình (NVDA)
[ ] Mọi nội dung đều được đọc thông báo chính xác
[ ] Các phần tử tương tác đều có đầy đủ vai trò (roles) và trạng thái (states)
[ ] Các cập nhật nội dung động đều được thông báo kịp thời

Kiểm thử Thị giác:
[ ] Tỷ lệ tương phản màu sắc đã được xác minh (tối thiểu 4.5:1)
[ ] Giao diện vẫn hoạt động tốt không vỡ khung ở mức phóng đại 200% zoom
[ ] Không có thông tin nào chỉ được truyền tải độc nhất bằng màu sắc
[ ] Tôn trọng thiết lập giảm chuyển động (prefers-reduced-motion) của người dùng
```

---
name: agent-organization-expert
description: Kỹ năng điều phối đa tác tử (multi-agent orchestration) phục vụ việc xây dựng đội ngũ, phân rã tác vụ, tối ưu hóa quy trình làm việc và thiết lập chiến lược phối hợp nhằm đạt hiệu suất nhóm và mức sử dụng tài nguyên tối ưu.
---

# Tổ Chức Tác Tử (Agent Organization)

Tập hợp và điều phối các đội ngũ đa tác tử thông qua việc phân tích tác vụ có hệ thống, ánh xạ năng lực và thiết kế luồng công việc.

## Cấu Hình (Configuration)

- **Số lượng Tác tử (Agent Count)**: 3
- **Loại Tác vụ (Task Type)**: general
- **Mẫu Điều phối (Orchestration Pattern)**: parallel
- **Mức Đồng thời Tối đa (Max Concurrency)**: 5
- **Thời gian chờ tối đa (Timeout - giây)**: 300
- **Số lần thử lại (Retry Count)**: 3

## Quy Trình Cốt Lõi

1. **Phân tích Yêu cầu**: Hiểu rõ phạm vi tác vụ, các ràng buộc và tiêu chí đánh giá thành công
2. **Ánh xạ Năng lực**: Ghép nối các tác tử hiện có với các kỹ năng cần thiết
3. **Thiết kế Quy trình (Workflow)**: Tạo kế hoạch thực thi kèm các mối phụ thuộc và điểm kiểm tra (checkpoints)
4. **Điều phối Thực thi**: Phối hợp 3 tác tử và giám sát tiến độ thực hiện
5. **Tối ưu hóa Liên tục**: Thích ứng linh hoạt dựa trên phản hồi về hiệu suất hoạt động

## Phân Rã Tác Vụ (Task Decomposition)

### Phân Tích Yêu Cầu
- Chia nhỏ các tác vụ phức tạp thành những tác vụ con (subtasks) rời rạc, độc lập
- Xác định yêu cầu đầu vào/đầu ra cho từng tác vụ con
- Ước tính độ phức tạp và nhu cầu tài nguyên cho từng thành phần
- Định nghĩa tiêu chí hoàn thành rõ ràng cho từng đơn vị công việc

### Ánh Xạ Phụ Thuộc (Dependency Mapping)
- Ghi nhận các ràng buộc về thứ tự thực thi tác vụ
- Xác định các phụ thuộc dữ liệu giữa các tác vụ con
- Lập bản đồ các yêu cầu chia sẻ tài nguyên chung
- Phát hiện sớm các điểm nghẽn (bottlenecks) và xung đột tiềm ẩn

### Lập Kế Hoạch Tiến Độ (Timeline Planning)
- Sắp xếp trình tự các tác vụ tôn trọng mối quan hệ phụ thuộc
- Xác định các cơ hội chạy song song (tối đa 5 tác vụ đồng thời)
- Phân bổ thời gian dự phòng (buffer time) cho các thành phần có rủi ro cao
- Xác định các điểm kiểm tra (checkpoints) để xác thực tiến độ

## Lựa Chọn Tác Tử (Agent Selection)

### Đối Chiếu Năng Lực (Capability Matching)
Lựa chọn tác tử dựa trên:
- Kỹ năng yêu cầu so với chuyên môn sâu của từng tác tử
- Hiệu suất trong quá khứ trên các tác vụ tương tự
- Tình trạng sẵn sàng hiện tại và khả năng chịu tải công việc
- Hiệu quả chi phí tương ứng với độ phức tạp của tác vụ

### Thứ Tự Ưu Tiên Của Tiêu Chí Lựa Chọn
1. **Độ phù hợp năng lực**: Tác tử bắt buộc phải sở hữu các kỹ năng cần thiết
2. **Thành tích thực tế**: Ưu tiên các tác tử đã được chứng minh tỷ lệ thành công cao
3. **Tính sẵn sàng**: Có đủ năng lực trống để hoàn thành đúng hạn
4. **Chi phí**: Tối ưu hóa việc sử dụng tài nguyên trong phạm vi giới hạn cho phép

### Kế Hoạch Dự Phòng (Backup Planning)
- Xác định sẵn các tác tử thay thế cho những vai trò trọng yếu
- Định nghĩa điều kiện kích hoạt chuyển đổi dự phòng (failover triggers) và quy trình bàn giao (handoff)
- Duy trì cơ chế dự phòng cho các tác vụ có nguy cơ là điểm lỗi đơn lẻ (single-point-of-failure)

## Xây Dựng Đội Ngũ (Team Assembly)

### Nguyên Tắc Cơ Cấu Đội Ngũ
- Đảm bảo độ bao phủ kỹ năng đầy đủ cho tất cả các tác vụ con
- Cân bằng khối lượng công việc giữa 3 thành viên trong nhóm
- Giảm thiểu chi phí giao tiếp trung gian (communication overhead)
- Đưa vào cơ chế dự phòng cho các chức năng then chốt

### Phân Công Vai Trò (Role Assignment)
- Giao các tác vụ con cho từng tác tử dựa trên thế mạnh sở trường
- Xác định rõ quyền sở hữu công việc và trách nhiệm giải trình
- Thiết lập các kênh giao tiếp giữa những vai trò phụ thuộc lẫn nhau
- Ghi rõ lộ trình chuyển cấp xử lý (escalation paths) khi gặp vướng mắc (blockers)

### Định Cỡ Quy Mô Đội Ngũ (Team Sizing)
- Đội ngũ quy mô nhỏ hơn cho các tác vụ có mức độ gắn kết phụ thuộc chặt chẽ (tightly coupled)
- Đội ngũ quy mô lớn hơn cho các khối lượng công việc có khả năng chạy song song cao
- Cân nhắc chi phí điều phối phát sinh khi quyết định số lượng thành viên
- Co giãn quy mô linh hoạt dựa trên tiến độ thực tế

## Các Mẫu Điều Phối (Orchestration Patterns)

### Thực Thi Tuần Tự (Sequential Execution)
Sử dụng khi các tác vụ có yêu cầu nghiêm ngặt về thứ tự trước sau:
- Tác vụ B đòi hỏi phải có đầu ra từ Tác vụ A
- Trạng thái hệ thống phải luôn nhất quán giữa các bước
- Việc xử lý lỗi đòi hỏi phải quay lui (rollback) theo đúng trình tự ngược lại

### Xử Lý Song Song (Parallel Processing)
Sử dụng khi các tác vụ độc lập với nhau (parallel):
- Không có sự phụ thuộc dữ liệu giữa các tác vụ
- Yêu cầu tài nguyên tách biệt nhau
- Kết quả có thể được gom tổng hợp lại sau khi tất cả hoàn tất
- Tối đa 5 thao tác chạy đồng thời

### Mẫu Đường Ống (Pipeline Pattern)
Sử dụng cho xử lý luồng dữ liệu (streaming) hoặc xử lý liên tục:
- Mỗi chặng (stage) xử lý và chuyển tiếp ngay kết quả sang chặng kế tiếp
- Cho phép thực thi đồng thời nhiều chặng khác nhau trên các phần dữ liệu khác nhau
- Giảm độ trễ tổng thể cho các luồng công việc nhiều bước

### Phân Quyền Phân Cấp (Hierarchical Delegation)
Sử dụng cho các tác vụ phức tạp đòi hỏi điều phối cấp dưới (sub-orchestration):
- Tác tử trưởng (Lead agent) điều phối các nhóm nhỏ cấp dưới
- Mỗi nhóm nhỏ phụ trách một miền chuyên môn riêng
- Kết quả được tổng hợp dần từ dưới lên theo cây phân cấp

### Map-Reduce
Sử dụng cho xử lý dữ liệu quy mô lớn:
- Pha ánh xạ (Map phase) phân tán công việc cho các tác tử
- Mỗi tác tử xử lý một phân vùng dữ liệu riêng
- Pha rút gọn (Reduce phase) kết hợp các kết quả lại với nhau

## Thiết Kế Luồng Công Việc (Workflow Design)

### Cấu Trúc Quy Trình
1. **Điểm bắt đầu (Entry point)**: Xác thực dữ liệu đầu vào và khởi tạo trạng thái
2. **Các giai đoạn thực thi**: Các nhóm tác vụ được sắp xếp theo trình tự
3. **Điểm kiểm tra (Checkpoints)**: Điểm lưu trữ bền vững trạng thái và kiểm tra tính hợp lệ
4. **Điểm kết thúc (Exit point)**: Tổng hợp kết quả cuối cùng và dọn dẹp tài nguyên

### Luồng Điều Khiển (Control Flow)
- Định nghĩa các điều kiện rẽ nhánh cho các luồng xử lý thay thế
- Chỉ định chính sách thử lại (retry policies) đối với các lỗi tạm thời (tối đa 3 lần thử lại)
- Thiết lập ngưỡng thời gian chờ tối đa cho từng giai đoạn (mặc định 300 giây)
- Lên kế hoạch suy giảm chức năng một cách êm thấm (graceful degradation) khi xảy ra lỗi cục bộ

### Luồng Dữ Liệu (Data Flow)
- Ghi rõ các bước biến đổi dữ liệu giữa các chặng
- Chỉ định định dạng dữ liệu và quy tắc xác thực tính hợp lệ
- Lên kế hoạch lưu trữ bền vững dữ liệu tại các điểm kiểm tra (checkpoints)
- Xử lý dọn dẹp dữ liệu tạm sau khi hoàn tất

## Chiến Lược Phối Hợp (Coordination Strategies)

### Các Mẫu Giao Tiếp (Communication Patterns)
- **Trực tiếp (Direct)**: Giao tiếp trực tiếp từ tác tử sang tác tử đối với các tác vụ gắn kết chặt
- **Phát quảng bá (Broadcast)**: Một-tới-nhiều dùng để cập nhật trạng thái chung
- **Dựa trên hàng đợi (Queue-based)**: Bất đồng bộ dành cho các tác vụ tách rời nhau (decoupled)
- **Hướng sự kiện (Event-driven)**: Phản ứng tự động khi có sự thay đổi trạng thái

### Đồng Bộ Hóa (Synchronization)
- Xác định các điểm đồng bộ (sync points) cho những tác vụ phụ thuộc nhau
- Triển khai cơ chế chờ đợi có gắn thời gian giới hạn (300 giây)
- Xử lý mượt mà trường hợp các tác vụ hoàn thành không đúng thứ tự dự kiến
- Duy trì trạng thái nhất quán xuyên suốt các tác tử

### Giải Quyết Xung Đột (Conflict Resolution)
- Thiết lập quy tắc ưu tiên khi xảy ra tranh chấp tài nguyên
- Định nghĩa cơ chế phân xử trọng tài cho các xung đột
- Ghi rõ quy trình quay lui (rollback) khi xảy ra khóa chết (deadlocks)
- Ngăn ngừa xung đột từ sớm thông qua việc lập lịch trình cẩn trọng

## Tối Ưu Hóa Hiệu Suất (Performance Optimization)

### Cân Bằng Tải (Load Balancing)
- Phân phối công việc dựa trên năng lực xử lý của từng tác tử
- Giám sát mức độ sử dụng và tự động cân bằng lại tải công việc
- Tránh làm quá tải các tác tử có hiệu suất cao
- Cân nhắc tính cục bộ của tác tử (agent locality) đối với các tác vụ nặng về dữ liệu

### Quản Lý Điểm Nghẽn (Bottleneck Management)
- Phát hiện các chặng xử lý chậm thông qua hệ thống giám sát
- Bổ sung thêm năng lực xử lý cho các tài nguyên đang bị thắt cổ chai
- Tái cấu trúc luồng công việc để giảm bớt sự phụ thuộc nối tiếp
- Lưu vào bộ nhớ đệm (cache) các kết quả trung gian ở những nơi mang lại lợi ích

### Hiệu Quả Sử Dụng Tài Nguyên
- Gom chung các tài nguyên chia sẻ (pool shared resources) giữa các tác tử
- Giải phóng tài nguyên ngay lập tức sau khi sử dụng xong
- Gom nhóm (batch) các thao tác tương tự nhau để giảm chi phí phụ trội
- Giám sát và cảnh báo khi phát hiện lãng phí tài nguyên

## Giám Sát và Thích Ứng (Monitoring and Adaptation)

### Theo Dõi Tiến Độ
- Giám sát trạng thái hoàn thành của từng tác vụ
- Theo dõi thời gian thực tế tiêu tốn so với ước tính ban đầu
- Sớm nhận diện các tác vụ có nguy cơ bị trễ hạn
- Báo cáo tiến độ tổng hợp cho các bên liên quan

### Chỉ Số Đo Lường Hiệu Suất (Performance Metrics)
- Tỷ lệ hoàn thành tác vụ và độ trễ xử lý
- Mức độ sử dụng tác tử và thông lượng đầu ra (throughput)
- Tỷ lệ phát sinh lỗi và thời gian phục hồi
- Mức tiêu thụ tài nguyên và chi phí vận hành

### Điều Chỉnh Động (Dynamic Adjustment)
- Phân bổ lại các tác tử dựa trên tiến độ thực tế
- Điều chỉnh mức độ ưu tiên dựa trên các điểm nghẽn phát sinh
- Mở rộng hoặc thu hẹp quy mô nhóm dựa trên khối lượng công việc
- Tinh chỉnh lại luồng công việc dựa trên những bài học rút ra

## Xử Lý Lỗi (Error Handling)

### Phát Hiện Sự Cố
- Giám sát lỗi thực thi tác vụ và tình trạng quá thời gian chờ (ngưỡng 300 giây)
- Phát hiện kịp thời khi một tác tử mất kết nối hoặc không phản hồi
- Nhận diện các mẫu lỗi dây chuyền (cascade failure patterns)
- Phát cảnh báo khi có hành vi bất thường

### Quy Trình Phục Hồi (Recovery Procedures)
- Thử lại các lỗi tạm thời với thời gian chờ tăng dần (backoff — tối đa 3 lần thử)
- Chuyển đổi dự phòng (failover) sang các tác tử dự bị khi cần thiết
- Quay lui (rollback) về điểm kiểm tra (checkpoint) gần nhất khi gặp lỗi nghiêm trọng
- Chuyển cấp báo cáo (escalate) đối với các sự cố không thể tự phục hồi

### Phòng Ngừa Sự Cố
- Kiểm tra tính hợp lệ của dữ liệu đầu vào trước khi thực thi
- Kiểm tra tính sẵn sàng của tác tử trước khi giao việc
- Thiết kế hệ thống có khả năng suy giảm êm thấm (graceful degradation)
- Xây dựng cơ chế dự phòng trên các luồng xử lý trọng yếu

## Đảm Bảo Chất Lượng (Quality Assurance)

### Các Cổng Kiểm Tra Xác Thực (Validation Gates)
- Xác minh kết quả đầu ra tại mỗi điểm kiểm tra (checkpoint)
- Kiểm tra đối chiếu chéo kết quả từ các tác vụ chạy song song
- Xác thực kết quả tổng hợp cuối cùng
- Xác nhận các tiêu chí thành công đều đã đạt được

### Tiêu Chuẩn Hiệu Suất
- Mục tiêu độ chính xác khi chọn tác tử: >95%
- Mục tiêu tỷ lệ hoàn thành tác vụ: >99%
- Mục tiêu thời gian phản hồi: <5 giây
- Mức sử dụng tài nguyên: khoảng tối ưu 60-80%

## Thực Hành Tốt Nhất (Best Practices)

### Lập Kế Hoạch
- Đầu tư thời gian phân tích kỹ lưỡng tác vụ ngay từ đầu
- Ghi chép rõ các giả định và ràng buộc
- Lên kế hoạch ứng phó trước cho các kịch bản lỗi
- Định nghĩa rõ các chỉ số đo lường thành công

### Thực Thi
- Bắt đầu với quy mô nhóm khả dụng tối thiểu (3 tác tử)
- Mở rộng quy mô dựa trên nhu cầu quan sát được thực tế
- Duy trì các kênh giao tiếp thông suốt, rõ ràng
- Theo dõi sát tiến độ so với các cột mốc (milestones)

### Học Hỏi Cải Tiến
- Thu thập dữ liệu hiệu suất để phục vụ phân tích
- Nhận diện các quy luật chung trong cả thành công lẫn thất bại
- Tinh chỉnh chiến lược lựa chọn và phối hợp tác tử
- Chia sẻ bài học kinh nghiệm cho các lần điều phối trong tương lai