Cơ chế phân quyền & mô hình hoạt động

Gateway là cổng duy nhất đứng giữa công cụ AI của nhân viên và 22 MCP của Viva. Mọi lệnh đều đi qua đây để xác thực, kiểm quyền, tính hạn mức và ghi nhận — MCP phía sau không bao giờ lộ token gốc ra ngoài.

🧭 1. Mô hình hoạt động

Nhân viên chỉ cầm API key vmk_live_… của riêng mình. Token MCP phía sau nằm mã hoá trong Gateway, theo từng workspace.
Mỗi MCP có một URL riêng: https://mcp.hoiai.com.vn/<mcp>/mcp. Cùng một key dùng cho mọi MCP được cấp.
Quản trị viên có thêm Admin MCP (/mcp-http/) để quản trị bằng câu lệnh tự nhiên qua AI.

🏢 2. Phân cấp: Workspace → Gói → Thành viên → Nhóm

Workspace

Một tổ chức: viva (nội bộ) hoặc khách thuê. Dữ liệu, credential, báo cáo cách ly hoàn toàn giữa các workspace.

Gói (subscription)

Gói nào bật MCP nấy, kèm trần quyền và hạn mức tháng. Nội bộ dùng gói internal-full. Hết hạn → 3 ngày ân hạn (chỉ đọc) → tạm ngưng.

Thành viên

username duy nhất, không đổi — là khoá đo lường. Đăng nhập bằng Gmail đã đăng ký.

Nhóm quyền

Ma trận MCP × mức quyền × tài nguyên × hạn mức ngày. Một người nhiều nhóm → quyền là hợp các nhóm, hạn mức lấy nhóm cao nhất.

🧮 3. Công thức quyền hiệu lực

quyền = MCP trong gói ∩ (∪ quyền các nhóm ∪ cấp lẻ còn hạn) − chặn lẻ

Kiểm tra (theo thứ tự)	Không đạt thì
Workspace còn hoạt động, gói còn hạn	SUBSCRIPTION_INACTIVE — từ chối toàn bộ
Tài khoản đang active	ACCOUNT_BLOCKED — từ chối toàn bộ
MCP thuộc gói, đang bật, nằm trong quyền	FORBIDDEN
Tool đã được duyệt, mức quyền ≤ được cấp, đúng tài nguyên, tool nhạy cảm cần nhóm cho phép	Tool bị ẩn khỏi danh sách / FORBIDDEN
Hạn mức: người/ngày · tool/ngày · workspace/tháng	QUOTA_USER / TOOL / WORKSPACE
Thao tác tiền / nguy hiểm: đã chạy thử + được duyệt	DRY_RUN_REQUIRED → PENDING_APPROVAL

AI chỉ nhìn thấy những tool người dùng được phép — không phải bị từ chối sau khi gọi. Lỗi trả bằng tiếng Việt kèm hướng xử lý.

🔐 4. Bốn mức quyền của tool

Mức	Ý nghĩa	Ví dụ	Khi chạy
R Đọc	Xem số liệu, báo cáo	gsc_top_queries, sales_report	Chạy ngay
W Ghi	Tạo / sửa, sửa lại được	update_post, create_post	Chạy thử trước (mặc định), xác nhận rồi chạy thật
M Tiền	Ngân sách, giá thầu, giá bán	update_campaign_budget	Bắt buộc chạy thử + quản trị viên duyệt
D Nguy hiểm	Xoá, ghi đè, gửi ra ngoài	delete_product, send_zns	Bắt buộc chạy thử + quản trị viên duyệt

Tool mới phát hiện từ MCP phía sau vào hàng chờ duyệt — chưa ai thấy cho tới khi quản trị viên phân loại mức quyền. Tool nhạy cảm (công nợ, xuất danh sách khách) chỉ hiện khi nhóm khai báo rõ.

👥 5. Nhóm quyền mặc định (workspace viva)

Nhóm	MCP và mức quyền	Đơn vị/ngày
SEO	itop W · gsc R · ga4 R · dataforseo R · gbp W · google_editor W	400
Video	youtube W · tiktok_content W · vbee W · meta R · google_editor W	300
MXH	meta W · zalo_oa W · tiktok_content W · linkedin W · itop W (chỉ site viva) · google_editor W	300
Sale	kiot R · ladipage R (CRM lw_*) · tiktok_shop R · tiki R · itop R	150
Marketing	ga4 R · gsc R · meta R · ladipage W · itop R · kiot R · zalo_oa R · google_editor W	300
Ads	google_ads M · facebook_ads M · zalo_ads M · gmc W · gtm W · stape R · ga4 W · ladipage W	400
Ecommerce	tiktok_shop M · tiki W · gmc W · itop W	300
Kế toán	kiot R + tool nhạy cảm (debt_aging, cashflow_report)	200
Admin workspace	Toàn bộ MCP trong gói, R W M D + quản lý thành viên + Admin MCP	1.000

Quản trị viên sửa nhóm trên Portal → Quản trị → Nhóm quyền; mỗi lần lưu tăng phiên bản, có lịch sử.

🗝️ 6. Cấp quyền & thu hồi

Vòng đời tài khoản

Quản trị viên tạo → invited, gửi email mời (hạn 72 giờ).
Người dùng đăng nhập lần đầu → active.
Khoá (bắt buộc lý do) → blocked: thu hồi mọi phiên + API key, từ chối mọi MCP ngay lập tức.
Mở khoá: key cũ không khôi phục — đăng nhập lại, tạo key mới.

Cấp lẻ / chặn lẻ

Cấp lẻ: thêm 1 MCP hoặc tool cho 1 người, bắt buộc lý do + ngày hết hạn ≤ 90 ngày; hết hạn tự mất.
Chặn lẻ: chặn 1 MCP / nhóm tool (vd delete_*) với 1 người — thắng quyền nhóm.
Tài nguyên: giới hạn trong nhóm theo site / tài khoản / page (vd MXH chỉ sửa bài noithatviva.vn).

API key

Tối đa 3 key / người, hạn 90 ngày, mỗi thiết bị một key.
Chỉ lưu dạng băm; thu hồi từng key bất cứ lúc nào ở tab API key.
n8n / tích hợp dùng key của tài khoản dịch vụ, không dùng key cá nhân.

Duyệt thao tác tiền / nguy hiểm

AI chạy thử (dry-run) → xem TRƯỚC → SAU.
Gọi chạy thật → Gateway tạo phiếu chờ duyệt.
Quản trị viên duyệt ở tab Quản trị → Duyệt.
Gọi lại đúng tham số → chạy; phiếu dùng 1 lần, hết hạn sau 7 ngày.

📈 7. Hạn mức & đo lường

Hạn mức: mỗi tool có số đơn vị; người dùng có hạn mức ngày theo nhóm (đặt lại 00:00), mỗi tool tối đa 500 lượt/ngày, workspace khách có hạn mức tháng theo gói.
Ghi nhận mỗi lần gọi: thời điểm, username, nhóm, công cụ AI, MCP, tool, mức quyền, kết quả, độ trễ, đơn vị. Không lưu prompt, tham số thô hay dữ liệu khách.
Báo cáo tối ưu MCP: lượt dùng theo MCP/tool, tool không ai dùng 30 ngày, tỉ lệ lỗi, độ trễ p50/p95, tool bị từ chối nhiều, phân bố công cụ AI.
Chỉ số chuyển đổi số (0–100/tháng): đều đặn 30% · độ rộng 20% · độ sâu 15% · thực thi 20% · chất lượng 15%. Chống làm đẹp: lượt trùng trong 5 phút tính 1, mỗi tool ≤ 50 lượt/ngày, chỉ đọc thì tối đa 60 điểm.
Nhân viên xem điểm của mình (tab Lịch sử); quản trị viên xem cả workspace.

Chỉ số đo mức ứng dụng công cụ, không đo hiệu quả công việc; khi đánh giá nhân sự cần kết hợp KPI nghiệp vụ của từng bộ phận.

🧑‍💼 8. Ai làm gì trên Portal

Vai trò	Làm được
Nhân viên	Xem MCP được cấp + URL, tạo/thu hồi API key, làm theo hướng dẫn kết nối, xem lịch sử & điểm của mình, đóng góp prompt mẫu.
Admin workspace	Tạo/khoá/mở tài khoản, gán nhóm, sửa nhóm quyền, cấp/chặn lẻ, duyệt phiếu tiền/nguy hiểm, xem báo cáo workspace, dùng Admin MCP.
Super admin (owner)	Thêm: registry MCP (URL, credential, đồng bộ & duyệt tool, bật/tắt toàn hệ thống), tạo workspace khách, đổi gói.