Tài liệu kỹ thuật – Phiên bản 1.0
Mô tả cấu trúc MongoDB của hệ thống Social Tool Worker
| Thành phần | Chi tiết |
|---|---|
| Database | MongoDB ≥ 7 |
| ORM | Typegoose + Mongoose |
| Model definitions | src/nats/*/\*.model.ts |
| Kết nối DB | src/config/database/mongodb.config.ts |
| Default DB name | social-tools |
Lưu ý: MongoDB của Worker là tách biệt với MySQL của API Server. Worker chỉ dùng MongoDB để lưu task queue tạm thời, không lưu dữ liệu nghiệp vụ dài hạn.
tasksLưu trữ các tác vụ tương tác MXH (like, comment, share, post...) nhận từ API Server.
| Trường | Kiểu | Mô tả |
|---|---|---|
_id | string | MongoDB ObjectId (tự sinh) |
task_id | string | Bắt buộc — ID task từ API Server |
group_id | string | Nhóm task liên quan (index) |
created_by | number | ID người tạo |
social_account_id | number | ID tài khoản MXH thực thi |
campaign_platform_id | string | Bắt buộc — ID cấu hình chiến dịch |
action_name | string | Tên hành động: like, share, comment... |
type | TaskType | Nền tảng MXH (1=Facebook, 2=Instagram, 3=Twitter, 4=TikTok, 5=Google, 6=Telegram) |
action | TaskAction | Loại hành động (xem bảng enum bên dưới) |
url | string | URL bài viết/trang mục tiêu |
content | string | Nội dung (cho comment/reply/post) |
targetGroup | string | URL group mục tiêu |
status | TaskStatus | 0: PENDING, 1: PROCESSING, 2: COMPLETED, 3: IN_QUEUE |
result_status | TaskResultStatus | Kết quả chi tiết (xem enum bên dưới) |
result_error | string | Thông báo lỗi nếu thất bại |
error_code | number | Mã lỗi |
execution_time | number | Thời gian thực thi (giây) |
retry_cookie_count | number | Số lần retry cookie (mặc định: 0) |
webhook_url | string | URL callback gửi kết quả |
call_webhook_count | number | Số lần đã gọi webhook |
skip_post | number | Số bài viết bỏ qua |
keywords | string | Từ khóa tìm kiếm |
result_url | string | URL kết quả sau khi thực thi |
result_page_name | string | Tên trang kết quả |
avatar_url | string | URL avatar (dùng cho đổi avatar) |
social_account | SocialAccount | Bắt buộc — Embedded: thông tin tài khoản |
proxy | ProxyInfo | Embedded: thông tin proxy |
comment_info | CommentInfo | Embedded: cấu hình comment |
reply_info | ReplyInfo | Embedded: cấu hình reply |
share_info | ShareInfo | Embedded: cấu hình share |
post | PostInfo | Embedded: cấu hình post (ảnh) |
captcha_info | CaptchaInfo | Embedded: cấu hình captcha |
page_info | PageInfo | Embedded: thông tin trang mục tiêu |
createdAt | Date | Thời gian tạo (auto) |
updatedAt | Date | Thời gian cập nhật (auto) |
| Giá trị | Tên | Mô tả |
|---|---|---|
| 1 | COMMENT | Bình luận bài viết |
| 2 | REPLY | Trả lời comment |
| 3 | POST | Đăng bài mới |
| 4 | SHARE | Chia sẻ bài viết |
| 5 | LIKE | Thả cảm xúc |
| 6 | CRAW | Thu thập dữ liệu |
| 7 | REPORT | Báo cáo bài viết |
| 8 | RENAME_USER | Đổi tên |
| 9 | CHANGEAVATAR | Đổi ảnh đại diện |
| 10 | CHECK_NOTIFICATION | Kiểm tra thông báo |
| 11 | CONFIRM_FRIEND_REQUEST | Xác nhận kết bạn |
| 12 | CHECK_NEW_FEED | Kiểm tra bảng tin |
| 13 | COMMENT_ADS | Comment quảng cáo |
| 14 | REPLY_ADS | Reply quảng cáo |
| Giá trị | Tên | Mô tả |
|---|---|---|
| 1 | SUCCESS | Thành công |
| 0 | UNKNOWN | Chưa xác định |
| -1 | ERROR | Lỗi chung |
| -2 | NOT_FOUND | URL không tìm thấy |
| -3 | CAPTCHA | Gặp captcha |
| -4 | MAX_RETRY | Đã hết lượt retry |
| -5 | COOKIE_ERROR | Cookie lỗi/hết hạn |
cookiesLưu trữ yêu cầu login/lấy cookie cho tài khoản MXH.
| Trường | Kiểu | Mô tả |
|---|---|---|
_id | string | MongoDB ObjectId |
cookie_id | number | Bắt buộc — ID cookie trên Admin |
created_by | number | ID người tạo |
type | CookieType | Nền tảng MXH (1–6, giống TaskType) |
device_size | DeviceSize | Bắt buộc — {width, height, ratio} |
user_agent | string | Bắt buộc — User-Agent trình duyệt |
value | string | Cookie string hiện tại |
username | string | Tên đăng nhập tài khoản |
password | string | Mật khẩu tài khoản |
secret_key | string | Mã 2FA |
name | string | Tên hiển thị |
profileAvatar | string | URL avatar thu thập được |
profileUrl | string | URL profile thu thập được |
profileEmail | string | Email thu thập được |
profileGender | number | Giới tính thu thập được |
profilePhone | string | SĐT thu thập được |
status | CookieProcessingRaw | 0: PENDING, 1: PROCESSING, 2: COMPLETED |
raw_status | CookieStatusRaw | Kết quả: 0: OPEN, 1: DONE, 2: FAIL |
error_message | string | Thông báo lỗi |
error_code | number | Mã lỗi |
ip_public | string | IP public khi login |
proxy | Proxy | Embedded: {id, ip, port, username, password} |
captcha_info | CaptchaInfo | Embedded: cấu hình captcha |
call_webhook_count | number | Số lần đã gọi webhook |
proxiesLưu trữ yêu cầu kiểm tra proxy (check alive, detect IP).
| Trường | Kiểu | Mô tả |
|---|---|---|
_id | string | MongoDB ObjectId |
proxy_id | number | ID proxy trên Admin |
created_by | number | ID người tạo |
status | Status | 0: PENDING, 1: PROCESSING, 2: COMPLETED, 3: FAILED |
status_send | SendAdminStatus | Đã gửi Admin: 0: NOTSEND, 1: SENDED |
status_code | number | HTTP status code khi check |
response | string | Response body khi check |
is_error | boolean | Có lỗi không |
ip | string | Bắt buộc — Địa chỉ IP proxy |
port | number | Bắt buộc — Port proxy |
username | string | Bắt buộc — Tên xác thực |
password | string | Bắt buộc — Mật khẩu xác thực |
ip_public | string | Bắt buộc — IP public khai báo |
detected_ip | string | IP public thực tế phát hiện được |
rotate_url | string | URL để rotate IP |
rotate_time | number | Thời gian auto rotate (giây) |
disable_auto_rotate | boolean | Tắt auto rotate |
auth_token | string | Token xác thực |
region | string | Vùng địa lý |
webhook_url | string | URL callback |
call_webhook_count | number | Số lần đã gọi webhook |
task_id | number | ID task liên quan |
campaign_platform_id | number | ID chiến dịch liên quan |
retry_count | number | Số lần đã retry (mặc định: 0) |
max_retries | number | Số retry tối đa (mặc định: 3) |
error_message | string | Thông báo lỗi |
batch_id | string | ID batch debug |
checked_at | Date | Thời điểm kiểm tra |
task_joinsLưu trữ yêu cầu join group / kiểm tra trạng thái join.
| Trường | Kiểu | Mô tả |
|---|---|---|
_id | string | MongoDB ObjectId |
id | number | Bắt buộc — ID task join từ API |
created_by | number | ID người tạo |
campaign_join_id | number | Bắt buộc — ID chiến dịch join |
type | TaskJoinType | Nền tảng MXH (1–6) |
campaign_join_type | CampaignJoinType | join (tham gia) hoặc check (kiểm tra) |
page_url | string | Bắt buộc — URL group cần join |
status_tool | TaskJoinStatus | 0: PENDING, 1: PROCESSING, 2: COMPLETED |
result_status | TaskJoinResultStatus | Kết quả (giống TaskResultStatus) |
result_error | string | Thông báo lỗi |
error_code | number | Mã lỗi |
execution_time | number | Thời gian thực thi (giây) |
group_type | GroupType | public hoặc private |
check_join_status | JoinGroupStatus | unknown, pending, approve, reject |
account | SocialAccount | Bắt buộc — Embedded: {id, name, value, user_agent, device_size} |
proxy | Proxy | Embedded: {ip, port, username, password} |
ai_info | AIInfo | Embedded: cấu hình AI |
captcha_info | CaptchaInfo | Embedded: cấu hình captcha |
cookie_proxyLưu lịch sử cookie–proxy đã sử dụng, phục vụ việc kiểm tra và gán proxy cho cookie login.
| Trường | Kiểu | Mô tả |
|---|---|---|
_id | string | MongoDB ObjectId |
id | number | ID tham chiếu |
cookie_id | number | Bắt buộc — FK cookie |
social_type | CookieType | Nền tảng MXH (1–4) |
ip_public | string | Bắt buộc — IP public |
auth_token | string | Token xác thực |
ip | string | Bắt buộc — IP proxy |
port | number | Bắt buộc — Port proxy |
username | string | Bắt buộc — Tên xác thực |
password | string | Bắt buộc — Mật khẩu |
webhook_url | string | URL callback |
call_webhook_count | number | Số lần gọi webhook |
last_used | Date | Lần sử dụng gần nhất |
{ cookie_id: 1, proxy_id: 1 } — Tra cứu nhanh theo cặp cookie–proxy{ last_used: -1 } — Sắp xếp theo lần dùng gần nhấttasks){
id: number // ID trên Admin
name: string // Tên hiển thị
status?: string // Trạng thái
active: boolean // Có khả dụng không
value?: string // Cookie string
username?: string // Tên đăng nhập
password?: string // Mật khẩu
secret_key?: string // Mã 2FA
user_agent: string // User-Agent
device_size: { width, height, ratio }
newFirstName?: string // Tên mới (đổi tên)
newMiddleName?: string // Tên đệm mới
newLastName?: string // Họ mới
newAvatarUrl?: string // URL avatar mới
}{
api_key?: string // API key (từ user hoặc hệ thống)
instruction?: string // System instruction cho AI
prompt?: string // Prompt template
service_name?: string // Tên dịch vụ AI
generated?: string // Kết quả đã sinh
generated_list: string[] // Danh sách kết quả
}{
ai_info?: AIInfo // Cấu hình AI
text?: string // Nội dung comment cố định
comment_image_url?: string // URL ảnh đính kèm
keyword?: string // Từ khóa
}{
ai_info?: AIInfo // Cấu hình AI
text: string[] // Danh sách nội dung reply
keyword?: string // Từ khóa
number_reply: number // Số reply (1–5, mặc định: 1)
}{
api_key: string // API key dịch vụ captcha
service_name: string // Tên dịch vụ (vd: omo)
}{
id?: number // ID trang
page_url?: string // URL trang
type?: string // Loại: page, group, profile, post
description?: string // Mô tả
}⚠️ Cần tuân thủ các quy ước dưới đây khi làm việc với MongoDB của Worker.
| Quy tắc | Chi tiết |
|---|---|
| 🗑️ Task tạm thời | Task được xóa khỏi MongoDB sau khi xử lý xong (nếu DEBUG_DELETE_TASK_AFTER_PROCESSING=true) |
| ♻️ Reset khi khởi động | Mọi task PROCESSING sẽ được reset về PENDING khi Worker khởi động lại |
| 📊 Index | tasks.status và tasks.group_id có index, cookie_proxy có compound index |
| 🔗 Không có Foreign Key | MongoDB không hỗ trợ FK — tính toàn vẹn dữ liệu phụ thuộc vào application logic |
| 📥 Embedded Document | Dữ liệu tài khoản, proxy được nhúng trực tiếp vào task (denormalized) để tránh lookup |
| ⏰ Timestamps tự động | createdAt và updatedAt do Typegoose/Mongoose tự quản lý |