pos-system/services/chat-service-net/docs/vi

Chat Service

Dịch vụ Chat thời gian thực 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 thời gian thực trong hệ thống microservices với:

• 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 - Phòng chat, ánh xạ user across devices
• 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. 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ả real-time connections
Multi-Transport	Tự động chọn WebSockets → SSE → Long Polling
Streaming	Hỗ trợ IAsyncEnumerable cho streaming AI responses

// Gửi tin nhắn đến nhóm
await Clients.Group(roomId).SendAsync("ReceiveMessage", message);

// Streaming AI response
public async IAsyncEnumerable<string> StreamAIResponse(string prompt)
{
    await foreach (var chunk in _aiService.StreamAsync(prompt))
        yield return chunk;
}

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

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

// Cấu hình Redis Backplane
builder.Services.AddSignalR()
    .AddStackExchangeRedis(connectionString, options => {
        options.Configuration.ChannelPrefix = RedisChannel.Literal("ChatService");
    });

C. Quản Lý Người Dùng & Nhóm

Tính năng	Mô tả
Groups	Gom kết nối theo phòng chat
User Mapping	Ánh xạ ConnectionId → UserId qua Claims
Persistent State	Lưu trạng thái nhóm vào database

// Custom User ID Provider
public class CustomUserIdProvider : IUserIdProvider
{
    public string? GetUserId(HubConnectionContext connection)
        => connection.User?.FindFirst(ClaimTypes.NameIdentifier)?.Value;
}

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

E. Giao Thức MessagePack

// Server configuration
builder.Services.AddSignalR()
    .AddMessagePackProtocol();

// Client configuration (JavaScript)
const connection = new signalR.HubConnectionBuilder()
    .withUrl("/chatHub")
    .withHubProtocol(new signalR.protocols.msgpack.MessagePackHubProtocol())
    .build();

F. Khả Năng Phục Hồi

Tính năng	Mô tả
Auto Reconnect	Client tự động kết nối lại
Stateful Reconnect	Buffer dữ liệu khi gián đoạn (.NET 8+)

// Server: Bật Stateful Reconnect
builder.Services.AddSignalR(options => {
    options.EnableDetailedErrors = true;
    options.StatefulReconnectBufferSize = 32 * 1024; // 32KB buffer
});

// Client: Cấu hình reconnect
connection.WithAutomaticReconnect([0, 2000, 10000, 30000]);

API Endpoints

HTTP REST APIs

Method	Endpoint	Mô tả
GET	/api/v1/rooms	Lấy danh sách phòng chat
POST	/api/v1/rooms	Tạo phòng chat mới
GET	/api/v1/rooms/{id}/messages	Lấy lịch sử tin nhắn
POST	/api/v1/rooms/{id}/participants	Thêm thành viên

SignalR Hub Methods

Method	Direction	Mô tả
SendMessage	Client → Server	Gửi tin nhắn
JoinRoom	Client → Server	Tham gia phòng
LeaveRoom	Client → Server	Rời phòng
ReceiveMessage	Server → Client	Nhận tin nhắn
UserJoined	Server → Client	Thông báo user mới

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
• MessagePack Protocol

Giấy Phép

Độc quyền - GoodGo Platform