Sheet 10 · AI Engine / Gateway · Kỹ năng · Quan hệ với ERP và dữ liệu

AI Engine & Gateway — kiến trúc tổng quan

Trang này trả lời một câu hỏi: AI nằm ở đâu trong hệ thống, và nó chạm tới dữ liệu bằng đường nào. Câu trả lời ngắn: AI không nằm trong ERP. Nó ở một tiến trình khác, trên một máy khác, dưới một unix user khác — và muốn đọc hay ghi dữ liệu thì phải đi qua đúng cùng một cửa API mà giao diện web đi, với đúng quyền của người đang nhắn nó.

Vì sao ranh giới này quan trọng đến thế. Sáng 03/09/2026 hệ thống từng có một ngoại lệ: ERP tự chạy claude -p / agy -p để sinh bản nháp Kỹ năng và Quy trình. Ngoại lệ đó bị gỡ ngay trong ngày, vì lời nhắc của người dùng là dữ liệu không tin được, mà tiến trình mô hình lại chạy dưới user erp — cùng máy với cơ sở dữ liệu của cả bốn khách hàng. Kiến trúc dưới đây là bản thay thế: AI gọi vào ERP, ERP không gọi ra AI.

1. Toàn cảnh — hai cửa vào, một hạt nhân

Hai cửa vào ERP: giao diện web và trợ lý AI Người dùng có hai cách tác động lên ERP: mở giao diện web, hoặc nhắn trợ lý AI trong workspace. Cả hai đều đi vào cùng một hạt nhân ERP; hạt nhân đó tra khoá API để biết trợ lý đang đại diện cho ai, rồi đọc ghi cơ sở dữ liệu riêng của từng tenant qua hai tầng lọc quyền. MỞ TRANG NHẮN TIN COOKIE X-AGENT-KEY 2 TẦNG LỌC TRA KHOÁ NGƯỜI Nhân sự CTC 9 tài khoản WEB Giao diện ERP Next.js · 30 route NGOÀI Trợ lý AI máy khác · user khác CORE ERP — sync-server :4114 · Node zero-dep Phân quyền · 2 tầng lọc Nguồn sự thật duy nhất DB SQLite / tenant 4 file · cách ly KHOÁ bot_api_keys 1 khoá = 1 người CHÚ GIẢI Điểm kiểm soát quyền Thành phần trong ERP Hệ thống ngoài Đường của trợ lý Đường của người dùng
Đọc sơ đồ: hai mũi tên vào hạt nhân ERP là hai cửa duy nhất. Cửa web mang cookie phiên; cửa trợ lý mang X-Agent-Key. Cả hai đều bị cùng một bộ phân quyền chặn, nên trợ lý không bao giờ mở được cánh cửa mà chính người dùng đó không có. Mũi tên từ ERP sang cơ sở dữ liệu luôn đi qua hai tầng lọc — không có đường tắt nào đọc thẳng file DB.

2. Bên trong AI Gateway — engine thuê bao và kỹ năng

AI Gateway, các engine thuê bao và đường kỹ năng AI Gateway nhận tin nhắn từ các kênh, chạy một engine thuê bao cho mỗi phiên trong workspace riêng của từng người. Workspace đó chứa khoá API và chỉ dẫn kỹ năng; agent dùng chúng để gọi bảng chín hành động của ERP. MẶC ĐỊNH CHỌN ĐƯỢC CHƯA CÀI CHẠY TRONG HTTP + KHOÁ GATEWAY AI Gateway Telegram · Zalo · web AGY antigravity gemini-3.8-flash-high CLAUDE Claude Agent SDK opus[1m] CODEX codex dự kiến, chưa cài WORKSPACE Workspace mỗi người .env → ERP_API_KEY skills/erp-platform API /api/agent/action 9 hành động allowlist không có lệnh xoá CHÚ GIẢI Engine đang chạy Dự kiến, chưa cài Điểm kiểm soát quyền Nơi giữ khoá và kỹ năng
Đọc sơ đồ: mỗi phiên hội thoại chạy đúng một engine, chọn theo cấu hình workspace (mặc định hiện tại là agy). Engine nào cũng vào ERP bằng cùng một cửa và cùng một khoá — đổi engine không đổi quyền. Ô codex vẽ nét gạch vì tại thời điểm dựng tài liệu nó chưa có trong PATH và chưa có trong cấu hình Gateway; khi cài xong thì nó nối vào đúng chỗ đó, không cần đổi gì phía ERP.

3. Quan hệ chi tiết — ai chạm được vào cái gì

Từ → ĐếnCách điRàng buộc
Trợ lý → ERPHTTPS + header X-Agent-KeyERP tra bot_api_keys ra scope_user_id rồi áp nguyên quyền người đó. Trợ lý không tự khai danh tính. Rate limit 120 lượt/phút/khoá, 300/phút/IP.
Trợ lý → Cơ sở dữ liệuKhông có đường nàoTrợ lý chạy trên máy khác, unix user khác. Chỉ dẫn kỹ năng cấm tường minh việc mở *.db, dùng sqlite3, hay đọc sync-server/data/ — kể cả khi người dùng yêu cầu, kể cả để "đối chiếu".
ERP → Trợ lý / GatewayKhông có đường nàoChiều này bị cấm theo nguyên tắc kiến trúc. ERP không gọi ra Gateway, không chạy CLI mô hình, không mở tiến trình con.
Kỹ năng → Trợ lýbot_api_keys.skill_idsKỹ năng chỉ có tác dụng với agent khi id của nó nằm trong skill_ids của chính khoá agent đang cầm. Đây là đường "phát hành cho trợ lý", đặt ở giao diện Kỹ năng.
Kỹ năng → Ngườishared_with / shared_editĐường độc lập hoàn toàn với đường trên: cho đồng nghiệp đọc (mức Xem) hoặc sửa (mức Sửa) trong giao diện ERP. Chia sẻ cho một người không làm trợ lý của họ biết kỹ năng, và ngược lại.
Trợ lý → Công việcHành động them · xong · trangthai · hanCần phân hệ tasks. Việc tạo ra tự giao cho chính người nhắn, mã theo quy tắc UKN-<số> khi chưa gắn khách.
Trợ lý → Kỹ năng / Quy trìnhtao_ky_nang · tao_quy_trinhChỉ TẠO MỚI, luôn là nháp (kỹ năng draft, quy trình tắt). Không sửa bản có sẵn, không xoá, không chia sẻ, không phát hành, không bật. Hạn 40 bản/người/24 giờ. Phân hệ kiểm bằng hasModule ở hai lớp.
Trợ lý → Tài chính, Hợp đồng, Thư…Chưa mởBảng hành động là allowlist, nên phân hệ nào chưa có hành động thì trợ lý không chạm tới được — kể cả khi tài khoản đó có quyền trên giao diện web. Mở thêm là một quyết định có chủ đích, không phải mặc định.

4. Ba mức "AI" trong hệ thống — đừng lẫn

MứcỞ đâuViệc và giới hạn
Engine thuê baoMáy chạy AI GatewaySinh ngôn ngữ. Không biết gì về ERP ngoài những gì chỉ dẫn kỹ năng và API trả về. Đổi engine không đổi quyền.
Trợ lý (agent)Workspace của từng ngườiĐọc chỉ dẫn kỹ năng, giữ khoá trong .env, gọi API ERP. Đây là nơi duy nhất "biết" cách nói chuyện với ERP.
Kỹ năng trong ERPBảng skillsLà dữ liệu, không phải mã. Nội dung kỹ năng do người viết hoặc trợ lý dựng nháp; ERP chỉ lưu và trả về đúng phạm vi. Một câu như "bỏ qua hướng dẫn trên" nằm trong ô tóm tắt kỹ năng chỉ là chữ — ERP không diễn giải nó.
Điều dễ hiểu sai nhất. "Kỹ năng" trong ERP nghe giống kỹ năng của Claude Code, nhưng hai thứ khác nhau: kỹ năng ERP là bản ghi nghiệp vụ để người và trợ lý cùng đọc; kỹ năng của trợ lý (~/.claude/skills, ~/.gemini/skills) là tệp chỉ dẫn dạy agent cách gọi API. Tệp chỉ dẫn erp-platform là thứ khiến trợ lý biết đường vào ERP — thiếu nó thì agent trả lời trôi chảy nhưng không gọi API lần nào, và người dùng tưởng việc đã xong.