1. Architecture
Social Tool Documentation
  • Tổng quan
  • Bussiness | Logic
    • Bussiness | Logic
  • Project
    • ADMIN
      • Tổng quan ADMIN
      • Architecture
        • System architecture
        • Code structure
      • Deployment
        • Local
        • Staging
        • Product
      • Hướng dẫn sử dụng
        • Đăng nhập
        • FAQ
        • Mạng xã hội
          • Tài khoản mạng xã hội
          • Nội dung bài viết & bình luận
          • Quản lý liên kết
          • Thư viện hình ảnh
          • Thu thập dữ liệu
        • Hệ thống
          • Quản lý proxy
        • Chiến dịch
          • Tạo & quản lý chiến dịch
          • Đăng nhập tài khoản
          • Check Proxy
          • Join Group
    • API
      • Tổng quan API
      • Architecture
        • System architecture
        • Database schema
        • Code structure
      • Deployment
        • Local
        • Staging
        • Product
      • API Interface
        • 🔑 Identity & Session
          • List users
          • Create user
          • Update info user
          • Update info user
          • List user departments
          • Delete user
          • List user's AI keys
          • Create AI key
          • Get user's active API key
          • Get supported services
          • Get supported AI models
          • Update AI key
          • Delete AI key
          • Get AI key by ID
          • List departments
          • Create department
          • Update department
          • Create department
          • Update department
          • Update department roles
          • Get department roles
          • Update department status
          • Delete department
          • List user sessions
          • Create user session
          • Delete user session
          • Get user sessions by user ID
          • Delete all user sessions
          • Update user session status
          • List user activity logs
          • Create user activity log
          • Get user activity logs
          • Delete user activity logs
          • User login
          • User registration
          • User logout
          • Logout from all devices
          • Refresh access token
          • Create api key
          • Reset password
          • Get current user
          • Get user roles
          • Create role
          • Update role
          • Update role
          • Update role
          • List user permission groups
          • Get user permission group by ID
          • Delete user permission group
          • Create user permission group
          • Update user permission group
          • Get all user permission groups with permissions
        • 🛰️ Proxy & Connectivity
          • List proxies
          • Create proxy
          • Create many proxies
          • Update proxy
          • Delete proxy
          • Get proxy by ID
          • Import proxies from CSV/Excel
          • Check expired proxies
          • Kiểm tra proxy (qua Campaign)
          • Xóa proxy
          • Cập nhật proxy
          • Proxy Group list
          • Create a Proxy Group
          • Get a Proxy Group by ID
          • Update a Proxy Group
          • Delete a Proxy Group
          • Delete a Proxy Group
          • List proxy providers
          • Create proxy provider
          • Update proxy provider
          • Delete proxy provider
          • Get proxy provider by ID
          • Import proxy packages from CSV
          • List proxy packages
          • Create proxy package
          • Update proxy package
          • Delete proxy package
          • Get proxy package by ID
          • Import proxy packages from CSV
        • 📱 Social Management
          • List socials
          • Create social
          • Update social
          • Delete social
          • Get social by ID
          • List social accounts
          • Create social account
          • Create social account
          • Get account tasks
          • Assign proxies to social account
          • Update social account
          • Delete social account
          • Get social account by ID
          • Join social account
          • Cancel social accounts
          • Cancel social accounts
          • Import social accounts from file
          • Get account usage statistics
          • Push cookies manually for specific accounts (via Campaign)
          • Đổi tên nhiều tài khoản (qua Campaign)
          • Đổi mật khẩu nhiều tài khoản (qua Campaign)
          • Đổi ảnh đại diện (qua Campaign)
          • Social Account Group list
          • Create a Social Account Group
          • Get a Social Account Group by ID
          • Create a Social Account Group
          • Delete a Social Account Group
          • List social pages
          • Create social page
          • Update social page
          • Delete social page
          • Get social page by ID
          • Batch update social page status
          • Batch delete social pages
          • Import social pages from file
          • Search social pages
          • Batch delete social pages
          • Social Page Group list
          • Create a Social Page Group
          • Get a Social Page Group by ID
          • Update a Social Page Group
          • Delete a Social Page Group
          • List social actions
          • Create social action
          • Update social type
          • Delete social action
          • Get social type by ID
          • List social pages
          • Create social content
          • Update social content
          • Delete social content
          • Get social content by ID
          • Batch delete social content
          • Import social accounts from file
          • Create a new social content group
          • Get paginated list of social content groups
          • Get social content group by ID
          • Update social content group
          • Soft delete social content group
          • Batch delete social content groups
          • Delete social content group
          • Get groups by social platform ID
          • Social Image list
          • Create a Social Image
          • Get a Social Image by ID
          • Update a Social Image
          • Delete a Social Image
          • Social Collect Data list
          • Create a Social Collect Data
          • Get a Social Collect Data by ID
        • 📁 Campaign Management
          • List campaigns
          • Create campaign
          • Update campaign
          • Delete campaign
          • Get campaign by ID
          • Create campaign platform
          • List campaign platforms
          • Update campaign platform
          • Delete campaign platform
          • Get campaign platform by ID
          • Create campaign platform
          • Create campaign platform
          • Clone campaign platforms
          • Cancel multiple campaign platforms
          • List campaign joins
          • Create campaign platform
          • List campaign joins
          • Update campaign platform
          • Update campaign platform
          • Update campaign platform
          • Update campaign platform
          • List jobs
          • Update job
          • Delete job
          • Get job by ID
          • List campaign platform tasks
          • Create campaign platform task
          • Update campaign platform task
          • Delete campaign platform task
          • Get campaign platform job task by ID
          • List Report Categories
          • Create Report Categories
          • Create Report Categories
          • Create Report Categories
          • List Report Details
          • Create Report Details
          • Create Report Details
          • Create Report Details
    • TOOL
      • Tổng quan TOOL
      • Architecture
        • Database schema
        • System architecture
        • Code structure
      • Deployment
        • Local
        • Staging
        • Product
      • API Interface
        • 🎯 NATS — Task
          • [NATS RPC] Tạo batch Task mới
          • [NATS RPC] Lấy danh sách tất cả Tasks
          • [NATS RPC] Đếm số Task đang chờ xử lý
          • [NATS RPC] Xóa tất cả Tasks
        • 🍪 NATS — Cookie
          • [NATS RPC] Thêm batch Cookie (Auto Login)
          • [NATS RPC] Lấy danh sách tất cả Cookies
          • [NATS RPC] Xóa tất cả Cookies
        • 🌐 NATS — Proxy
          • [NATS RPC] Gửi batch Proxy để kiểm tra
        • 🔗 NATS — TaskJoin
          • [NATS RPC] Tạo lệnh tham gia Group
          • [NATS RPC] Kiểm tra trạng thái tham gia Group
        • 📤 NATS — Callbacks
          • [NATS PUB] Kết quả thực thi Task
          • [NATS PUB] Kết quả Crawl dữ liệu
          • [NATS PUB] Kết quả Auto Login
          • [NATS PUB] Kết quả kiểm tra Proxy
          • [NATS PUB] Kết quả tham gia Group
          • [NATS PUB] Kết quả kiểm tra trạng thái tham gia
        • 📊 HTTP — Logs & Info
          • Service Root — Thông tin Worker
          • Health Check
          • Đọc file log
          • Log hôm nay
          • Log theo ngày cụ thể
          • Danh sách ngày có log
          • Test kết nối ChatGPT
        • 📋 HTTP — Data Query
          • Danh sách Tasks (phân trang + lọc)
          • Xóa tất cả Tasks
          • Danh sách tất cả Cookies
          • Xóa tất cả Cookies
          • Xóa Cookie theo _id
          • Danh sách Proxies (lọc theo task_id)
          • Xóa tất cả Proxies
          • Proxy Checks đang chờ xử lý
          • Proxy Checks đã hoàn thành
          • Xóa Proxy theo _id
          • Danh sách Task Join (phân trang + lọc)
          • Tạo Task Join (HTTP mode)
          • Xóa tất cả Task Join
  • Schemas
    • AIInfo
    • CommentInfo
    • ReplyInfo
    • ShareInfo
    • CaptchaInfo
    • PageInfo
    • SocialAccountInfo
    • ProxyInfo
    • SocialInfo
    • ActionInfo
    • CreateTaskPayload
    • CreateCookiePayload
    • CreateProxyPayload
    • CreateTaskJoinPayload
    • NatsAcceptedResponse
    • NatsRejectedResponse
    • NatsErrorResponse
    • TaskCompletedPayload
    • CookieUpdatePayload
    • ProxyCheckResultPayload
    • TaskJoinResultPayload
    • TaskJoinCheckResultPayload
    • PagingInfo
    • AppError
  1. Architecture

Database schema

Tài liệu Database Schema — Social Tool Worker#

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

1. Tổng quan Công nghệ#

Worker sử dụng MongoDB làm task queue nội bộ, quản lý schema thông qua Typegoose (TypeScript decorator cho Mongoose).
Thành phầnChi tiết
DatabaseMongoDB ≥ 7
ORMTypegoose + Mongoose
Model definitionssrc/nats/*/\*.model.ts
Kết nối DBsrc/config/database/mongodb.config.ts
Default DB namesocial-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.

2. Sơ đồ quan hệ tổng thể#




3. Luồng trạng thái chung#


4. Chi tiết các Collection#

4.1. Collection tasks#

Lưu trữ các tác vụ tương tác MXH (like, comment, share, post...) nhận từ API Server.
TrườngKiểuMô tả
_idstringMongoDB ObjectId (tự sinh)
task_idstringBắt buộc — ID task từ API Server
group_idstringNhóm task liên quan (index)
created_bynumberID người tạo
social_account_idnumberID tài khoản MXH thực thi
campaign_platform_idstringBắt buộc — ID cấu hình chiến dịch
action_namestringTên hành động: like, share, comment...
typeTaskTypeNền tảng MXH (1=Facebook, 2=Instagram, 3=Twitter, 4=TikTok, 5=Google, 6=Telegram)
actionTaskActionLoại hành động (xem bảng enum bên dưới)
urlstringURL bài viết/trang mục tiêu
contentstringNội dung (cho comment/reply/post)
targetGroupstringURL group mục tiêu
statusTaskStatus0: PENDING, 1: PROCESSING, 2: COMPLETED, 3: IN_QUEUE
result_statusTaskResultStatusKết quả chi tiết (xem enum bên dưới)
result_errorstringThông báo lỗi nếu thất bại
error_codenumberMã lỗi
execution_timenumberThời gian thực thi (giây)
retry_cookie_countnumberSố lần retry cookie (mặc định: 0)
webhook_urlstringURL callback gửi kết quả
call_webhook_countnumberSố lần đã gọi webhook
skip_postnumberSố bài viết bỏ qua
keywordsstringTừ khóa tìm kiếm
result_urlstringURL kết quả sau khi thực thi
result_page_namestringTên trang kết quả
avatar_urlstringURL avatar (dùng cho đổi avatar)
social_accountSocialAccountBắt buộc — Embedded: thông tin tài khoản
proxyProxyInfoEmbedded: thông tin proxy
comment_infoCommentInfoEmbedded: cấu hình comment
reply_infoReplyInfoEmbedded: cấu hình reply
share_infoShareInfoEmbedded: cấu hình share
postPostInfoEmbedded: cấu hình post (ảnh)
captcha_infoCaptchaInfoEmbedded: cấu hình captcha
page_infoPageInfoEmbedded: thông tin trang mục tiêu
createdAtDateThời gian tạo (auto)
updatedAtDateThời gian cập nhật (auto)
TaskAction Enum:
Giá trịTênMô tả
1COMMENTBình luận bài viết
2REPLYTrả lời comment
3POSTĐăng bài mới
4SHAREChia sẻ bài viết
5LIKEThả cảm xúc
6CRAWThu thập dữ liệu
7REPORTBáo cáo bài viết
8RENAME_USERĐổi tên
9CHANGEAVATARĐổi ảnh đại diện
10CHECK_NOTIFICATIONKiểm tra thông báo
11CONFIRM_FRIEND_REQUESTXác nhận kết bạn
12CHECK_NEW_FEEDKiểm tra bảng tin
13COMMENT_ADSComment quảng cáo
14REPLY_ADSReply quảng cáo
TaskResultStatus Enum:
Giá trịTênMô tả
1SUCCESSThành công
0UNKNOWNChưa xác định
-1ERRORLỗi chung
-2NOT_FOUNDURL không tìm thấy
-3CAPTCHAGặp captcha
-4MAX_RETRYĐã hết lượt retry
-5COOKIE_ERRORCookie lỗi/hết hạn

4.2. Collection cookies#

Lưu trữ yêu cầu login/lấy cookie cho tài khoản MXH.
TrườngKiểuMô tả
_idstringMongoDB ObjectId
cookie_idnumberBắt buộc — ID cookie trên Admin
created_bynumberID người tạo
typeCookieTypeNền tảng MXH (1–6, giống TaskType)
device_sizeDeviceSizeBắt buộc — {width, height, ratio}
user_agentstringBắt buộc — User-Agent trình duyệt
valuestringCookie string hiện tại
usernamestringTên đăng nhập tài khoản
passwordstringMật khẩu tài khoản
secret_keystringMã 2FA
namestringTên hiển thị
profileAvatarstringURL avatar thu thập được
profileUrlstringURL profile thu thập được
profileEmailstringEmail thu thập được
profileGendernumberGiới tính thu thập được
profilePhonestringSĐT thu thập được
statusCookieProcessingRaw0: PENDING, 1: PROCESSING, 2: COMPLETED
raw_statusCookieStatusRawKết quả: 0: OPEN, 1: DONE, 2: FAIL
error_messagestringThông báo lỗi
error_codenumberMã lỗi
ip_publicstringIP public khi login
proxyProxyEmbedded: {id, ip, port, username, password}
captcha_infoCaptchaInfoEmbedded: cấu hình captcha
call_webhook_countnumberSố lần đã gọi webhook

4.3. Collection proxies#

Lưu trữ yêu cầu kiểm tra proxy (check alive, detect IP).
TrườngKiểuMô tả
_idstringMongoDB ObjectId
proxy_idnumberID proxy trên Admin
created_bynumberID người tạo
statusStatus0: PENDING, 1: PROCESSING, 2: COMPLETED, 3: FAILED
status_sendSendAdminStatusĐã gửi Admin: 0: NOTSEND, 1: SENDED
status_codenumberHTTP status code khi check
responsestringResponse body khi check
is_errorbooleanCó lỗi không
ipstringBắt buộc — Địa chỉ IP proxy
portnumberBắt buộc — Port proxy
usernamestringBắt buộc — Tên xác thực
passwordstringBắt buộc — Mật khẩu xác thực
ip_publicstringBắt buộc — IP public khai báo
detected_ipstringIP public thực tế phát hiện được
rotate_urlstringURL để rotate IP
rotate_timenumberThời gian auto rotate (giây)
disable_auto_rotatebooleanTắt auto rotate
auth_tokenstringToken xác thực
regionstringVùng địa lý
webhook_urlstringURL callback
call_webhook_countnumberSố lần đã gọi webhook
task_idnumberID task liên quan
campaign_platform_idnumberID chiến dịch liên quan
retry_countnumberSố lần đã retry (mặc định: 0)
max_retriesnumberSố retry tối đa (mặc định: 3)
error_messagestringThông báo lỗi
batch_idstringID batch debug
checked_atDateThời điểm kiểm tra

4.4. Collection task_joins#

Lưu trữ yêu cầu join group / kiểm tra trạng thái join.
TrườngKiểuMô tả
_idstringMongoDB ObjectId
idnumberBắt buộc — ID task join từ API
created_bynumberID người tạo
campaign_join_idnumberBắt buộc — ID chiến dịch join
typeTaskJoinTypeNền tảng MXH (1–6)
campaign_join_typeCampaignJoinTypejoin (tham gia) hoặc check (kiểm tra)
page_urlstringBắt buộc — URL group cần join
status_toolTaskJoinStatus0: PENDING, 1: PROCESSING, 2: COMPLETED
result_statusTaskJoinResultStatusKết quả (giống TaskResultStatus)
result_errorstringThông báo lỗi
error_codenumberMã lỗi
execution_timenumberThời gian thực thi (giây)
group_typeGroupTypepublic hoặc private
check_join_statusJoinGroupStatusunknown, pending, approve, reject
accountSocialAccountBắt buộc — Embedded: {id, name, value, user_agent, device_size}
proxyProxyEmbedded: {ip, port, username, password}
ai_infoAIInfoEmbedded: cấu hình AI
captcha_infoCaptchaInfoEmbedded: cấu hình captcha

4.5. Collection cookie_proxy#

Lư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ườngKiểuMô tả
_idstringMongoDB ObjectId
idnumberID tham chiếu
cookie_idnumberBắt buộc — FK cookie
social_typeCookieTypeNền tảng MXH (1–4)
ip_publicstringBắt buộc — IP public
auth_tokenstringToken xác thực
ipstringBắt buộc — IP proxy
portnumberBắt buộc — Port proxy
usernamestringBắt buộc — Tên xác thực
passwordstringBắt buộc — Mật khẩu
webhook_urlstringURL callback
call_webhook_countnumberSố lần gọi webhook
last_usedDateLần sử dụng gần nhất
Indexes:
{ 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ất

5. Embedded Documents#

Các document nhúng được dùng chung giữa nhiều collection:

SocialAccount (trong tasks)#

{
  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
}

AIInfo (dùng cho comment/reply/share)#

{
  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ả
}

CommentInfo#

{
  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
}

ReplyInfo#

{
  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)
}

CaptchaInfo#

{
  api_key: string      // API key dịch vụ captcha
  service_name: string // Tên dịch vụ (vd: omo)
}

PageInfo#

{
  id?: number          // ID trang
  page_url?: string    // URL trang
  type?: string        // Loại: page, group, profile, post
  description?: string // Mô tả
}

6. Lưu ý quan trọng#

⚠️ 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ắcChi tiết
🗑️ Task tạm thờiTask được xóa khỏi MongoDB sau khi xử lý xong (nếu DEBUG_DELETE_TASK_AFTER_PROCESSING=true)
♻️ Reset khi khởi độngMọi task PROCESSING sẽ được reset về PENDING khi Worker khởi động lại
📊 Indextasks.status và tasks.group_id có index, cookie_proxy có compound index
🔗 Không có Foreign KeyMongoDB không hỗ trợ FK — tính toàn vẹn dữ liệu phụ thuộc vào application logic
📥 Embedded DocumentDữ liệu tài khoản, proxy được nhúng trực tiếp vào task (denormalized) để tránh lookup
⏰ Timestamps tự độngcreatedAt và updatedAt do Typegoose/Mongoose tự quản lý

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.
Modified at 2026-03-26 03:32:17
Previous
Tổng quan TOOL
Next
System architecture
Built with