Code structure

Tài liệu kỹ thuật dành cho Developer tiếp nhận dự án
Phiên bản 1.0 — Cập nhật lần cuối: 2026

🧭 Giới thiệu tài liệu

Tài liệu này mô tả cấu trúc mã nguồn, quy tắc tổ chức module, pipeline xử lý tác vụ và hướng dẫn debug của Social Tool Worker. Đây là tài liệu dành cho developer cần hiểu cách hệ thống hoạt động để bảo trì hoặc mở rộng.

1. Hệ thống này làm gì?

Social Tool Worker là automation engine — nhận lệnh từ API Server (qua NATS hoặc HTTP), sau đó:

Lưu task vào MongoDB (queue nội bộ).

Cron engine quét task pending, mở trình duyệt headless Chrome.

Nạp cookie + proxy vào browser, truy cập URL mục tiêu.

Thực hiện hành động (like, comment, share, login...).

Gửi kết quả trở lại API Server.

Điểm mấu chốt: Worker không kết nối trực tiếp vào MySQL của API Server. Mọi giao tiếp đều qua NATS message hoặc HTTP webhook.

2. Cấu trúc thư mục `/src`

src/
├── index.ts              ← Entry point: kết nối DB, đăng ký NATS/HTTP, khởi chạy server
│
├── api/                  ← HTTP API controllers (dùng khi USE_NATS=false)
│   ├── chatgpt/          ← API endpoint cho ChatGPT
│   ├── cookie/           ← API cookie management
│   ├── logs/             ← API xem log file
│   ├── proxy/            ← API proxy management
│   └── task/             ← API task management
│
├── nats/                 ← 🔥 Module chính (dùng khi USE_NATS=true)
│   ├── index.ts          ← Đăng ký NATS listeners + Dynamic Worker Allocation
│   ├── config/           ← Hằng số cấu hình (ACTIONS_LIMITS)
│   │
│   ├── task/             ← Module thực thi hành động MXH
│   │   ├── task.model.ts
│   │   ├── task.service.ts
│   │   ├── task.cron.ts
│   │   ├── task.sub.ts
│   │   ├── task.controller.ts
│   │   ├── task.dto.ts
│   │   └── task.mapper.ts
│   │
│   ├── cookie/           ← Module login / lấy cookie
│   │   ├── cookie.model.ts
│   │   ├── cookie.service.ts
│   │   ├── cookie.cron.ts
│   │   ├── cookie.sub.ts
│   │   ├── cookie.controller.ts
│   │   └── cookie.dto.ts
│   │
│   ├── proxy/            ← Module kiểm tra proxy
│   │   ├── proxy.model.ts
│   │   ├── proxy.service.ts
│   │   ├── proxy.cron.ts
│   │   ├── proxy.sub.ts
│   │   ├── proxy.controller.ts
│   │   └── proxy.dto.ts
│   │
│   ├── task_join/        ← Module join group
│   │   ├── task_join.model.ts
│   │   ├── task_join.service.ts
│   │   ├── task_join.cron.ts
│   │   ├── task_join.sub.ts
│   │   ├── task_join.controller.ts
│   │   └── task_join.dto.ts
│   │
│   ├── cookie_proxy/     ← Model lưu lịch sử cookie-proxy
│   │   └── cookie-proxy.model.ts
│   │
│   └── logs/             ← Controller xem log
│       └── logs.controller.ts
│
├── services/             ← Business services bổ sung
│   ├── check-proxy/      ← Logic kiểm tra proxy
│   └── webhook/          ← Logic gửi webhook
│
├── config/               ← Cấu hình hệ thống
│   ├── constants.ts      ← Hằng số global
│   └── database/
│       └── mongodb.config.ts  ← Kết nối MongoDB
│
├── utils/                ← Tiện ích dùng chung
│   ├── browser_manager/  ← Quản lý pool session Puppeteer
│   ├── captcha/          ← Tích hợp dịch vụ giải captcha
│   ├── chat_gpt/         ← Tích hợp OpenAI API
│   ├── concurrency/      ← Mutex, giới hạn concurrent
│   ├── social/           ← Enum nền tảng MXH (SocialType)
│   ├── file/             ← Đọc/ghi file
│   ├── number/           ← Tiện ích số học
│   ├── env.ts            ← Load biến môi trường
│   ├── logger.ts         ← Logger (file + console)
│   ├── nats.ts           ← NATS connection helper
│   ├── cookieUtils.ts    ← Parse/validate cookie
│   ├── extractors.ts     ← Trích xuất dữ liệu từ trang web
│   ├── error.custom.ts   ← Class lỗi tùy chỉnh
│   ├── error.middleware.ts ← Middleware xử lý lỗi
│   ├── telegramNotify.ts ← Gửi thông báo Telegram
│   └── createElysia.ts   ← Factory tạo Elysia instance
│
└── types/                ← TypeScript types
    └── global/           ← Interface & Type toàn cục

3. Quy tắc tổ chức Module

Mỗi module NATS tuân theo cấu trúc chuẩn gồm 6 file:

File	Vai trò	Khi nào cần sửa
`*.model.ts`	Định nghĩa Typegoose schema (MongoDB collection)	Thêm/sửa trường dữ liệu
`*.service.ts`	Logic nghiệp vụ: query DB, xử lý task, gọi browser	Thêm logic mới
`*.cron.ts`	Cron engine: quét task pending, gọi service xử lý	Thay đổi tần suất, logic quét
`*.sub.ts`	NATS subscriber: lắng nghe event, lưu task vào DB	Thêm event mới từ API Server
`*.controller.ts`	HTTP endpoints (Elysia routes)	Thêm API mới
`*.dto.ts`	Data Transfer Object: validate, transform dữ liệu	Thay đổi format dữ liệu

⚠️ Lưu ý cho dev mới: Logic nghiệp vụ chỉ nằm trong *.service.ts. Subscriber và Controller chỉ nhận dữ liệu và chuyển tiếp cho Service. Không viết business logic trong subscriber hoặc controller.

4. Pipeline xử lý tác vụ

4.1. Luồng nhận và thực thi Task

[NATS Event từ API Server]
        │
        ▼
[*.sub.ts] — Subscriber nhận message
        │  Validate message format
        │  Transform thành document
        ▼
[*.model.ts] — Lưu vào MongoDB (status: PENDING)
        │
        ▼
[*.cron.ts] — Cron quét định kỳ
        │  Lấy batch task PENDING
        │  Nhóm theo user_id (tránh xung đột tài khoản)
        │  Cập nhật status → PROCESSING
        ▼
[*.service.ts] — Xử lý nghiệp vụ
        │  Khởi tạo browser session (Puppeteer)
        │  Nạp cookie + cấu hình proxy
        │  Thực thi hành động trên MXH
        │  Xử lý captcha nếu gặp
        ▼
[Kết quả]
   ├── SUCCESS → Gọi webhook → Xóa task khỏi MongoDB
   └── FAILED  → Ghi log → Retry hoặc gửi lỗi về API Server

4.2. Cron Engine — Processing Flow

Mỗi cron cycle thực hiện các bước sau:

Lấy danh sách user_id có task pending (tránh xử lý trùng lặp).

Với mỗi user_id, lấy 1 task theo thứ tự ưu tiên.

Kiểm tra concurrent limit (BROWSER_LIMIT).

Mở browser session và thực thi task.

Đánh dấu kết quả và gửi webhook callback.

Đóng browser session để giải phóng tài nguyên.

💡 Tại sao nhóm theo user_id? Để đảm bảo mỗi tài khoản MXH chỉ chạy một task tại một thời điểm, tránh xung đột session trên cùng trình duyệt.

5. Entry Point — `src/index.ts`

File này khởi tạo toàn bộ ứng dụng qua 4 bước:

[1] Kết nối MongoDB
        │
        ▼
[2] Tạo Elysia server
    → Đăng ký route cơ bản: /, /health, /logs
        │
        ▼
[3] Chọn chế độ vận hành:
    ├── USE_NATS=true  → registerNatsEvents() (NATS mode)
    └── USE_NATS=false → apiRoutes + Swagger (HTTP mode)
        │
        ▼
[4] Đăng ký HTTP controllers bổ sung
    → taskController, cookieController, logsController
    → proxyController, taskJoinController, chatgptController
        │
        ▼
[5] Khởi chạy server tại PORT

6. Module `nats/index.ts` — Dynamic Worker Allocation

File này là bộ não điều phối của Worker ở chế độ NATS. Chức năng chính:

Đăng ký NATS listeners cho 4 module (Task, Cookie, Proxy, TaskJoin).

Reset trạng thái task từ PROCESSING → PENDING khi khởi động (tránh task bị stuck).

Phân bổ worker động dựa trên pending count của từng module.

Tự động tái phân bổ mỗi 120 giây hoặc khi có trigger thủ công.

Graceful shutdown — đợi task đang chạy hoàn thành trước khi dừng cron.

7. Hướng dẫn debug nhanh

Task bị stuck ở PENDING

Kiểm tra cron tương ứng có đang chạy không (xem log [CRON]).

Kiểm tra CRON_TASK_LIMIT — có thể tất cả worker đang bận.

Kiểm tra BROWSER_LIMIT — có thể đã đạt giới hạn browser session.

Kiểm tra kết nối MongoDB — connectDatabase() có thành công không.

Task failed liên tục

COOKIE_ERROR (-5): Cookie đã hết hạn → cần login lại.

CAPTCHA (-3): Gặp captcha → kiểm tra OMO_CAPTCHA_KEY còn hiệu lực.

NOT_FOUND (-2): URL mục tiêu không tồn tại hoặc đã bị xóa.

PROXY_ERROR: Proxy không hoạt động → kiểm tra Proxy Module.

Worker không nhận task mới

Kiểm tra kết nối NATS: NATS_URL có đúng không.

Kiểm tra NATS_QUEUE_GROUP — phải giống với API Server.

Xem log [NATS] All event listeners registered có xuất hiện không.

Browser session bị leak

Kiểm tra biến SO_ENABLE_BROWSER_LEFTOVERS_CLEANUP=true trong Docker env.

Xem browserManager.sessionsCount qua endpoint /.

Kiểm tra DEBUG_END_SESSION=true để đảm bảo session được đóng sau task.

8. Quy ước code

Quy ước	Chi tiết
Ngôn ngữ	TypeScript strict mode
Naming	camelCase cho biến/hàm, PascalCase cho class/enum
Module	Mỗi module NATS gồm 6 file chuẩn (model, service, cron, sub, controller, dto)
Logic	Business logic chỉ ở `*.service.ts`
DB Access	Chỉ qua Typegoose model, không query raw MongoDB
Error	Dùng class `APIError` trong `utils/error.custom.ts`
Logging	Dùng `logger` từ `@/utils`, không dùng `console.log` trong production
Formatting	Prettier (cấu hình sẵn)
Linting	OxLint

Tài liệu được cập nhật lần cuối: 2026. Mọi thắc mắc vui lòng liên hệ đội ngũ kỹ thuật.

Cấu trúc Mã nguồn — Social Tool Worker#

🧭 Giới thiệu tài liệu#

1. Hệ thống này làm gì?#

2. Cấu trúc thư mục /src#

3. Quy tắc tổ chức Module#

4. Pipeline xử lý tác vụ#

4.1. Luồng nhận và thực thi Task#

4.2. Cron Engine — Processing Flow#

5. Entry Point — src/index.ts#

6. Module nats/index.ts — Dynamic Worker Allocation#

7. Hướng dẫn debug nhanh#

Task bị stuck ở PENDING#

Task failed liên tục#

Worker không nhận task mới#

Browser session bị leak#

8. Quy ước code#

Cấu trúc Mã nguồn — Social Tool Worker