Hướng Dẫn Sử Dụng & Thiết Lập (User Guide)#
Tài liệu này cung cấp hướng dẫn chi tiết để đội ngũ Developer và QC có thể tự thiết lập môi trường chạy dự án ở Local, cũng như cách tương tác với hệ thống API Interface (Swagger).
1. Tài Liệu API Interface (Swagger UI)#
H ệ thống đã tích hợp sẵn thư viện chuẩn hóa OpenAPI documentation qua module Laravel L5-Swagger (darkaonline/l5-swagger). Tất cả các routes API chính dùng cho Admin đều có Interface Schema chuẩn tại đây.1.1. Đường dẫn truy cập#
Môi trường Local: Sau khi khởi chạy Backend, truy cập http://localhost:8000/api/doc
Cách xem tài liệu: Truy cập thẳng đường link này trên trình duyệt để xem toàn bộ Request, Response, Body format của Endpoint được định nghĩa trực quan.
1.2. Authentication trên Interface#
Hệ thống sử dụng JWT Token. Để test các API cần bảo mật trực tiếp trên màn hình Swagger, bạn làm theo các bước sau:1.
Gọi API /auth/login với tài khoản hợp lệ để lấy JWT Token (access_token).
2.
Bấm vào nút Authorize (Thường có biểu tượng ổ khóa) ở góc phải màn hình Swagger UI.
3.
Dán Token vào với format: Bearer {access_token}. (Ví dụ: Bearer eyJ0eXAi...)
4.
Bấm Authorize để lưu lại và bắt đầu test các API khác.
2. Vận Hành Backend (api)#
Công nghệ cốt lõi: PHP >= 8.1, Laravel 10.
Phụ thuộc: MySQL, Redis, Elasticsearch.
Phương Pháp Setup: Hybrid (Docker kết hợp Native)#
Theo định hướng của team, môi trường sẽ thiết lập theo kiến trúc Hybrid:Mã nguồn PHP/Laravel chạy trực tiếp trên server native (php artisan serve).
Các dịch vụ nền tảng (Database, Redis, Elasticsearch) sẽ được container hóa chạy qua Docker giúp code dễ debug mà không cần cài thủ công các dịch vụ nặng.
Các bước cài đặt và build Local:#
Bước 1: Clone / Copy thư mục source api.Bước 2: Khởi tạo các Core Services bằng Docker (Không cần chạy container tools_api_php):Bước 3: Cài đặt các thư viện PHP:Bước 4: Thiết lập file môi trường:Bước 5: Cấu hình file .env kết nối Hybrid:
Mở file .env, lưu ý dùng địa chỉ 127.0.0.1 cùng các cổng map trong docker-compose.yml (để code host giao tiếp được với docker):DB_HOST=127.0.0.1
DB_PORT=39001
DB_DATABASE=tools
REDIS_HOST=127.0.0.1
REDIS_PORT=38001
ELASTICSEARCH_HOST=127.0.0.1
ELASTICSEARCH_PORT=9200
Chạy Hàng Đợi (Queues & Background worker)#
Để các tác vụ nền như Report hay Scan Keyword hoạt động được (bắt buộc Redis đang chạy), bạn cần chạy:Kích Hoạt Crontab (Task Scheduling)#
Vào server hoặc local setup chạy CRON job sau mỗi 1 phút:
3. Vận Hành Frontend (admin)#
Công nghệ cốt lõi: Vue 3, Vite, TypeScript, TailwindCSS, Pinia.
Yêu cầu: Phiên bản Node.js >= 18.3.0.
Các bước cài đặt và build Local:#
Bước 1: Cài đặt các gói thư viện:Bước 2: Thiết lập file môi trường:
Copy file .env.development.example thành .env.development.Bước 3: Kết Nối Admin với API:
Mở file .env.development và cấu hình biến kết nối chỉ ra địa chỉ Backend:VITE_API_SERVER=[http://127.0.0.1:8000]
Modified at 2026-03-31 03:21:53
