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

Kịch bản Demo — LLM Credit Quotas (Rate Limit)

1. Overview​

1.1 Bài toán​

Hiện tại chi phí gọi LLM (chat với agent) trong FleziGalaxy chưa được kiểm soát theo tổ chức / người dùng. Một org hoặc một member có thể sử dụng LLM không giới hạn trong tháng, dẫn tới:

  • Không dự đoán được chi phí vận hành — không có giới hạn chi tiêu (budget) theo tháng cho từng khách hàng/tổ chức.
  • Không có cơ chế tự động gán hạn mức khi thêm member mới vào tổ chức — mỗi lần thêm member vào org, org admin phải nhớ và vào cấu hình quota thủ công.

1.2 Mục tiêu chức năng​

Chức năng LLM Credit Quotas giải quyết bài toán trên bằng một mô hình phân bổ 2 tầng theo tháng UTC hiện tại:

System Admin  →  gán trần (Limit) + default credit cho ORG
                        │
                        ▼
   Org Admin   →  chia Limit của org đó cho từng MEMBER (quota cá nhân)
                        │
                        ▼
      Member   →  chat, mỗi câu trừ dần credit theo cost thực tế (1 credit = $0.01)

Cùng với đó là:

  • Một màn hình read-only để member tự theo dõi hạn mức của mình (modal Usage credit).
  • Cơ chế chặn gửi tin khi hết/không có quota, kèm mã lỗi rõ ràng (error_code / blocked_reason), hiển thị hiển thị đa ngôn ngữ EN/JA.
  • Cơ chế cảnh báo theo ngưỡng (80/85/90/95/100%) để user biết trước khi bị khóa.
  • Cơ chế auto-allocate default credit khi invite/tạo/sửa user, giảm thao tác thủ công cho admin.

System Admin luôn bypass toàn bộ cơ chế này (không bị kiểm tra hạn mức, không thấy modal Usage credit) — vì vai trò của họ là người cấp phát ngân sách, không phải người tiêu thụ.

2. Demo này sẽ trình diễn gì​

Demo tập trung vào toàn bộ vòng đời của một credit budget, đi từ vai System Admin xuống Org Admin rồi tới trải nghiệm của một member thường khi chat — để người xem thấy được luồng đầu-cuối (end-to-end), không chỉ từng màn hình rời rạc.

Các feature sẽ demo​

#FeatureVai trò dùngMô tả ngắn
1Set / Edit / Toggle / Remove org budgetSystem AdminCấp trần credit tháng cho một tổ chức, kèm default_credit gợi ý khi invite member
2View members (read-only)System AdminXem nhanh member trong org đã được chia bao nhiêu, không sửa được
3Edit Default CreditOrg AdminĐổi gợi ý auto-allocate mà không đụng tới Limit tổng của org
4Assign quotas (hàng loạt)Org AdminChọn nhiều member chưa có quota, gán cùng một limit một lần
5Set / Edit / Toggle / Remove member quotaOrg AdminQuản lý quota cho từng member riêng lẻ
6Modal Usage creditMọi user (trừ System Admin)Tự xem hạn mức, % đã dùng, trạng thái của chính mình
7Chat gate — khóa ô nhập & lỗi khi gửiMọi user (trừ System Admin)Trải nghiệm bị chặn khi hết quota / chưa có quota / quota bị tắt / org budget bị tắt
8Cảnh báo ngưỡng 80→100%Mọi user (trừ System Admin)Toast + notification chuông khi dùng gần hết hạn mức, không phải chờ tới lúc bị chặn
9Auto-allocate khi invite user mớiOrg Admin / System Admin (người invite)Member mới tự động nhận default_credit nếu org còn đủ ngân sách, không cần thao tác thêm

3. Kế hoạch thực hiện (Plan các bước demo)​

Giả định môi trường demo đã có sẵn: 1 tài khoản System Admin, 1 tài khoản Org Admin thuộc org "Demo Org" (org này chưa có credit budget), và ít nhất 2–3 tài khoản member thường trong org đó (chưa có quota).

Bước 0 — Chuẩn bị (trước khi demo, không quay/chiếu)​

  1. Đăng nhập sẵn 3 tab/trình duyệt (hoặc 3 profile) tương ứng: System Admin, Org Admin, Member.
  2. Xác nhận "Demo Org" chưa có credit budget (để thấy được empty state ORG_BUDGET_NOT_SET ở bước Org Admin).
  3. Chuẩn bị sẵn 1 member "member_no_quota_demorl@fpt.com" chưa được gán quota, dùng để demo case bị chặn.

Bước 1 — System Admin: thiết lập ngân sách cho tổ chức (UC-A1 → UC-A5)​

  1. Vào Governance → Credit Budgets (màn tổ chức).
  2. Chỉ ra Demo Org đang Not set (chưa có budget).
  3. Set budget: nhập Limit = 1000, Default credit = 50 → lưu, chỉ ra toast thành công "Organization budget set." và trạng thái mặc định là bật.
  4. Edit: tăng Limit lên 1200, giải thích ràng buộc Limit không được thấp hơn used/allocated (không demo lỗi, chỉ nói qua).
  5. View members: mở modal xem danh sách member trong Demo Org (đang trống vì Org Admin chưa chia) — chỉ ra đây là read-only.
  6. Toggle disable org để minh họa hệ quả — nói trước sẽ bật lại ngay để không ảnh hưởng phần demo sau.

Bước 2 — Org Admin: chia ngân sách cho member (UC-B1 → UC-B6)​

  1. Chuyển sang tab Org Admin → Governance → Credit Budgets (màn member).
  2. Chỉ ra thẻ tóm tắt: Org limit / Org used / Allocated / Remaining đồng bộ với những gì System Admin vừa cấu hình.
  3. Edit Default Credit: đổi từ 50 → 100, lưu, chỉ ra đây chỉ đổi gợi ý auto-allocate, không đổi Limit org.
  4. Assign quotas (hàng loạt): chọn 2 member chưa có quota, gán Limit = 150/người → chỉ ra Remaining org giảm tương ứng.
  5. Set quota cho 1 member còn lại (member_no_quota@demo) → chủ động bỏ qua bước này, để dành member này minh họa case "chưa có quota" ở Bước 4.
  6. Edit quota của 1 member vừa gán (tăng/giảm nhẹ) → chỉ ra validate Limit ≥ used và Limit ≤ Remaining + limit hiện tại.

Bước 3 — Member: tự xem hạn mức (UC-C1)​

  1. Chuyển sang tab của member đã được gán quota ở Bước 2.
  2. Mở menu avatar → Usage credit → chỉ ra: kỳ hiện tại, used/limit, %, thanh tiến độ, dòng "remaining credits", badge trạng thái Available.
  3. Đổi ngôn ngữ UI sang 日本語 ngay tại đây để chứng minh hiển thị đa ngôn ngữ hoạt động, sau đó đổi lại English.

Bước 4 — Chat: trải nghiệm bị chặn & cảnh báo (UC-D1 → UC-D4)​

  1. Case "chưa có quota": đăng nhập member_no_quota@demo → vào chat → chỉ ra ô nhập bị khóa ngay, banner đỏ "Messaging is paused for your account." với lý do No credit quota has been assigned to you.
  2. Case "còn hạn mức, dùng bình thường": quay lại member đã có quota ở Bước 2 → gửi 1–2 câu chat bình thường → chỉ ra không bị chặn.
  3. Case "cảnh báo ngưỡng": nếu dữ liệu demo cho phép set sẵn used gần ngưỡng (ví dụ 80%), gửi thêm 1 câu để kích hoạt toast "Credit usage at 80%" + chuông thông báo — chỉ ra icon chuông ở sidebar lắc kèm glow đỏ ngay khi thông báo tới, không cần mở popover mới thấy.
  4. Case "vượt hạn mức / soft-admit": dùng member đã set sẵn used gần chạm limit, gửi câu cuối khiến used ≥ limit (câu này vẫn thành công — soft-admit) → gửi tiếp câu kế → bị chặn 429 USER_QUOTA_EXCEEDED, ô nhập khóa lại, badge Usage credit đổi thành Quota exceeded.
  5. Case "org budget bị tắt" (tùy thời gian còn lại): System Admin tắt Demo Org → mọi member trong org bị chặn ngay với ORG_QUOTA_DISABLED, kể cả member đang có quota bình thường → bật lại ngay sau khi minh họa. Mở lại modal Usage credit của member này để chỉ ra used/limit/% vẫn hiện số thật (không trống), chỉ badge đổi sang lý do org bị tắt.

Bước 5 — Auto-allocate khi invite user mới (UC-E1)​

  1. Chuyển sang tab Org Admin (hoặc System Admin nếu người invite là System Admin) → invite 1 user mới vào Demo Org (org đã có budget, default_credit = 100, còn đủ remaining).
  2. Sau khi tạo xong, mở lại màn member (Org Admin) → chỉ ra user mới đã tự có quota = 100 ngay mà không cần thao tác Set quota thủ công.
  3. (Tùy chọn) Minh họa case "không đủ ngân sách": invite thêm 1 user khi Remaining còn ít hơn default_credit → user vẫn được tạo thành công (soft-fail), nhưng không có quota, và người invite nhận notification chuông báo thiếu ngân sách — chỉ ra rằng user mới không bị ảnh hưởng, chỉ requester được báo.

Bước 6 — Wrap-up​

  1. Tóm tắt lại luồng: System Admin cấp ngân sách org → Org Admin chia cho member → Member dùng chat với cảnh báo/khóa theo hạn mức → tự động cấp quota khi invite.
  2. Nhấn mạnh 3 giá trị chính đã chứng minh: kiểm soát chi phí theo tháng, phân bổ công bằng trong org, trải nghiệm rõ ràng, hiển thị đa ngôn ngữ cho end-user khi bị chặn hoặc gần hết hạn mức.