Hệ thống Soạn thảo Văn bản Cộng tác theo Thời gian thực
Một nền tảng chỉnh sửa tài liệu đa người dùng hiệu năng cao (tương tự Google Docs),
giải quyết bài toán xung đột dữ liệu với thuật toán Operational Transformation (OT).
- 🌟 Tổng Quan Dự Án
- ✨ Tính Năng Nổi Bật
- 🏗️ Kiến Trúc & Thiết Kế Hệ Thống
- 💻 Công Nghệ Sử Dụng
- 🚀 Hướng Dẫn Cài Đặt (Getting Started)
- 📂 Cấu Trúc Dự Án
- 🧪 Kiểm Thử (Testing)
- 🤝 Đóng Góp (Contributing)
- 👥 Người Đóng Góp (Contributors)
Collaborative Systems là một hệ thống biên tập tài liệu cộng tác cho phép nhiều người dùng cùng chỉnh sửa một văn bản tại cùng một thời điểm.
Dự án áp dụng thuật toán Centralized Operational Transformation (OT) và Vector Clocks nhằm duy trì tính nhất quán tuyệt đối của tài liệu, bất chấp độ trễ mạng hay thao tác đồng thời. Bằng việc tách rời REST API/WebSockets Server và OT Worker qua hệ thống Message Broker (RabbitMQ), hệ thống đạt được tính ổn định và khả năng mở rộng ngang (Horizontal Scaling) vô cùng mạnh mẽ.
- ⚡ Đồng bộ thời gian thực siêu thấp (Ultra-low Latency): Thay đổi văn bản được đồng bộ tới tất cả client với tốc độ tính bằng mili-giây qua WebSockets.
- 👥 Quản lý Hiện diện (Presence) & Con trỏ độc lập (Live Cursors): Hiển thị danh sách người dùng Online/Offline và theo dõi chuyển động con trỏ chuột của từng cá nhân kèm màu sắc nhận diện riêng biệt.
- 🔐 Hệ thống Phân quyền Linh hoạt (RBAC): Chủ sở hữu (Owner) có thể cấp quyền
Viewer(Chỉ xem) hoặcEditor(Chỉnh sửa). Mọi thay đổi quyền được cập nhật ngay lập tức (Real-time). - 🎨 Giao diện Cao cấp (Modern UI/UX): Trải nghiệm người dùng tuyệt vời với phong cách thiết kế Glassmorphism, hỗ trợ giao diện Sáng/Tối (Dark/Light mode) dựa trên Tailwind CSS v4 & Shadcn/UI.
- 🛡️ Bảo mật JWT & Protected Routes: Đảm bảo quyền riêng tư và xác thực bảo mật cho mọi tài liệu cá nhân.
Hệ thống được thiết kế theo hướng sự kiện (Event-Driven Architecture). Mọi thao tác gõ (Operations) đều được định tuyến qua cơ chế Consistent Hashing theo ID tài liệu (Document ID) vào RabbitMQ để đảm bảo việc xử lý luồng thao tác luôn diễn ra tuần tự nghiêm ngặt (Strict Ordering), tránh tranh chấp đa luồng.
graph TD
Client1[Frontend Client 1] <-->|WebSockets| API[FastAPI API Server]
Client2[Frontend Client 2] <-->|WebSockets| API
API -->|1. Push Operations| MQ[RabbitMQ Event Queue]
MQ -->|2. Consistent Hashing Order| Worker[OT Worker Process]
Worker -->|3. Conflict Resolution| OT[Thuật toán OT & Vector Clock]
Worker -->|4. Update State| Redis[(Redis OT History Cache)]
Worker -->|5. Persistence| DB[(MongoDB Permanent Store)]
Worker -->|6. Broadcast Synced Op| Exchange[RabbitMQ Fanout Exchange]
Exchange -->|7. Distribute| API
- Operational Transformation (OT 3x3 Matrix): Xử lý ma trận biến đổi toán học khi các thao tác
Insert,Delete,Retaindiễn ra cùng lúc trên một index. - Tie-breaker: Cơ chế phân xử logic khi hai người dùng cùng thao tác đè lên một vị trí, đảm bảo sự hội tụ (Convergence) của tài liệu trên tất cả các Client.
- Framework Core: Next.js 16 (App Router), React 19
- Ngôn ngữ: TypeScript
- Styling & UI: Tailwind CSS v4.0, Shadcn/UI, Lucide React
- Networking: Axios (với JWT interceptor), Native WebSockets
- Framework Core: FastAPI (Python 3.11+), Uvicorn (ASGI)
- Message Broker: RabbitMQ (
aio-pika) - Database: MongoDB (
motorasync driver) - Caching: Redis (
redis.asyncio) - Testing: Pytest
- Docker & Docker Compose (Bắt buộc cho Infrastructure)
- Node.js (v18+)
- Python (v3.11+)
Dự án cung cấp sẵn tệp Docker Compose để chạy MongoDB, Redis, RabbitMQ và các giao diện quản trị trực quan.
cd backend
docker-compose up -d🎛️ Bảng Điều Khiển Hạ Tầng (Management Dashboards):
- 🐰 RabbitMQ Management: http://localhost:15672 (Tài khoản:
nam.dev/ Mật khẩu:Nam12345@)- 🍃 Mongo Express (MongoDB UI): http://localhost:8085 (Tài khoản:
admin/ Mật khẩu:admin)- 🔴 Redis Commander (Redis UI): http://localhost:8086
Mở 2 cửa sổ Terminal mới tại thư mục backend/.
Terminal 1: Chạy API Server
python -m venv venv
# Windows: .\venv\Scripts\activate | macOS/Linux: source venv/bin/activate
pip install -r requirements.txt
# Tạo file .env từ .env.example
# Khởi chạy server API
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reloadTerminal 2: Chạy OT Worker
# Kích hoạt môi trường ảo (venv) trước
# Windows: .\venv\Scripts\activate | macOS/Linux: source venv/bin/activate
python -m app.worker.consumer💡 Mẹo (Scale-out): Bạn có thể chạy song song nhiều OT Worker để chia tải (Horizontal Scaling) bằng cách điều chỉnh cấu hình
RABBITMQ_NUM_QUEUESvà biến môi trườngWORKER_QUEUES. Xem hướng dẫn chi tiết tại backend/readme.md.
Mở Terminal mới tại thư mục frontend/:
npm install
# Khởi tạo biến môi trường (.env)
echo "NEXT_PUBLIC_API_BASE_URL=http://localhost:8000/api" > .env
# Chạy ứng dụng Frontend
npm run dev🎉 Trải nghiệm ứng dụng tại: http://localhost:4000
Kiến trúc Monorepo được chia ranh giới rõ ràng:
Collaborative-Systems/
├── backend/ # Logic xử lý thuật toán & API Backend
│ ├── app/api/ # Routes cho REST API & WebSockets
│ ├── app/core/ # Thuật toán cốt lõi (OT, Vector Clock)
│ ├── app/models/ # Pydantic Schemas (Data Validation)
│ ├── app/worker/ # RabbitMQ Consumer (Xử lý tác vụ ngầm)
│ ├── infra/ # Repository Pattern giao tiếp DB, Cache, MQ
│ └── tests/ # Unit Tests (Pytest)
│
├── benchmarks/ # Các kịch bản kiểm thử tải (Load Testing) và đo lường hiệu năng
│ └── locustfile.py # Kịch bản kiểm thử với Locust cho OT Worker và API
|
└── frontend/ # Giao diện người dùng
├── app/ # Next.js App Router (Pages, Layouts)
├── components/ui/ # Shadcn Primitives (Button, Dialog, ...)
├── components/ # Core components (Editor, Sidebar, ...)
├── hooks/ # React Hooks tùy chỉnh
└── lib/ # Utilities, API Axios instances, Auth Context
Đảm bảo độ chính xác tuyệt đối của bộ biến đổi OT (Index Shifting) bằng cách chạy Unit Tests trên Backend:
cd backend
python -m pytest tests/Dự án luôn hoan nghênh sự đóng góp từ cộng đồng. Quy trình đóng góp tiêu chuẩn:
- Fork dự án này về tài khoản của bạn.
- Tạo Branch cho tính năng/bản vá:
git checkout -b feature/AmazingFeature - Commit thay đổi của bạn:
git commit -m 'Add some AmazingFeature' - Push lên Branch:
git push origin feature/AmazingFeature - Mở một Pull Request trên Repository gốc và mô tả chi tiết thay đổi của bạn.
(Vui lòng tuân thủ các quy chuẩn định dạng code: PEP8 cho Python và ESLint/Prettier cho Next.js).
Dự án này được phát triển, cống hiến và bảo trì bởi sự phối hợp của các thành viên tài năng:
Bạn muốn đóng góp? Hãy xem mục Đóng Góp!
Được xây dựng với ❤️ bởi cộng đồng lập trình viên Việt Nam.