TÀI LIỆU KỸ THUẬT: CODE STRUCTURE - SEARCH TOOL

Cấu trúc mã nguồn của Search Tool được phân mảnh theo module rõ ràng (Modular Architecture), vận hành trên môi trường Bun và ứng dụng Mongoose để xử lý cơ sở dữ liệu.

I. CÂY THƯ MỤC MÃ NGUỒN (DIRECTORY LAYOUT)

tools/
├── src/
│   ├── index.ts                        # Entry Point: Gắn kết Database, Khởi động Elysia, Đăng ký Route.
│   │
│   ├── api/                            # Tầng Giao tiếp HTTP (API Layer).
│   │   ├── index.ts                    # Tệp gom nhóm (Prefix: /api).
│   │   ├── search/                     # Phân hệ: Nhiệm vụ tìm kiếm Google/CocCoc.
│   │   │   ├── search.controller.ts    # Tầng Định tuyến & Điều hướng Request.
│   │   │   ├── search.dto.ts           # Schema xác thực đầu vào.
│   │   │   ├── search.model.ts         # Khai báo Collection Mongoose.
│   │   │   ├── search.service.ts       # Logic đọc/ghi dữ liệu.
│   │   │   └── search.cron.ts          # Bộ lên lịch thực thi khởi chạy Browser.
│   │   │
│   │   ├── proxy/                      # Phân hệ: Xoay vòng Proxy.
│   │   ├── search-anchor-text/         # Phân hệ: Trích xuất Backlink.
│   │   └── test/                       # Phân hệ: Công cụ kiểm thử nội bộ (Dev Debug).
│   │
│   ├── config/                         # Tầng Thiết lập Môi trường tĩnh.
│   │   └── database/
│   │       └── mongodb.config.ts       # Thông số khởi tạo Mongoose.
│   │
│   ├── types/                          # Định nghĩa cấu trúc kiểu TypeScript toàn cục.
│   │
│   └── utils/                          # Tầng Công cụ chia sẻ (Shared Utilities).
│       ├── createElysia.ts             # Nhà máy (Factory) khởi tạo Elysia Instance.
│       ├── env.ts                      # Bộ phân tích biến môi trường.
│       ├── error.middleware.ts         # Lớp bọc xử lý Lỗi cục bộ.
│       ├── logger.ts                   # Trình ghi Log phân cấp (Có gắn màu/thời gian).
│       ├── captcha/                    # Tiện ích bẻ khóa Captcha (nếu có).
│       ├── file/                       # Tiện ích tương tác File hệ thống.
│       └── browser_manager/            # Tầng Quản trị Nhân Trình Duyệt.
│           ├── index.ts                # Lớp quản lý Pool Chrome Sessions.
│           └── device.ts               # Khai báo kích thước hiển thị theo thiết bị.
│
├── plugin/                             # Phần mở rộng cấu hình Browser.
├── storage/
│   └── log/                            # Nơi chứa các tệp nhật ký hệ thống sinh ra khi chạy.
├── tmp/                                # Nơi lưu trữ Chrome Profile và Hình ảnh Snapshot tạm thời.
│
├── package.json                        # Khai báo thư viện (Dependencies).
├── tsconfig.json                       # Khai báo tiêu chuẩn TypeScript.
└── docker-compose.yml                  # Tập lệnh khởi tạo MongoDB cục bộ.

II. ĐẶC ĐIỂM KIẾN TRÚC (ARCHITECTURAL TRAITS)

1. Định tuyến Tích hợp (Elysia Controllers)

Toàn bộ logic HTTP được tổ chức gọn gàng trong các tệp .controller.ts. Framework Elysia cho phép khai báo định tuyến (Route), kiểm duyệt dữ liệu (Schema Validation) và xử lý ngoại lệ đồng thời bằng cú pháp nối chuỗi (Chaining) gọn gàng.

2. Sự cách ly của Cronjob (Isolated Scheduler)

Khác với các hệ thống phổ thông dùng API để kích hoạt hàm, Tool này tách biệt toàn bộ khâu thao tác trình duyệt vào các tệp .cron.ts.

Các file Cron này sử dụng @elysiajs/cron để chạy vòng lặp mỗi giây (Every Second).

Bảo vệ Đa luồng: Cơ chế protect: true được thiết lập trên các hàm Webhook, đảm bảo chỉ có đúng 1 tiến trình Webhook chạy tại một thời điểm, tránh việc gọi Callback trùng lặp làm loạn dữ liệu hệ thống trung tâm.

3. Tầng Công cụ (Utils Layer)

Trái tim của dự án nằm tại utils/browser_manager. Tầng này đóng gói toàn bộ logic gọi Puppeteer, cấu hình ẩn danh (Stealth Plugin), xử lý lỗi treo trang (Page Crash), và trả về cho các Cronjob một phiên duyệt web sạch sẽ và sẵn sàng hoạt động.

Code Structure

TÀI LIỆU KỸ THUẬT: CODE STRUCTURE - SEARCH TOOL#

I. CÂY THƯ MỤC MÃ NGUỒN (DIRECTORY LAYOUT)#

II. ĐẶC ĐIỂM KIẾN TRÚC (ARCHITECTURAL TRAITS)#

1. Định tuyến Tích hợp (Elysia Controllers)#