Giao diện
@digiforce-nc/plugin-data-source-manager
Plugin quản lý nhiều data source — kết nối, cấu hình, và phân quyền cho các nguồn dữ liệu bên ngoài (PostgreSQL, MySQL, REST API...).
Plugin này làm gì?
Nếu plugin-data-source-main quản lý data source chính (database nội bộ), thì plugin-data-source-manager là tổng đài quản lý tất cả data source — cả nội bộ lẫn bên ngoài. Nó cho phép kết nối đến nhiều database/API khác nhau, mỗi cái có collection riêng, ACL riêng.
Ba nhiệm vụ chính
| # | Nhiệm vụ | Chi tiết |
|---|---|---|
| 1 | Kết nối | Lưu cấu hình kết nối, test connection, load tables từ database ngoài |
| 2 | Quản lý schema | Overlay collections/fields lên data source ngoài (tên hiển thị, UI schema) |
| 3 | Phân quyền | ACL riêng cho mỗi data source (roles → resources → actions → scopes) |
AI: hỏi dữ liệu bằng ngôn ngữ tự nhiên (Data Query)
Nếu hệ thống có bật AI và bot được gán tool/skill truy vấn dữ liệu, bạn có thể yêu cầu AI tổng hợp dữ liệu theo collection và điều kiện (đếm, tổng, trung bình, nhóm theo thời gian, sắp xếp, giới hạn…).
- Xem tổng quan AI (cách bật AI, tạo bot, gán tools/skills): xem
plugin-ai. - Khi nào dùng: cần nhanh chóng trả lời câu hỏi kiểu “tháng này bao nhiêu đơn?”, “doanh thu theo kênh”, “top khách hàng”, “tỉ lệ chuyển đổi theo tuần”… mà không phải tự viết truy vấn.
- Ví dụ câu hỏi:
- “Đếm số đơn theo trạng thái trong 7 ngày gần nhất, sắp xếp giảm dần.”
- “Tổng doanh thu theo tháng 6 tháng gần nhất, nhóm theo tháng.”
- “Top 10 sản phẩm theo số lượng bán trong 30 ngày.”
Gợi ý
Để AI trả kết quả đúng, hãy nêu rõ collection, khoảng thời gian, và field cần đo (ví dụ amount, createdAt, status).
Kiến trúc
Tổng quan
| Thành phần | Vai trò |
|---|---|
| DataSource Factory | Tạo DataSource instance theo type (postgres, mysql, rest-api...) |
| Loader | Load data source vào app.dataSourceManager, quản lý trạng thái (loading/loaded/failed) |
| Per-DS ACL sync | Mỗi data source có ACL riêng, đồng bộ role/resource/action/scope |
| Schema overlay | Cho phép override tên, UI schema cho collection/field từ nguồn ngoài |
Luồng thêm data source mới
API endpoints
Data source management
| Endpoint | Mô tả |
|---|---|
dataSources:list | Danh sách data source (kèm status) |
dataSources:listEnabled | Data source đang bật (không gồm main) |
dataSources:create | Tạo kết nối mới |
dataSources:update | Cập nhật cấu hình |
dataSources:destroy | Xóa kết nối (không xóa được main) |
dataSources:testConnection | Test kết nối trước khi lưu |
dataSources:refresh | Reload data source |
dataSources:readTables | Đọc danh sách bảng từ DB ngoài |
dataSources:loadTables | Load bảng cụ thể vào collection |
Collections & fields overlay
| Endpoint | Mô tả |
|---|---|
dataSources.collections:list | Danh sách collection của data source |
dataSources.collections:update | Override metadata collection |
dataSourcesCollections.fields:list | Danh sách field |
dataSourcesCollections.fields:create | Thêm field overlay |
dataSourcesCollections.fields:update | Sửa field overlay |
dataSourcesCollections.fields:destroy | Xóa field overlay |
Per-datasource ACL
| Endpoint | Mô tả |
|---|---|
dataSources.roles:get | Lấy cấu hình role cho data source |
dataSources.roles:update | Cập nhật strategy role cho data source |
roles.dataSourceResources:create | Gán permission resource cho role |
roles.dataSourceResources:update | Cập nhật permission |
roles.dataSourcesCollections:list | Danh sách collection kèm trạng thái permission |
Database
| Bảng | Chứa gì |
|---|---|
dataSources | Kết nối (key, type, options, enabled, fixed) |
dataSourcesCollections | Metadata overlay collection (tên, options) |
dataSourcesFields | Metadata overlay field (interface, UI schema) |
dataSourcesRoles | Strategy role per data source |
dataSourcesRolesResources | Permission resource per role per data source |
dataSourcesRolesResourcesActions | Action permission + fields + scope |
dataSourcesRolesResourcesScopes | Named scope per data source |
Trạng thái data source
Plugin theo dõi trạng thái mỗi data source:
| Status | Ý nghĩa |
|---|---|
loading | Đang kết nối và load schema |
loaded | Sẵn sàng sử dụng |
failed | Kết nối lỗi (xem dataSourceErrors) |
reloading | Đang reload (sau khi cập nhật cấu hình) |
Mở rộng loại data source
Plugin bên ngoài đăng ký driver:
typescript
// Ví dụ: plugin-data-source-external-postgres
this.app.dataSourceManager.factory.register('postgres', PostgresDataSource);Các driver có sẵn: plugin-data-source-external-postgres, plugin-data-source-external-mysql, plugin-data-source-external-mssql, plugin-data-source-external-oracle, plugin-data-source-external-mariadb, plugin-data-source-rest-api.
Thành phần client
| Thành phần | Mô tả |
|---|---|
| DatabaseConnectionManager | Trang quản lý data source (Settings → Data sources) |
| MainDataSourceManager | Quản lý data source chính |
| CollectionManagerPage | Quản lý collection trong data source |
| PermissionManager | Cấu hình ACL per data source |
| DatabaseConnectionProvider | Context provider cho thông tin kết nối |
Dependencies
| Package | Vai trò |
|---|---|
@digiforce-nc/server | Server framework |
@digiforce-nc/client | Client framework |
@digiforce-nc/plugin-acl | ACL models (RoleResourceModel) + mergeRole |
Mục lục chi tiết
- Kiến trúc — DataSource lifecycle, factory pattern, per-DS ACL
- API reference — DataSources CRUD, remote collections/fields, roles resources
- Database schema — ER diagram, 7 bảng
- FAQ — Câu hỏi thường gặp