Tài liệu Database Schema

Tài liệu kỹ thuật – Phiên bản 1.0
Mô tả cấu trúc cơ sở dữ liệu của hệ thống Social Tool

1. Tổng quan Công nghệ

Hệ thống sử dụng cơ sở dữ liệu MySQL, quản lý schema thông qua Drizzle ORM.

Thành phần	Chi tiết
Database	MySQL
ORM	Drizzle ORM
Model definitions	`src/api/models/*.model.ts`
Schema entry point	`src/api/models/schema.ts`
Config	`drizzle.config.ts`

2. Sơ đồ quan hệ tổng thể (ERD)

3. Luồng thực thi tác vụ

4. Chi tiết các bảng

4.1. Bảng `users`

Quản lý thông tin đăng nhập và phân quyền cho toàn bộ nguời dùng hệ thống.

Cột	Kiểu dữ liệu	Mô tả
`id`	int	Primary Key, tự động tăng
`name`	varchar(255)	Tên hiển thị
`email`	varchar(255)	Email đăng nhập (Unique)
`password`	varchar(255)	Mật khẩu đã mã hóa
`phone`	varchar(20)	Số điện thoại liên lạc
`status`	boolean	Trạng thái hoạt động (`true`: active)
`permis_ids`	varchar	Danh sách ID nhóm quyền, phân cách bằng dấu phẩy
`secret_key`	varchar	Khóa bí mật dùng cho bảo mật / API
`created_at`	timestamp	Thời điểm tạo
`updated_at`	timestamp	Thời điểm cập nhật cuối
`created_by`	int	ID người tạo
`updated_by`	int	ID người cập nhật cuối

4.2. Bảng `social_accounts`

Lưu trữ thông tin các tài khoản mạng xã hội.

Cột	Kiểu dữ liệu	Mô tả
`id`	int	Primary Key, tự động tăng
`social_id`	int	FK → bảng `socials`
`group_id`	int	FK → bảng `social_account_groups`
`name`	varchar	Tên gợi nhớ của tài khoản
`username`	varchar	Tên đăng nhập trên nền tảng
`password`	varchar	Mật khẩu nền tảng
`old_password`	varchar	Mật khẩu cũ (lưu khi có thay đổi)
`secret_key`	text	Mã 2FA hoặc khóa bảo mật bổ sung
`value`	text	Cookie hoặc Access Token
`status`	varchar	Trạng thái: `new`, `pending`, `active`, `failure`...
`avatar`	varchar	URL ảnh đại diện
`email`	varchar	Email khôi phục / đăng ký tài khoản
`phone`	varchar	Số điện thoại gắn với tài khoản
`linkProfile`	varchar	URL profile cá nhân
`gender`	int	Giới tính (`1`: Nam, `2`: Nữ)
`user_agent`	varchar	User Agent trình duyệt được giả lập
`device_size`	varchar	Kích thước màn hình thiết bị giả lập
`note`	text	Ghi chú thêm
`active`	boolean	Tài khoản có khả dụng không
`version`	int	Phiên bản dữ liệu (hỗ trợ migration)
`created_at`	timestamp	Thời điểm thêm vào hệ thống
`updated_at`	timestamp	Thời điểm cập nhật cuối
`deleted_at`	datetime	Thời điểm xóa mềm (Soft Delete)

4.3. Bảng `social_pages`

Quản lý các Fanpage, Group, Profile của các trang mạng xã hội.

Cột	Kiểu dữ liệu	Mô tả
`id`	int	Primary Key
`social_id`	int	FK nền tảng
`group_id`	int	FK nhóm trang
`page_url`	varchar	URL đầy đủ của trang / group
`title`	varchar	Tên hoặc tiêu đề trang
`type`	enum	Loại trang: `page`, `group`, `profile`, `post`...
`group_type`	enum	Chế độ group: `public`, `private`
`parent_id`	int	ID trang cha (nếu có cấu trúc phân cấp)
`description`	text	Mô tả về mục tiêu
`keyword`	varchar	Từ khóa phân loại
`active`	boolean	Trạng thái hoạt động
`created_at`	datetime	Thời gian tạo
`updated_at`	datetime	Thời gian cập nhật
`deleted_at`	datetime	Thời gian xóa mềm (Soft Delete)

4.4. Bảng `campaigns`

Lưu thông tin cơ bản của một chiến dịch.

Cột	Kiểu dữ liệu	Mô tả
`id`	bigint	Primary Key
`social_id`	bigint	FK nền tảng (nullable nếu là job hệ thống)
`name`	varchar	Tên chiến dịch
`type`	varchar	Loại: `join_group`, `login`, `changename`...
`description`	text	Mô tả mục tiêu chiến dịch
`rules_json`	json	Cấu hình chung toàn chiến dịch
`active`	boolean	Chiến dịch đang hoạt động hay không
`start_date`	timestamp	Ngày bắt đầu dự kiến
`end_date`	timestamp	Ngày kết thúc dự kiến
`created_by`	bigint	ID người tạo
`updated_by`	int	ID người cập nhật cuối
`created_at`	timestamp	Thời gian tạo
`updated_at`	timestamp	Thời gian cập nhật
`deleted_at`	timestamp	Thời gian xóa mềm (Soft Delete)

4.5. Bảng `campaign_platforms`

Quản lý chiến dịch và các cấu hình của các task sẽ thực hiện.

Cột	Kiểu dữ liệu	Mô tả
`id`	bigint	Primary Key
`action_id`	bigint	FK hành động (Like, Comment, Share...)
`campaign_id`	bigint	FK chiến dịch gốc
`parent_id`	bigint	FK platform cha (nếu có)
`name`	varchar	Tên cấu hình platform
`code`	varchar	Mã định danh duy nhất
`status`	varchar	Trạng thái: `pending`, `running`, `completed`, `cancelled`...
`description`	text	Mô tả chi tiết
`rules_json`	json	Logic chạy (delay, số bài mỗi tài khoản...)
`metadata_json`	json	Dữ liệu thực thi (danh sách link bài, nội dung...)
`active`	boolean	Có kích hoạt không
`is_tasks_created`	boolean	Đã sinh task nhỏ lẻ chưa
`last_task_creation_at`	timestamp	Lần cuối sinh task
`start_date`	timestamp	Thời gian bắt đầu thực thi
`end_date`	timestamp	Thời gian kết thúc thực thi
`cancelled_at`	timestamp	Thời điểm hủy (nếu có)
`all_tasks_finished_at`	timestamp	Thời điểm hoàn tất toàn bộ task
`created_at`	timestamp	Thời gian tạo
`updated_at`	timestamp	Thời gian cập nhật
`deleted_at`	timestamp	Thời gian xóa mềm (Soft Delete)

4.6. Bảng `campaign_platform_tasks`

Quản lý các task cần thực hiện của chiến dịch

Cột	Kiểu dữ liệu	Mô tả
`id`	bigint	Primary Key
`campaign_platform_id`	bigint	FK platform cấu hình
`social_account_id`	bigint	FK tài khoản thực hiện
`page_id`	bigint	FK trang mục tiêu (nếu có)
`group_id`	varchar	Nhóm các task liên quan
`code`	varchar	Mã task duy nhất
`status`	enum	`pending` / `running` / `completed` / `failed` / `cancelled`
`priority`	bigint	Độ ưu tiên thực thi
`metadata`	json	Dữ liệu riêng của task (link bài, nội dung comment...)
`start_date`	timestamp	Thời điểm bắt đầu chạy
`completed_at`	timestamp	Thời điểm hoàn thành
`created_at`	timestamp	Thời gian tạo
`updated_at`	timestamp	Thời gian cập nhật
`deleted_at`	timestamp	Thời gian xóa mềm (Soft Delete)

4.7. Bảng `proxies`

Quản lý proxy dùng để bảo vệ tài khoản khỏi checkpoint.

Cột	Kiểu dữ liệu	Mô tả
`id`	int	Primary Key
`ip`	varchar	Địa chỉ IPv4 / IPv6
`port`	int	Port kết nối
`username`	varchar	Tên xác thực proxy
`password`	varchar	Mật khẩu xác thực proxy
`rotate_url`	varchar	URL để thực hiện rotate IP
`rotate_time`	int	Khoảng thời gian tự động rotate (giây)
`group_id`	int	FK nhóm proxy
`proxy_package_id`	int	FK gói proxy
`proxy_price`	int	Giá thuê proxy
`note`	varchar	Ghi chú
`is_active`	boolean	Proxy có khả dụng không
`expired_at`	timestamp	Ngày hết hạn
`region`	varchar	Khu vực địa lý của IP
`disable_auto_rotate`	boolean	Tắt tính năng tự động xoay IP
`ipBlockedByFb`	int	Đánh dấu IP bị Facebook chặn
`created_at`	timestamp	Thời gian thêm proxy
`updated_at`	timestamp	Thời gian cập nhật cuối
`deleted_at`	timestamp	Thời gian xóa mềm (Soft Delete)

5. Quy trình cập nhật Schema

Các bước thực hiện:

Chỉnh sửa Model — Mở file .model.ts tương ứng trong src/api/models/ và thực hiện thay đổi.

Tạo Migration — Chạy lệnh để Drizzle quét code và sinh file SQL:

Áp dụng Migration — Thực thi các file SQL mới vào database:

6. Nguyên tắc & Lưu ý quan trọng

⚠️ Cần tuân thủ các quy ước dưới đây để đảm bảo tính nhất quán và an toàn dữ liệu.

Quy tắc	Chi tiết
🗑️ Soft Delete	Luôn dùng `deleted_at` thay vì xóa cứng dữ liệu quan trọng
🕐 Timestamp tự động	Các cột `created_at`, `updated_at` được Drizzle/SQL tự quản lý
📋 Đăng ký Schema	Khi thêm bảng mới, bắt buộc khai báo trong `src/api/models/schema.ts` để Drizzle nhận dạng quan hệ
🔗 Foreign Key	Luôn sử dụng FK để đảm bảo tính toàn vẹn dữ liệu giữa các bảng

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.

Database schema

Tài liệu Database Schema#

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

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

3. Luồng thực thi tác vụ#

4. Chi tiết các bảng#

4.1. Bảng users#

4.2. Bảng social_accounts#

4.3. Bảng social_pages#

4.4. Bảng campaigns#

4.5. Bảng campaign_platforms#

4.6. Bảng campaign_platform_tasks#

4.7. Bảng proxies#

5. Quy trình cập nhật Schema#

6. Nguyên tắc & Lưu ý quan trọng#