Cài đặt Hệ thống

Quick Reference

• Who: Owner / Admin
• Where: Menu trái → Cài đặt (/settings)
• Time: ~5 phút setup AI, ~3 phút per channel
• Prerequisites: Role Owner hoặc Admin

Prerequisites

• [ ] Đã đăng nhập với role Owner hoặc Admin
• [ ] Có API key từ AI provider (nếu setup AI connector)
• [ ] Có Telegram bot token / Lark webhook URL (nếu setup channels)

Phần 1: Cấu hình AI Connector

Step 1: Mở trang Cài đặt

1. Click Cài đặt trên sidebar
2. Tab AI Connectors hiện mặc định

Step 2: Chọn AI Provider

Hệ thống hỗ trợ 5 provider:

Provider	API Key Format	URL lấy key	Ghi chú
OpenRouter	sk-or-...	openrouter.ai/keys	Khuyến nghị — truy cập nhiều model
OpenAI	sk-...	platform.openai.com/api-keys	GPT models
Anthropic	sk-ant-...	console.anthropic.com	Claude models
Google	AIza...	aistudio.google.com/apikey	Gemini models
Custom	Tùy	—	OpenAI-compatible endpoint

Source: (src/app/core/models/ai-providers.ts:1-222)

Step 3: Chọn Model

Model khuyến nghị:

Model	Provider	Chi phí	Chất lượng	Tốc độ
Claude Sonnet 4.6	OpenRouter/Anthropic	Trung bình	Cao	Nhanh
DeepSeek V3.2	OpenRouter	Thấp	Cao	Nhanh
Claude Opus 4.6	OpenRouter/Anthropic	Cao	Rất cao	Trung bình
OpenRouter Free	OpenRouter	Miễn phí	Trung bình	Trung bình

Step 4: Nhập API Key & Test

1. Nhập API Key vào ô
2. Click Test Connection
3. Hệ thống kiểm tra:
   • API key hợp lệ
   • Model accessible
   • Đo latency (ms)
4. Nếu thành công → Click Lưu

WARNING

API key được lưu ở backend dạng masked (sk-or-***...***). Frontend không bao giờ hiện full key sau khi lưu.

Step 5: Quản lý Connectors

Hành động	Cách làm
Thêm mới	Click "Thêm Connector" → wizard
Xoá	Click icon xoá trên connector card
Active	Chỉ 1 connector active tại một thời điểm

---

Phần 2: Cấu hình Notification Channels

Step 1: Chuyển Tab Channels

1. Trong trang Cài đặt, click tab Notification Channels

Step 2: Thêm Channel mới

Click Thêm Channel → chọn loại:

Telegram:

Field	Required	Mô tả	Ví dụ
Bot Token	Yes	Token từ @BotFather	1234567890:AAF...
Chat ID	Yes	ID chat/group nhận tin	123456789

Email:

Field	Required	Mô tả	Ví dụ
Email	Auto	Tự động theo account	user@company.com

Lark (Feishu):

Field	Required	Mô tả	Ví dụ
Webhook URL	Yes	URL webhook từ Lark bot	https://open.feishu.cn/...

Step 3: Verify Channel

1. Sau khi thêm, click Test
2. Backend gửi message test qua channel
3. Kiểm tra nhận được message
4. Nếu thành công → is_verified = true

TIP

Telegram: Đảm bảo bot đã được add vào group/chat trước khi test. Lark: Đảm bảo webhook chưa hết hạn.

Step 4: Quản lý Channels

Hành động	Cách làm
Sửa config	Click edit → cập nhật token/webhook
Test lại	Click Test → gửi message kiểm tra
Xoá	Click xoá (sẽ mất subscriptions liên quan)

Expected Results

• AI Connector test thành công trong 1-3 giây
• Channel test gửi message ngay lập tức
• Sau setup, AI Chat và Subscriptions hoạt động bình thường

Troubleshooting

AI Test Connection thất bại

Cause: API key sai, hết hạn, hoặc model không accessible.

Solution:

1. Kiểm tra API key đúng format (xem bảng trên)
2. Kiểm tra tài khoản còn credit
3. Thử model khác (VD: free model)

Telegram test không nhận message

Cause: Bot chưa được add vào chat, hoặc chat_id sai.

Solution:

1. Add bot vào group: tìm bot bằng username → Add to group
2. Lấy chat_id: gửi message trong group → gọi https://api.telegram.org/bot{token}/getUpdates → tìm chat.id
3. Cập nhật chat_id trong config → test lại

Lark webhook trả lỗi

Cause: Webhook URL hết hạn hoặc bị disable.

Solution:

1. Vào Lark Admin → Bot Management → tạo webhook mới
2. Cập nhật URL trong config → test lại

Related

• AI Chat — Sử dụng AI sau khi setup connector
• Thông báo — Tạo subscriptions sau khi setup channels
• Dashboards — Schedule reports cần channels
• API: POST /api/v1/ai/connectors/test — Xem API