@digiforce-nc/plugin-data-source-main

Plugin quản lý collection và field cho data source chính (main) — cầu nối giữa metadata lưu trong DB và runtime ORM.

Plugin này làm gì?

Hãy hình dung database của ứng dụng như một kho hàng. plugin-data-source-main là hệ thống quản lý kệ hàng — nó biết có bao nhiêu kệ (collection), mỗi kệ có ngăn gì (field), và khi bạn thêm/sửa/xóa kệ qua giao diện, nó tự động tạo/đổi bảng vật lý trong database.

Ba nhiệm vụ chính

#	Nhiệm vụ	Chi tiết
1	Lưu metadata	Lưu định nghĩa collection/field trong bảng `collections` và `fields`
2	Load vào runtime	Đọc metadata → tạo Collection instance trong Database ORM (theo thứ tự dependency)
3	Sync vật lý	Tạo/alter bảng thực trong database khi schema thay đổi

Kiến trúc

Tổng quan

Thành phần	Vai trò
CollectionRepository	Load collection từ DB theo thứ tự topological sort (xử lý kế thừa, view, FK)
CollectionModel	Load 1 collection vào runtime, migrate bảng vật lý
FieldModel	Load field, đồng bộ unique index, default value, sort, FK
DB Hooks	Tự động migrate khi admin thêm/sửa collection/field qua UI

Luồng tạo collection mới

API endpoints

Collection management

Endpoint	Mô tả
`collections:list`	Danh sách collection
`collections:listMeta`	Danh sách collection đã load (với field metadata)
`collections:create`	Tạo collection mới (tự động migrate)
`collections:update`	Cập nhật collection
`collections:destroy`	Xóa collection (cascade remove fields, FK)
`collections:setFields`	Bulk replace toàn bộ fields cho collection (transactional)

Composite constraints

Endpoint	Mô tả
`collections:createCompositeConstraint`	Tạo unique constraint trên nhiều field
`collections:updateCompositeConstraint`	Cập nhật constraint
`collections:deleteCompositeConstraint`	Xóa constraint

Database views

Endpoint	Mô tả
`dbViews:list`	Danh sách DB view chưa kết nối collection
`dbViews:get`	Infer fields từ view
`dbViews:query`	Query trực tiếp từ view (phân trang)

Main data source

Endpoint	Mô tả
`mainDataSource:refresh`	Reload collection từ metadata
`mainDataSource:syncFields`	Đồng bộ fields từ database vật lý

Database (metadata tables)

Bảng	Chứa gì	Ví dụ
`collections`	Định nghĩa collection (name, title, inherit, options)	`{ name: 'orders', title: 'Đơn hàng' }`
`fields`	Định nghĩa field (name, type, interface, options)	`{ name: 'title', type: 'string', interface: 'input' }`
`collectionCategories`	Danh mục phân loại collection	`{ name: 'business', color: 'blue' }`
`collectionCategory`	Liên kết collection ↔ category (M2M)

Tính năng đặc biệt

Topological sort khi load

Collection có thể kế thừa nhau (inherit) hoặc có FK chéo. Plugin dùng topological sort để load đúng thứ tự:

users (không phụ thuộc) → orders (FK → users) → orderItems (FK → orders)

Hỗ trợ Database views

Admin có thể tạo collection từ DB view có sẵn — plugin tự infer field types từ view schema.

db2cm (database-to-collection-manager)

Khi collection được tạo bằng code (không qua UI), db2cm tự động import metadata vào bảng collections/fields để hiển thị trên UI.

Multi-instance sync

Khi chạy cluster, thay đổi collection/field trên instance A tự động sync sang instance B qua message bus.

Thành phần client

Thành phần	Mô tả
Preset field templates	Tự động thêm field mặc định khi tạo collection mới: `id`, `createdAt`, `createdBy`, `updatedAt`, `updatedBy`

Dependencies

Package	Vai trò
`@digiforce-nc/database`	Database ORM (peer)
`@digiforce-nc/server`	Server framework (peer)
`@digiforce-nc/client`	Client framework (peer)
`@digiforce-nc/plugin-error-handler`	Xử lý lỗi field/collection
`@digiforce-nc/plugin-field-sort`	Sắp xếp field

Mục lục chi tiết

Kiến trúc — Meta-driven DDL, collection/field lifecycle, sync
API reference — Collections CRUD, fields CRUD, mainDataSource:refresh/syncFields
Database schema — ER diagram, meta tables
FAQ — Câu hỏi thường gặp