Chuyển tới nội dung chính

API Chat

Tiền tố /api/v1/chat. Controller: chat.controller.ts. Collection: chat-sessions, chat-messages, chat-tool-actions, ai-usage-logs. Logic chat, guardrail và quota: 03-modules/ai-chat.md (Phase 3).

ThrottlerGuard ở cấp class. Các route gửi tin (có @Throttle) bị giới hạn 15 lần mỗi phút (CHAT_ROUTE_RPM_LIMIT, chat.constant.ts); đây là giới hạn theo thời gian ngắn, tách biệt với hạn mức theo ngày (NORMAL USER 30, HR 100, SUPER ADMIN không giới hạn, xem chat-quota-policies).

Hai kiểu phản hồi​

KiểuRoutePhản hồi
Một lần (JSON)POST /chat/message, POST /chat/sessions/:sessionId/messagesJSON bọc { statusCode, message, data }
Stream (SSE)POST /chat/message/stream, POST /chat/sessions/:sessionId/messages/streamtext/event-stream, không bọc. Xem realtime

Với route stream, lỗi hết hạn mức đến qua sự kiện error (HTTP vẫn 200). Với route JSON, hết hạn mức ném ChatQuotaExceededException (kế thừa TooManyRequestsException, thông điệp "Daily chatbot quota exceeded. Please try again after the quota resets."); mã HTTP là 429 (too-many-requests.exception.ts).

Danh sách route​

RouteAuthMô tả
POST /api/v1/chat/messageĐăng nhập (mọi vai trò)Gửi một tin tới trợ lý AI và nhận câu trả lời trọn vẹn (không stream)
GET /api/v1/chat/historyĐăng nhập (mọi vai trò)Lịch sử hội thoại có phân trang (limit tối đa 100)
DELETE /api/v1/chat/clearĐăng nhập (mọi vai trò)Xóa cuộc trò chuyện hiện tại
POST /api/v1/chat/sessionsĐăng nhập (mọi vai trò)Tạo phiên chat mới
GET /api/v1/chat/sessionsĐăng nhập (mọi vai trò)Liệt kê các phiên chat của tôi
GET /api/v1/chat/sessions/:sessionId/messagesĐăng nhập (mọi vai trò)Xem tin nhắn của một phiên
POST /api/v1/chat/sessions/:sessionId/messagesĐăng nhập (mọi vai trò)Gửi tin vào một phiên và nhận câu trả lời trọn vẹn
DELETE /api/v1/chat/sessions/:sessionIdĐăng nhập (mọi vai trò)Xóa một phiên chat
GET /api/v1/chat/admin/usage/summaryĐăng nhập, vai trò: SUPER ADMINTổng hợp mức dùng AI (quản trị viên)
GET /api/v1/chat/admin/usage/timeseriesĐăng nhập, vai trò: SUPER ADMINChuỗi thời gian mức dùng AI (quản trị viên)
GET /api/v1/chat/admin/usage/top-usersĐăng nhập, vai trò: SUPER ADMINNgười dùng dùng AI nhiều nhất (quản trị viên)
POST /api/v1/chat/tool-actions/:actionId/confirmĐăng nhập (mọi vai trò)Xác nhận một hành động do trợ lý đề xuất (ví dụ lưu tin)
DELETE /api/v1/chat/tool-actions/:actionIdĐăng nhập (mọi vai trò)Hủy một hành động đang chờ
POST /api/v1/chat/message/streamĐăng nhập (mọi vai trò)Gửi một tin và nhận câu trả lời dạng stream SSE
POST /api/v1/chat/sessions/:sessionId/messages/streamĐăng nhập (mọi vai trò)Gửi tin vào một phiên và nhận câu trả lời dạng stream SSE

Ràng buộc đầu vào​

  • message: bắt buộc, 1 đến 1000 ký tự.
  • jobId: tùy chọn, phải là MongoId; dùng làm ngữ cảnh cho câu hỏi về một tin.
  • history: page, limit (mặc định 50, tối đa 100).

Phạm vi dữ liệu​

Phiên và tin nhắn gắn với userId của người gọi. Quản trị viên mới gọi được nhóm admin/usage/*. Việc kiểm tra người gọi chỉ truy cập phiên của chính mình ở các route sessions/:sessionId/... nằm trong ChatService, chưa được đối chiếu ở đây: Chưa xác minh.

Known Limitation​

  • DELETE /chat/clear và DELETE /chat/sessions/:sessionId đều "xóa" cuộc trò chuyện; khác biệt giữa xóa mềm và xóa thật chưa được kiểm tra. Trạng thái: Chưa xác minh.
  • Hành động công cụ (tool-actions) hết hạn lười (lúc truy cập), xem chat-tool-actions.

Chi tiết từng route​

POST /api/v1/chat/message​

Gửi một tin tới trợ lý AI và nhận câu trả lời trọn vẹn (không stream)

  • Auth: Đăng nhập (mọi vai trò)
  • Handler: sendMessage trong chat.controller.ts
  • Mã thành công: 201, message = "Message sent successfully"
  • Giới hạn tốc độ: CHAT_ROUTE_RPM_LIMIT lần mỗi 1 phút

Body: SendMessageDto (send-message.dto.ts)

FieldKiểuBắt buộcValidationVí dụ
messagestringCóIsString, IsNotEmpty, MinLength(1), MaxLength(1000)'Tôi nên học skill gì để trở thành Senior Backend Engineer?'
jobIdstringKhôngIsMongoId'507f1f77bcf86cd799439011'

Phản hồi theo Swagger

MãMô tả
201Message sent successfully
400Invalid message format
429Too many requests - rate limit exceeded

GET /api/v1/chat/history​

Lịch sử hội thoại có phân trang (limit tối đa 100)

  • Auth: Đăng nhập (mọi vai trò)
  • Handler: getHistory trong chat.controller.ts
  • Mã thành công: 200, message = "History retrieved successfully"

Query

TênBắt buộcMô tảVí dụ
pageKhôngPage number (default: 1)
limitKhôngMessages per page (default: 50, max: 100)
(toàn bộ query string)—DTO ConversationHistoryQueryDto

Query: ConversationHistoryQueryDto (conversation-history.dto.ts)

FieldKiểuBắt buộcValidationVí dụ
pagenumberKhôngIsInt, Min(1)1
limitnumberKhôngIsInt, Min(1), Max(100)50

Phản hồi theo Swagger

MãMô tả
200History retrieved successfully

DELETE /api/v1/chat/clear​

Xóa cuộc trò chuyện hiện tại

  • Auth: Đăng nhập (mọi vai trò)
  • Handler: clearConversation trong chat.controller.ts
  • Mã thành công: 200, message = "Conversation cleared successfully"

Phản hồi theo Swagger

MãMô tả
200Conversation cleared successfully

POST /api/v1/chat/sessions​

Tạo phiên chat mới

  • Auth: Đăng nhập (mọi vai trò)
  • Handler: createSession trong chat.controller.ts
  • Mã thành công: 201, message = "Chat session created successfully"

Body: CreateChatSessionDto (create-chat-session.dto.ts)

FieldKiểuBắt buộcValidationVí dụ
typeEChatSessionTypeKhôngIsEnum(EChatSessionType)—
titlestringKhôngIsString, MaxLength(120)'Backend career advice'

Phản hồi theo Swagger

MãMô tả
201Chat session created successfully

GET /api/v1/chat/sessions​

Liệt kê các phiên chat của tôi

  • Auth: Đăng nhập (mọi vai trò)
  • Handler: listSessions trong chat.controller.ts
  • Mã thành công: 200, message = "Chat sessions retrieved successfully"

Phản hồi theo Swagger

MãMô tả
200Chat sessions retrieved successfully

GET /api/v1/chat/sessions/:sessionId/messages​

Xem tin nhắn của một phiên

  • Auth: Đăng nhập (mọi vai trò)
  • Handler: getSessionMessages trong chat.controller.ts
  • Mã thành công: 200, message = "Session messages retrieved successfully"

Path params

TênKiểuMô tả
sessionIdstring

Query

TênBắt buộcMô tảVí dụ
pageKhôngPage number (default: 1)
limitKhôngMessages per page (default: 50, max: 100)
(toàn bộ query string)—DTO ConversationHistoryQueryDto

Query: ConversationHistoryQueryDto (conversation-history.dto.ts)

FieldKiểuBắt buộcValidationVí dụ
pagenumberKhôngIsInt, Min(1)1
limitnumberKhôngIsInt, Min(1), Max(100)50

Phản hồi theo Swagger

MãMô tả
200Session messages retrieved successfully

POST /api/v1/chat/sessions/:sessionId/messages​

Gửi tin vào một phiên và nhận câu trả lời trọn vẹn

  • Auth: Đăng nhập (mọi vai trò)
  • Handler: sendSessionMessage trong chat.controller.ts
  • Mã thành công: 201, message = "Message sent successfully"
  • Giới hạn tốc độ: CHAT_ROUTE_RPM_LIMIT lần mỗi 1 phút

Path params

TênKiểuMô tả
sessionIdstring

Body: SendMessageDto (send-message.dto.ts)

FieldKiểuBắt buộcValidationVí dụ
messagestringCóIsString, IsNotEmpty, MinLength(1), MaxLength(1000)'Tôi nên học skill gì để trở thành Senior Backend Engineer?'
jobIdstringKhôngIsMongoId'507f1f77bcf86cd799439011'

Phản hồi theo Swagger

MãMô tả
201Message sent successfully

DELETE /api/v1/chat/sessions/:sessionId​

Xóa một phiên chat

  • Auth: Đăng nhập (mọi vai trò)
  • Handler: clearSession trong chat.controller.ts
  • Mã thành công: 200, message = "Chat session cleared successfully"

Path params

TênKiểuMô tả
sessionIdstring

Phản hồi theo Swagger

MãMô tả
200Chat session cleared successfully

GET /api/v1/chat/admin/usage/summary​

Tổng hợp mức dùng AI (quản trị viên)

  • Auth: Đăng nhập, vai trò: SUPER ADMIN
  • Handler: getUsageSummary trong chat.controller.ts
  • Mã thành công: 200, message = "AI usage summary retrieved successfully"

Query

TênBắt buộcMô tảVí dụ
(toàn bộ query string)—DTO AiUsageQueryDto

Query: AiUsageQueryDto (ai-usage-query.dto.ts)

FieldKiểuBắt buộcValidationVí dụ
startDatestringKhôngIsDateString'2026-05-01T00:00:00.000Z'
endDatestringKhôngIsDateString'2026-05-14T23:59:59.999Z'
providerAIProviderKhôngIsIn—
modelstringKhôngIsString'llama-3.3-70b-versatile'
intentEChatIntentKhôngIsEnum(EChatIntent)—

Phản hồi theo Swagger

MãMô tả
200AI usage summary retrieved successfully

GET /api/v1/chat/admin/usage/timeseries​

Chuỗi thời gian mức dùng AI (quản trị viên)

  • Auth: Đăng nhập, vai trò: SUPER ADMIN
  • Handler: getUsageTimeseries trong chat.controller.ts
  • Mã thành công: 200, message = "AI usage timeseries retrieved successfully"

Query

TênBắt buộcMô tảVí dụ
(toàn bộ query string)—DTO AiUsageTimeseriesQueryDto

Query: AiUsageTimeseriesQueryDto (ai-usage-query.dto.ts)

Kế thừa AiUsageQueryDto.

FieldKiểuBắt buộcValidationVí dụ
daysnumberKhôngIsInt, Min(1), Max(90)30

Phản hồi theo Swagger

MãMô tả
200AI usage timeseries retrieved successfully

GET /api/v1/chat/admin/usage/top-users​

Người dùng dùng AI nhiều nhất (quản trị viên)

  • Auth: Đăng nhập, vai trò: SUPER ADMIN
  • Handler: getTopUsers trong chat.controller.ts
  • Mã thành công: 200, message = "Top AI users retrieved successfully"

Query

TênBắt buộcMô tảVí dụ
(toàn bộ query string)—DTO AiUsageTopUsersQueryDto

Query: AiUsageTopUsersQueryDto (ai-usage-query.dto.ts)

Kế thừa AiUsageQueryDto.

FieldKiểuBắt buộcValidationVí dụ
limitnumberKhôngIsInt, Min(1), Max(50)10

Phản hồi theo Swagger

MãMô tả
200Top AI users retrieved successfully

POST /api/v1/chat/tool-actions/:actionId/confirm​

Xác nhận một hành động do trợ lý đề xuất (ví dụ lưu tin)

  • Auth: Đăng nhập (mọi vai trò)
  • Handler: confirmToolAction trong chat.controller.ts
  • Mã thành công: 201, message = "Chat tool action confirmed successfully"

Path params

TênKiểuMô tả
actionIdstring

Phản hồi theo Swagger

MãMô tả
201Chat tool action confirmed successfully

DELETE /api/v1/chat/tool-actions/:actionId​

Hủy một hành động đang chờ

  • Auth: Đăng nhập (mọi vai trò)
  • Handler: cancelToolAction trong chat.controller.ts
  • Mã thành công: 200, message = "Chat tool action canceled successfully"

Path params

TênKiểuMô tả
actionIdstring

Phản hồi theo Swagger

MãMô tả
200Chat tool action canceled successfully

POST /api/v1/chat/message/stream​

Gửi một tin và nhận câu trả lời dạng stream SSE

  • Auth: Đăng nhập (mọi vai trò)
  • Handler: streamMessage trong chat.controller.ts
  • Mã thành công: 201 (phản hồi không bọc { statusCode, message, data }, do @SkipTransform)
  • Giới hạn tốc độ: CHAT_ROUTE_RPM_LIMIT lần mỗi 1 phút

Body: SendMessageDto (send-message.dto.ts)

FieldKiểuBắt buộcValidationVí dụ
messagestringCóIsString, IsNotEmpty, MinLength(1), MaxLength(1000)'Tôi nên học skill gì để trở thành Senior Backend Engineer?'
jobIdstringKhôngIsMongoId'507f1f77bcf86cd799439011'

Phản hồi theo Swagger

MãMô tả
200SSE-compatible stream

POST /api/v1/chat/sessions/:sessionId/messages/stream​

Gửi tin vào một phiên và nhận câu trả lời dạng stream SSE

  • Auth: Đăng nhập (mọi vai trò)
  • Handler: streamSessionMessage trong chat.controller.ts
  • Mã thành công: 201 (phản hồi không bọc { statusCode, message, data }, do @SkipTransform)
  • Giới hạn tốc độ: CHAT_ROUTE_RPM_LIMIT lần mỗi 1 phút

Path params

TênKiểuMô tả
sessionIdstring

Body: SendMessageDto (send-message.dto.ts)

FieldKiểuBắt buộcValidationVí dụ
messagestringCóIsString, IsNotEmpty, MinLength(1), MaxLength(1000)'Tôi nên học skill gì để trở thành Senior Backend Engineer?'
jobIdstringKhôngIsMongoId'507f1f77bcf86cd799439011'

Phản hồi theo Swagger

MãMô tả
200SSE-compatible stream