pos-system/services/chat-service-net/docs/vi/README.md

Chat Service

Dịch vụ Chat thời gian thực với Mã hóa Đầu-cuối (E2EE) cho nền tảng GoodGo, xây dựng trên ASP.NET Core SignalR.

Tổng Quan

Chat Service cung cấp khả năng giao tiếp bảo mật thời gian thực trong hệ thống microservices với:

• Mã hóa Đầu-cuối - Giao thức trao đổi khóa X3DH với AES-256-GCM
• Giao tiếp thời gian thực - ASP.NET Core SignalR với WebSockets/SSE/Long Polling
• Khả năng mở rộng - Redis Backplane hoặc Azure SignalR Service
• Quản lý người dùng & nhóm - Hội thoại, ánh xạ user đa thiết bị
• Tích hợp AI - Chatbot thông minh với streaming response
• Hiệu năng cao - Giao thức MessagePack
• Khả năng phục hồi - Auto reconnect, Stateful Reconnect

Yêu Cầu

Yêu cầu	Phiên bản
.NET SDK	10.0.101+
Docker	24.0+
PostgreSQL	16+
Redis	7+

Bắt Đầu Nhanh

1. Cấu Hình Môi Trường

# Sao chép template môi trường
cp .env.example .env

# Chỉnh sửa cấu hình
nano .env

2. Chạy với Docker

# Khởi động tất cả services
docker-compose up -d

# Xem logs
docker-compose logs -f chatservice-api

3. Chạy Local

dotnet restore
dotnet build
dotnet run --project src/ChatService.API

Tính Năng Chi Tiết

A. Mã Hóa Đầu-cuối (E2EE)

Tính năng	Mô tả
Giao thức X3DH	Extended Triple Diffie-Hellman cho trao đổi khóa
Identity Keys	Cặp khóa định danh Curve25519 dài hạn
Signed Pre-Keys	Xoay vòng định kỳ (mỗi 30 ngày)
One-Time Pre-Keys	Forward secrecy cho tin nhắn đầu tiên
AES-256-GCM	Mã hóa đối xứng cho tin nhắn

// Server CHỈ lưu nội dung đã mã hóa - không thể giải mã mà không có private key của client
public class Message
{
    public string EncryptedContent { get; }  // Mã hóa Base64
    public string Nonce { get; }              // IV cho AES-GCM
    public string? AuthTag { get; }           // Authentication tag
}

B. Giao Tiếp Thời Gian Thực

Tính năng	Mô tả
SignalR Hub	Hub trung tâm xử lý tất cả kết nối realtime
Multi-Transport	Tự động chọn WebSockets → SSE → Long Polling
Streaming	Hỗ trợ IAsyncEnumerable cho streaming AI responses

C. Khả Năng Mở Rộng

Giải pháp	Use Case
Redis Backplane	On-premise, triển khai multi-instance
Azure SignalR Service	Azure cloud, serverless scenarios
Sticky Sessions	Fallback khi không dùng Azure SignalR

D. Tích Hợp AI

Tính năng	Mô tả
AI Assistant	Chatbot trong nhóm (trigger: @gpt)
Streaming Response	Đẩy từng phần câu trả lời realtime
Context History	Lưu lịch sử chat cho context AI

API Endpoints

Conversations API

Method	Endpoint	Mô tả
POST	/api/conversations	Tạo hội thoại mới
GET	/api/conversations	Lấy danh sách hội thoại của user
GET	/api/conversations/{id}	Lấy hội thoại cụ thể

Messages API

Method	Endpoint	Mô tả
POST	/api/messages	Gửi tin nhắn đã mã hóa
GET	/api/messages/conversation/{id}	Lấy tin nhắn trong hội thoại
POST	/api/messages/read	Đánh dấu tin nhắn đã đọc

Keys API (E2EE)

Method	Endpoint	Mô tả
POST	/api/keys/register	Đăng ký E2EE key bundle
POST	/api/keys/rotate	Xoay vòng signed pre-key
POST	/api/keys/prekeys	Upload one-time pre-keys
GET	/api/keys/bundle/{userId}	Lấy key bundle của user
GET	/api/keys/my-bundle	Lấy trạng thái key bundle của mình

SignalR Hub Methods

Method	Hướng	Mô tả
JoinRoom	Client → Server	Tham gia phòng hội thoại
LeaveRoom	Client → Server	Rời phòng hội thoại
SendMessage	Client → Server	Gửi tin nhắn đã mã hóa
SendTypingIndicator	Client → Server	Gửi trạng thái đang gõ
MarkMessageRead	Client → Server	Đánh dấu tin nhắn đã đọc
StreamAIResponse	Client → Server	Yêu cầu AI streaming response
ReceiveMessage	Server → Client	Nhận tin nhắn mới
UserJoined	Server → Client	Thông báo user tham gia
UserLeft	Server → Client	Thông báo user rời đi
TypingIndicator	Server → Client	Chỉ báo đang gõ
MessageDelivered	Server → Client	Trạng thái tin nhắn đã gửi
MessageRead	Server → Client	Trạng thái tin nhắn đã đọc

Health Endpoints

Endpoint	Mục đích
/health	Trạng thái đầy đủ
/health/live	Liveness probe
/health/ready	Readiness probe

Cấu Hình

Biến Môi Trường

Biến	Mô tả	Mặc định
ASPNETCORE_ENVIRONMENT	Môi trường	Development
DATABASE_URL	PostgreSQL connection	-
REDIS_URL	Redis connection	-
AZURE_SIGNALR_CONNECTION	Azure SignalR (optional)	-
OPENAI_API_KEY	OpenAI API key (optional)	-

appsettings.json

{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Database=chatservice;Username=postgres;Password=postgres",
    "Redis": "localhost:6379"
  },
  "SignalR": {
    "EnableMessagePack": true,
    "StatefulReconnectBufferSize": 32768
  },
  "AI": {
    "Provider": "OpenAI",
    "Model": "gpt-4",
    "MaxHistoryMessages": 20
  }
}

Triển Khai

Docker Build

docker build -t chatservice:latest .
docker run -p 5000:8080 --env-file .env chatservice:latest

Kubernetes

Xem ARCHITECTURE.md để biết chi tiết cấu hình Kubernetes với Sticky Sessions.

Tài Liệu Tham Khảo

• ASP.NET Core SignalR
• Redis Backplane
• Azure SignalR Service
• Giao thức X3DH

Giấy Phép

Độc quyền - GoodGo Platform