feat: make toolkit public and add remote 1-line installer

- Add remote web installer (install.sh) supporting curl | bash without cloning repo - Remove team-specific wrappers and symlinks in favor of clean public install.sh - Consolidate all usage and setup documentation directly into README.md - Add open-source MIT License - Streamline end-to-end testing workflow with 4-in-1 autopilot mode Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-09-08 08:57:50 +07:00
parent 6fc49787a9
commit 3e1314a3e1
5 changed files with 529 additions and 644 deletions
@@ -1,149 +1,337 @@
-# 🚀 Laravel Agent Unit Testing Toolkit
+# 🚀 Laravel Unit Testing Toolkit for Claude Code

-Bộ công cụ, cẩm nang quy chuẩn và Claude Code Skills chuyên biệt dành cho việc **tự động phân tích, thiết lập môi trường và sinh Unit Test chuẩn xác cho bất kỳ mã nguồn PHP Laravel nào** (hỗ trợ Laravel 9, 10, 11; PHPUnit 9/10/11 & Pest PHP v2/v3).
+> **Bộ công cụ tự động hóa toàn diện cho việc thiết lập môi trường, sinh Unit Test chuẩn AAA và kiểm thử tự động cho bất kỳ dự án PHP & Laravel nào (từ Laravel 8 đến 13+, PHP 8.0 đến 8.4+).**
+
+Được phát triển dưới dạng mã nguồn mở (Open Source) dành cho mọi lập trình viên, đội ngũ kỹ thuật và cộng đồng phát triển phần mềm.

 ---

-## 🌟 Tính Năng Nổi Bật
+## 📑 MỤC LỤC
+1. [Điểm Nổi Bật & Tính Năng Cốt Lõi](#1-điểm-nổi-bật--tính-năng-cốt-lõi)
+2. [Cấu Trúc Thư Mục Repository](#2-cấu-trúc-thư-mục-repository)
+3. [Hướng Dẫn Cài Đặt Lần Đầu](#3-hướng-dẫn-cài-đặt-lần-đầu)
+4. [Khởi Tạo Cho Một Dự Án Laravel Bất Kỳ](#4-khởi-tạo-cho-một-dự-án-laravel-bất-kỳ)
+5. [Quy Trình 5 Bước Sinh & Chạy Unit Test](#5-quy-trình-5-bước-sinh--chạy-unit-test)
+   - [Bước 1: Quét Môi Trường & Cài Packages (`/laravel-test-setup`)](#bước-1-quét-môi-trường--cài-packages-laravel-test-setup)
+   - [Bước 2: Sinh Unit Test Tự Động (`/laravel-unit-test`)](#bước-2-sinh-unit-test-tự-động-laravel-unit-test)
+   - [Bước 3: Chạy Test Thông Minh (`test-runner.sh`)](#bước-3-chạy-test-thông-minh-test-runnersh)
+   - [Bước 4: Thẩm Định & Chấm Điểm Test (`/laravel-test-review`)](#bước-4-thẩm-định--chấm-điểm-test-laravel-test-review)
+   - [Bước 5: Sinh Mã Giả Lập Nhanh (`/laravel-mock-helper`)](#bước-5-sinh-mã-giả-lập-nhanh-laravel-mock-helper)
+6. [Cách Cập Nhật Bộ Công Cụ Khi Có Nâng Cấp](#6-cách-cập-nhật-bộ-công-cụ-khi-có-nâng-cấp)
+7. [Giải Đáp Thắc Mắc & Xử Lý Lỗi (FAQ & Troubleshooting)](#7-giải-đáp-thắc-mắc--xử-lý-lỗi-faq--troubleshooting)
+8. [Bảng Tra Cứu Toàn Bộ Lệnh (Full Cheat Sheet)](#8-bảng-tra-cứu-toàn-bộ-lệnh-full-cheat-sheet)
+9. [Ma Trận Tương Thích & Bản Quyền](#9-ma-trận-tương-thích--bản-quyền)

-1. **Chuẩn Hóa Môi Trường (Step 0)**:
-   - Tự động phát hiện cấu hình Docker (Sail, Docker Compose) hoặc PHP CLI cục bộ.
-   - Thiết lập SQLite In-Memory (`:memory:`) siêu tốc, bảo vệ tuyệt đối database dev.
-   - Script chạy test thông minh `test-runner.sh` tự nhận diện môi trường container.
+---
+
+## 1. Điểm Nổi Bật & Tính Năng Cốt Lõi
+
+1. **Chuẩn Hóa Môi Trường Tự Động (Bước 0)**:
+   - Tự động nhận diện runtime: **Laravel Sail**, **Docker Compose** (service `app`/`php`), hoặc **PHP CLI cục bộ**.
+   - Bảo vệ an toàn database: thiết lập SQLite In-Memory (`:memory:`), tuyệt đối không chạm hay làm mất dữ liệu dev/local.
+   - Tự động cài đặt các package còn thiếu (`mockery`, `faker`, `paratest`) thẳng vào đúng container đang chạy.
 2. **Triết Lý Kiểm Thử Đỉnh Cao (AAA & Isolation)**:
-   - Cô lập hoàn toàn logic đơn vị, mock đúng nơi, fake đúng chỗ.
-   - Tuyệt đối không over-mock DTO, Value Object hay Mock chuỗi Eloquent Builder.
-3. **Cẩm Nang Chi Tiết Cho 13 Tầng Kiến Trúc Laravel**:
-   - Services, Actions, Controllers, FormRequests, Custom Rules, Repositories, Query Builders, Models, Jobs, Events, Listeners, Middlewares, Policies, Notifications, Mails, Commands, View Components, Observers, Exceptions.
-4. **Hệ Thống 4 Skills Tự Động Hóa Cho Claude Code**:
-   - `/laravel-test-setup`: Quét môi trường, cấu hình và chạy Smoke Test.
-   - `/laravel-unit-test`: Đọc class nguồn -> Sinh file test hoàn chỉnh.
-   - `/laravel-test-review`: Thẩm định, chấm điểm và chỉ ra lỗi anti-patterns của file test.
-   - `/laravel-mock-helper`: Sinh code Mockery / Fakes nhanh cho Interface/Class.
+   - Đảm bảo tính cô lập tuyệt đối (Zero Leakage): mock toàn bộ external services, APIs, queues, mails.
+   - Không over-mocking: giữ nguyên thực thể DTO, Value Object, Collection thật.
+   - Chặn đứng lỗi anti-pattern mock chuỗi Eloquent Query Builder dễ vỡ.
+3. **Bao Phủ Trọn Vẹn 13 Tầng Kiến Trúc Laravel**:
+   - Services, Actions, Controllers, FormRequests, Custom Rules, Repositories, Query Builders, Models, Jobs, Events, Listeners, Middlewares, Policies, Notifications, Mailables, Artisan Commands, View Components, Observers, Exceptions.
+4. **Chế Độ Autopilot Khép Kín (`/laravel-unit-test --all --run`)**:
+   - Chỉ với 1 lệnh duy nhất: tự động lập manifest quét toàn bộ dự án, viết test tuần tự không sót file, **viết đến đâu tự chạy test đến đó**, và **tự động sửa lỗi (Auto-Healing)** cho đến khi PASS 100%.
+5. **Sẵn Sàng Cho Tương Lai & Architecture Testing**:
+   - Hỗ trợ đầy đủ tính năng mới nhất của **PHP 8.4+** (Property Hooks, Asymmetric Visibility).
+   - Tích hợp bộ kiểm thử kiến trúc toàn dự án **Architecture Test** bằng Pest v3 / PHPUnit (`arch()`).
+   - Cung cấp sẵn file cấu hình CI/CD Quality Gate (GitHub Actions, GitLab CI) chặn merge PR nếu code coverage < 80%.

 ---

-## 📁 Cấu Trúc Dự Án
+## 2. Cấu Trúc Thư Mục Repository

 ```text
 agent-unit-testing/
+├── install.sh                               # Script cài đặt chính (hỗ trợ Toàn cục & Theo dự án)
 ├── .claude/
-│   └── skills/                              # Bộ 4 Skills cho Claude Code
-│       ├── laravel-test-setup/              # Khởi tạo & kiểm tra môi trường test
-│       ├── laravel-unit-test/               # Sinh mã Unit Test tự động
-│       ├── laravel-test-review/             # Review & chấm điểm file test
-│       └── laravel-mock-helper/             # Hỗ trợ sinh mã Mocking
+│   └── skills/                              # Bộ 4 Skills tích hợp cho Claude Code
+│       ├── laravel-test-setup/              # Kiểm tra môi trường & tự cài đặt dependencies
+│       ├── laravel-unit-test/               # Sinh Unit Test tự động (hỗ trợ Autopilot --all --run)
+│       ├── laravel-test-review/             # Chấm điểm chất lượng test theo thang 100 & bắt lỗi anti-patterns
+│       └── laravel-mock-helper/             # Sinh mã Mockery & Laravel Fakes nhanh
 │
-├── docs/                                    # Cẩm nang kiến thức & quy chuẩn cốt lõi
-│   ├── 00-environment-and-setup.md          # Hướng dẫn setup dependencies, DB in-memory & Docker
-│   ├── 01-overview-and-principles.md        # Triết lý Unit Test: AAA, Isolation, Boundary
-│   ├── 02-test-frameworks.md                # So sánh & Cú pháp PHPUnit 10/11 vs Pest PHP
+├── docs/                                    # 10 Cẩm Nang Kiến Thức & Quy Chuẩn Cốt Lõi
+│   ├── 00-environment-and-setup.md          # Hướng dẫn setup dependencies, SQLite in-memory & Docker
+│   ├── 01-overview-and-principles.md        # Triết lý Unit Test: AAA, cách ly, ranh giới Feature test
+│   ├── 02-test-frameworks.md                # So sánh & cú pháp PHPUnit 10/11 vs Pest PHP v2/v3
 │   ├── 03-mocking-strategies.md             # Toàn tập Mockery vs Laravel Fakes vs Static Facades
 │   ├── 04-naming-and-structure.md           # Quy chuẩn đặt tên file, namespace, test method
 │   ├── 05-anti-patterns.md                  # 12 lỗi cấm kỵ khi viết Unit Test Laravel
 │   ├── 06-future-php84-laravel-latest.md    # Hướng dẫn chuyên sâu PHP 8.4+ & Laravel 12/13
-│   ├── 07-troubleshooting-and-debugging.md  # Cẩm nang sửa 10 lỗi thường gặp nhất khi test
+│   ├── 07-troubleshooting-and-debugging.md  # Cẩm nang sửa 10 lỗi thường gặp nhất khi chạy test
 │   ├── 08-test-data-factories-and-builders.md# Quản lý fixture: Model::make(), States & DTO Builders
 │   ├── 09-advanced-edge-cases.md            # DB::transaction, Traits, File uploads, Serialization
 │   │
-│   └── components/                          # Hướng dẫn test cho 13 loại Laravel Component
+│   └── components/                          # 13 Cẩm Nang Chi Tiết Cho Từng Component Laravel
 │       ├── 01-services-and-actions.md       # Service Layer, Action classes, DTOs
 │       ├── 02-controllers.md                # API & Web Controllers
-│       ├── 03-form-requests-and-rules.md    # FormRequest rules, Custom Validation Rules
+│       ├── 03-form-requests-and-rules.md    # FormRequests & Custom Validation Rules
 │       ├── 04-repositories-and-queries.md   # Repositories & Custom Query Builders
 │       ├── 05-models.md                     # Accessors, Mutators, Custom Casts
-│       ├── 06-jobs-and-queues.md            # Queueable Jobs, handle(), retry logic
-│       ├── 07-events-and-listeners.md       # Event payloads, Listeners handling
+│       ├── 06-jobs-and-queues.md            # Queueable Jobs, retry logic, failed()
+│       ├── 07-events-and-listeners.md       # Event payloads & Listener handlers
 │       ├── 08-middlewares.md                # Request interception, Auth, Role, Tenant
-│       ├── 09-policies-and-gates.md         # Phân quyền Policy methods (can/cannot)
+│       ├── 09-policies-and-gates.md         # Policies authorization logic (can/cannot)
 │       ├── 10-notifications-and-mail.md     # Mailables & Notification channels
-│       ├── 11-artisan-commands.md           # Console input/options, exit code, prompts
+│       ├── 11-artisan-commands.md           # Console arguments, options, exit codes
 │       ├── 12-view-components-and-blade.md  # Blade View Components & directives
 │       └── 13-observers-and-exceptions.md   # Model Observers & Custom Exceptions
 │
-├── templates/                               # Boilerplate mẫu sẵn dùng
-│   ├── configs/                             # File config: phpunit.xml, .env.testing, Pest.php
-│   ├── docker/                              # Script test-runner.sh & docker-compose.test.yml
-│   ├── phpunit/                             # Templates chuẩn PHPUnit 10/11 (Attributes)
-│   └── pest/                                # Templates chuẩn Pest PHP v2/v3
+├── templates/                               # Templates Mẫu Chuẩn
+│   ├── configs/                             # phpunit.xml.dist, .env.testing, Pest.php
+│   ├── docker/                              # Smart test-runner.sh & docker-compose.test.yml
+│   ├── ci/                                  # GitHub Actions & GitLab CI quality gates
+│   ├── phpunit/                             # 8 Component templates + ArchitectureTest
+│   └── pest/                                # 8 Component templates + ArchitectureTest
 │
-└── rules/                                   # Bộ quy tắc & Checklists
-    ├── system-prompt-unit-test.md           # System prompt tối cao cho AI
-    ├── edge-cases-matrix.md                 # Ma trận kịch bản biên (Null, Empty, Boundary, Error)
-    └── verification-checklist.md            # Checklist 10 bước tự kiểm tra trước khi xuất code
+├── rules/                                   # Bộ Quy Tắc & Tiêu Chí Đánh Giá
+│   ├── system-prompt-unit-test.md           # System prompt cốt lõi cho AI
+│   ├── edge-cases-matrix.md                 # Ma trận kịch bản biên (Null, Boundary, Errors)
+│   └── verification-checklist.md            # Checklist 10 bước tự kiểm tra trước khi xuất code
+│
+├── LICENSE                                  # Giấy phép mã nguồn mở MIT
+└── README.md                                # Tài liệu hướng dẫn chính
 ```

 ---

-## ⚡ Cài Đặt Cho Team (1 Dòng Lệnh Duy Nhất)
+## 3. Cài Đặt Trực Tiếp Vào Source Code (Không Cần Clone Repo)

-Mỗi thành viên trong team chỉ cần mở Terminal, dán lệnh sau và bấm Enter:
+Bất kỳ ai muốn sử dụng bộ công cụ này **KHÔNG CẦN phải clone source code công cụ về máy**. 
+
+Chỉ cần mở Terminal, `cd` vào thư mục dự án Laravel của bạn và chạy **đúng 1 dòng lệnh**:
+
+### 🌟 1 Dòng Lệnh Cài Đặt Từ Xa (Remote 1-Line Installer)
 ```bash
-git clone ssh://git@ssh-git.smartgift.io.vn:2222/Smartgift-AI/agent-unit-testing.git ~/.smartgift/agent-unit-testing && ~/.smartgift/agent-unit-testing/sg-install-unit-testing.sh --global
+cd /duong-dan/toi/source-code-laravel-cua-ban
+
+# Chạy lệnh cài đặt từ xa:
+curl -fsSL https://raw.githubusercontent.com/<OWNER>/agent-unit-testing/main/install.sh | bash
+```
+
+*(Đối với thành viên trong nội bộ team Smartgift hoặc khi dùng Git SSH server):*
+```bash
+cd /duong-dan/toi/source-code-laravel-cua-ban
+
+# Cài đặt trực tiếp qua Git mà không cần lưu repo công cụ:
+bash <(git archive --remote=ssh://git@ssh-git.smartgift.io.vn:2222/Smartgift-AI/agent-unit-testing.git main install.sh | tar -xO)
 ```
-*Lệnh trên tự động clone vào `~/.smartgift/` và kích hoạt toàn cục trên máy tính.*

 ---

-## 🛠️ Hướng Dẫn Sử Dụng Nhanh
+### 🎯 Quy Trình Tự Động Diễn Ra Ngầm:
+1. Script sẽ tải các tài nguyên cần thiết từ xa vào thư mục tạm `/tmp/`.
+2. Tự động cấy trực tiếp vào source code của bạn:
+   - Thư mục `.claude/skills/` (với trọn bộ 4 Skills viết test tự động).
+   - Thư mục `.claude/testing-docs/` (cẩm nang quy chuẩn 13 tầng Laravel).
+   - Script chạy test thông minh `./test-runner.sh` (tự bắt Docker/Sail/Local).
+   - Script cài package test `./setup-test-deps.sh`.
+   - Tự động cấu hình SQLite In-Memory `:memory:` an toàn vào `phpunit.xml`.
+   - Tự động tạo GitHub Actions CI `.github/workflows/unit-tests.yml`.
+3. Tự động xóa sạch thư mục tạm, **hoàn toàn không lưu lại rác hay repository công cụ trên máy của bạn**!
+
+---
+
+## 4. Tùy Chọn: Cài Đặt Toàn Cục Cho Toàn Máy Tính (Global Mode)
+
+Nếu bạn là lập trình viên muốn cài 1 lần duy nhất cho toàn bộ máy tính (để mọi source code mở Claude Code lên đều tự có sẵn các lệnh):

-### Bước 1: Khởi Tạo Vào Dự Án Laravel Bất Kỳ
-Mở terminal tại thư mục dự án Laravel của bạn:
 ```bash
-cd /duong-dan/toi/du-an-laravel
-sg-install-unit-testing.sh
+curl -fsSL https://raw.githubusercontent.com/<OWNER>/agent-unit-testing/main/install.sh | bash -s -- --global
 ```

-### Bước 2: Chuẩn Bị Môi Trường
-Mở Claude Code (`claude`) tại thư mục dự án và chạy skill:
+🎯 **Lợi ích:**
+- Tự động cài đặt 4 Skills vào `~/.claude/skills/`.
+- Đăng ký lệnh `sg-test-init` (hoặc `laravel-test-init`) vào Terminal để gõ ở bất kỳ thư mục nào cũng tự tạo `test-runner.sh`.
+
+---
+
+## 5. Quy Trình Trọn Vẹn: Từ Bắt Đầu Đến Hoàn Thành Viết Unit Test
+
+Dưới đây là **kịch bản thực chiến trọn vẹn từ A đến Z** khi bạn áp dụng vào một source code Laravel thực tế:
+
+```text
+┌────────────────┐     ┌────────────────┐     ┌────────────────┐     ┌────────────────┐
+│  1. CÀI ĐẶT    │ ──> │ 2. SETUP ENV   │ ──> │ 3. AUTOPILOT   │ ──> │ 4. NGHIỆM THU  │
+│  curl | bash   │     │ test-setup     │     │ unit-test --all│     │ Coverage > 80% │
+└────────────────┘     └────────────────┘     └────────────────┘     └────────────────┘
+```
+
+---
+
+### 🔹 Giai đoạn 1: Cài đặt công cụ vào Source Code (Chỉ mất 5 giây)
+Mở terminal, `cd` vào thư mục source code Laravel của bạn và chạy 1 dòng lệnh:
 ```bash
+cd /duong-dan/toi/source-code-laravel
+curl -fsSL https://raw.githubusercontent.com/<OWNER>/agent-unit-testing/main/install.sh | bash
+```
+✅ **Kết quả**: Source code đã được tích hợp bộ Skills, cẩm nang rules, script `./test-runner.sh` và cấu hình SQLite `:memory:` an toàn.
+
+---
+
+### 🔹 Giai đoạn 2: Khởi động Claude Code & Chuẩn hóa môi trường
+Mở Claude Code ngay tại thư mục source code:
+```bash
+claude
+```
+Chạy lệnh kiểm tra và tự động cài đặt thư viện kiểm thử còn thiếu:
+```text
 /laravel-test-setup --install
 ```
-Agent sẽ tự động kiểm tra `composer.json`, kiểm tra database test SQLite và tự cài đặt các package còn thiếu.
+✅ **Kết quả**: AI tự động kiểm tra `composer.json`, nếu thiếu `mockery`, `faker`, `paratest` -> AI tự động kích hoạt lệnh cài đặt vào container Docker hoặc môi trường Local của bạn và xác nhận môi trường chuyển sang trạng thái "Xanh" (100% Sẵn sàng).

-### Bước 3: Sinh Unit Test Tự Động & Chạy Test Ngay
-Chỉ định class, thư mục, hoặc phủ toàn bộ dự án:
-```bash
-# 🌟 1 lệnh duy nhất Autopilot: Tự động viết test cả dự án & TỰ CHẠY TEST LUÔN:
+---
+
+### 🔹 Giai đoạn 3: Ra lệnh viết toàn bộ Unit Test & Tự động chạy test luôn
+Chỉ cần gõ **đúng 1 lệnh Autopilot**:
+```text
 /laravel-unit-test --all --run
-
-# Sinh test cho 1 file & tự động chạy test kiểm tra ngay:
-/laravel-unit-test app/Services/PaymentService.php --run
-
-# Cho cả thư mục / module & test luôn:
-/laravel-unit-test app/Services/ --run
-
-# Cho các file vừa sửa trên Git & test luôn (trước khi tạo PR):
-/laravel-unit-test --changed --run
 ```

-### Bước 4: Chạy Kiểm Thử
-Sử dụng script thông minh tự động nhận diện Docker / Sail / Local:
-```bash
-./test-runner.sh --filter=PaymentServiceTest
-```
+**Quá trình AI thực hiện tự động hoàn toàn:**
+1. **Quét & Lập Manifest**: AI quét toàn bộ `app/Services/`, `app/Actions/`, `app/Http/Requests/`, `app/Jobs/`, `app/Policies/`, `app/Rules/`,... và tạo file kiểm soát `tests/.test-manifest.json` (ví dụ: Tổng cộng 36 files).
+2. **Viết test tuần tự**: AI duyệt từng file `[1/36]`, `[2/36]`... sinh mã test chuẩn AAA, đầy đủ kịch bản Happy Path, Edge Cases (0, âm, null, rỗng) và Exception.
+3. **Chạy test & Tự động sửa lỗi (Auto-Healing)**:
+   - Viết xong file nào, AI tự động gọi `./test-runner.sh --filter=<TênTest>` để chạy test file đó ngay.
+   - Nếu test bị ĐỎ (Fail) do thiếu mock hoặc sai tham số -> AI tự động đọc log lỗi, tự sửa code test ngay tại chỗ cho đến khi XANH (Pass 100%).

-### Bước 5: Cập Nhật Bộ Công Cụ Khi Có Phiên Bản Mới
-Thành viên đứng ở bất kỳ đâu chỉ cần gõ:
+---
+
+### 🔹 Giai đoạn 4: Nghiệm thu kết quả & Kiểm tra Code Coverage
+Sau khi hoàn tất toàn bộ danh sách trong manifest, AI sẽ tự động chạy:
 ```bash
-sg-test-update
+./test-runner.sh --coverage
+```
+Bảng báo cáo nghiệm thu sẽ xuất hiện:
+```markdown
+🎉 HOÀN TẤT VIẾT VÀ TEST TOÀN BỘ DỰ ÁN:
+✓ Tổng số class đã phủ test: 36/36 files (100%)
+✓ Tổng số test cases được sinh: 142 test cases
+✓ Kết quả thực thi: 142 PASSED (0 FAILED)
+✓ Code Coverage: 86.4% (Đạt tiêu chuẩn Quality Gate > 80%)
 ```

 ---

-## 🎯 Ma Trận Tương Thích (Compatibility Matrix)
+### 🔹 Giai đoạn 5 (Tùy chọn): Các chế độ chạy linh hoạt khác
+Nếu không muốn chạy cả dự án, bạn có thể chọn các chế độ linh hoạt sau:
+- **Chỉ viết cho 1 class & test luôn**:
+  ```text
+  /laravel-unit-test app/Services/PaymentService.php --run
+  ```
+- **Chỉ viết cho cả 1 thư mục & test luôn**:
+  ```text
+  /laravel-unit-test app/Services/ --run
+  ```
+- **Chỉ viết cho các file vừa sửa đổi trên Git trước khi tạo PR**:
+  ```text
+  /laravel-unit-test --changed --run
+  ```
+- **Thẩm định & Chấm điểm 1 file test có sẵn (thang 100)**:
+  ```text
+  /laravel-test-review tests/Unit/Services/PaymentServiceTest.php
+  ```
+- **Sinh nhanh khối mã Mockery cho một Interface**:
+  ```text
+  /laravel-mock-helper App\Contracts\PaymentGatewayInterface
+  ```

-| Thành phần | Phiên bản hỗ trợ & Tương thích tương lai |
+---
+
+## 6. Cách Cập Nhật Bộ Công Cụ Khi Có Nâng Cấp
+
+Khi repository công cụ trên Git có tài liệu mới hoặc nâng cấp rules:
+
+### 🌟 Cách 1: Cập nhật trực tiếp vào source code hiện tại
+Đứng tại thư mục source code Laravel của bạn và chạy lại dòng lệnh cài đặt:
+```bash
+curl -fsSL https://raw.githubusercontent.com/<OWNER>/agent-unit-testing/main/install.sh | bash
+```
+*(Script sẽ tự động kéo bản mới nhất và ghi đè cập nhật vào `.claude/skills/` và runner của source code).*
+
+---
+
+### ⚡ Cách 2: Nếu bạn đã cài đặt chế độ Toàn Cục (Global)
+Bất kể bạn đang đứng ở thư mục nào trong Terminal, chỉ cần gõ:
+```bash
+laravel-test-update
+```
+*(hoặc alias: `sg-test-update`)*
+Lệnh sẽ tự động kéo bản cập nhật mới nhất từ Git về máy bạn trong 3 giây.
+
+---
+
+## 7. Giải Đáp Thắc Mắc & Xử Lý Lỗi (FAQ & Troubleshooting)
+
+### Q1: Tại sao tôi gõ `./install.sh` thì bị báo `zsh: no such file or directory`?
+👉 **Trả lời**: Ký hiệu `./` nghĩa là tìm file ngay trong thư mục hiện tại. Khi bạn đã `cd` sang một dự án khác, thư mục đó không có file này.
+**Cách sửa**: Bỏ dấu `./` đi, chỉ cần gõ thẳng tên lệnh toàn cục đã được đăng ký:
+```bash
+laravel-test-init
+# Hoặc:
+laravel-unit-test-setup
+```
+
+### Q2: Tôi cài đặt vào một thư mục trống nhưng bị báo chưa có `artisan` hoặc `composer.json`?
+👉 **Trả lời**: Mặc định script sẽ kiểm tra để tránh cài nhầm vào thư mục không phải Laravel. Nếu bạn muốn cài đặt trước vào thư mục trống, hãy thêm cờ `--force`:
+```bash
+install.sh --force
+# Hoặc:
+laravel-test-init --force
+```
+
+### Q3: Chạy test trên SQLite `:memory:` bị lỗi hàm MySQL (`JSON_CONTAINS`, `DATE_FORMAT`)?
+👉 **Trả lời**: Mở tài liệu `docs/07-troubleshooting-and-debugging.md` (mục 5) để xem cách đăng ký hàm giả lập trong `setUp()`, hoặc chuyển kết nối test sang một container MySQL test riêng.
+
+### Q4: Làm sao chặn merge Pull Request nếu Code Coverage dưới 80%?
+👉 **Trả lời**: Bộ công cụ đã tạo sẵn file `.github/workflows/unit-tests.yml` (hoặc `.gitlab-ci.yml`). Pipeline CI sẽ tự động chạy song song trên PHP 8.2, 8.3, 8.4 và tự động từ chối merge nếu độ phủ < 80%.
+
+---
+
+## 8. Bảng Tra Cứu Toàn Bộ Lệnh (Full Cheat Sheet)
+
+| Nhiệm Vụ | Lệnh Terminal / Claude Code | Ngữ Cảnh Sử Dụng |
+| :--- | :--- | :--- |
+| **Cài đặt từ xa (Không cần clone)** | `curl -fsSL <URL>/install.sh \| bash` | Đứng tại source code Laravel và chạy 1 dòng duy nhất |
+| **Cài đặt toàn cục (Global Mode)** | `curl -fsSL <URL>/install.sh \| bash -s -- --global` | Cài vào máy dùng cho mọi folder |
+| **Cài đặt vào thư mục trống** | `curl -fsSL <URL>/install.sh \| bash -s -- . --force` | Dùng khi thư mục chưa có `composer.json` |
+| **Khởi tạo test runner nhanh** | `laravel-test-init` (hoặc `sg-test-init`) | Gõ tại terminal của bất kỳ dự án nào |
+| **Cập nhật bộ công cụ (1-Click)** | `laravel-test-update` (hoặc `sg-test-update`) | Kéo bản mới nhất từ Git về máy mọi lúc |
+| **Quét & Setup môi trường test** | `/laravel-test-setup` | Chạy trong Claude Code để kiểm tra cấu hình |
+| **Tự động cài gói composer thiếu**| `/laravel-test-setup --install` | Cài `mockery`, `faker`, `paratest` vào container |
+| **Autopilot: Viết xong test luôn**| `/laravel-unit-test --all --run` | 1 lệnh tự setup, viết test cả dự án, chạy test & tự fix |
+| **Sinh test cho 1 file & test luôn**| `/laravel-unit-test app/.../Service.php --run`| Sinh test cho 1 class và chạy test kiểm tra ngay |
+| **Sinh test cả thư mục** | `/laravel-unit-test app/Services/ --run` | Khi cần phủ test cho cả 1 folder / module |
+| **Quét dự án lớn chưa có test** | `/laravel-unit-test --untested` | Tìm các class thiếu test để sinh hàng loạt |
+| **Sinh test cho Git Diff** | `/laravel-unit-test --changed --run` | Trước khi tạo Pull Request trên Git |
+| **Review chất lượng file test** | `/laravel-test-review tests/.../Test.php`| Chấm điểm thang 100 & bắt lỗi anti-patterns |
+| **Sinh code Mockery nhanh** | `/laravel-mock-helper MyInterface` | Sinh code mock sẵn dùng |
+| **Chạy test tự nhận diện** | `./test-runner.sh --filter=MyTest` | Tự bắt Docker / Sail / Local |
+| **Tra cứu sửa lỗi** | Đọc `docs/07-troubleshooting-and-debugging.md` | Sửa 10 lỗi thường gặp nhất |
+| **Tra cứu 7 ca khó** | Đọc `docs/09-advanced-edge-cases.md` | `DB::transaction()`, Trait, Upload file, Queue |
+| **Tra cứu sửa lỗi** | Đọc `docs/07-troubleshooting-and-debugging.md` | Sửa 10 lỗi thường gặp nhất |
+| **Tra cứu 7 ca khó** | Đọc `docs/09-advanced-edge-cases.md` | `DB::transaction()`, Trait, Upload file, Queue |
+
+---
+
+## 9. Ma Trận Tương Thích & Bản Quyền
+
+| Thành Phần | Phiên Bản Hỗ Trợ |
 | :--- | :--- |
-| **PHP** | 8.0, 8.1, 8.2, 8.3, **8.4+** (Hỗ trợ Property Hooks, Asymmetric Visibility) |
-| **Laravel** | 9.x, 10.x, 11.x, **12.x & 13.x (Latest & Future-ready)** |
-| **PHPUnit** | 9.x (DocBlock), 10.x, **11.x & 12.x** (PHP 8 Attributes `#[Test]`, `#[DataProvider]`) |
-| **Pest PHP** | v2.x & **v3.x** (Hỗ trợ Architectural Testing `arch()`, Mutation testing) |
+| **PHP** | 8.0, 8.1, 8.2, 8.3, **8.4+** (Property Hooks, Asymmetric Visibility) |
+| **Laravel** | 8.x, 9.x, 10.x, 11.x, **12.x & 13.x (Kiến trúc hiện đại)** |
+| **PHPUnit** | 9.x (DocBlock fallback), 10.x, **11.x & 12.x** (PHP 8 Attributes `#[Test]`) |
+| **Pest PHP** | v2.x & **v3.x** (Architecture Testing `arch()`, Mutation testing) |
 | **Mocking** | Mockery, PHPUnit Test Doubles, Laravel Built-in Fakes, `Concurrency::fake()`, `Context::fake()` |
 | **Database** | SQLite In-Memory (`:memory:`), MySQL Test DB |
-| **Môi trường** | Docker Compose, Laravel Sail, Native PHP CLI |
+| **Hệ Điều Hành** | macOS, Linux, WSL2 (Windows), Docker, CI/CD Environments |

---
-
-## 📜 Giấy Phép & Bản Quyền
-Phát triển bởi Smartgift AI Team. Phục vụ tự động hóa quy trình kiểm thử phần mềm đạt chuẩn chất lượng cao.
+### Giấy Phép (License)
+Phát hành theo giấy phép mã nguồn mở [MIT License](LICENSE). Bất kỳ ai cũng có quyền tự do sử dụng, chỉnh sửa và đóng góp cho dự án.