@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)

Modeling API (mới)

Module modeling/ cung cấp API khai báo (declarative) để tạo/cập nhật collection và field — phù hợp cho AI agent, migration script, hoặc công cụ tự động:

Endpoint	Mô tả
collections:apply	Tạo hoặc cập nhật collection kèm fields theo khai báo (upsert semantics)
fields:apply	Tạo hoặc cập nhật field đơn lẻ cho collection có sẵn
modeling:inspect	Kiểm tra trạng thái modeling hiện tại (templates, plugins, collections)

collections:apply — declarative upsert

await agent.resource('collections').apply({
  values: {
    name: 'orders',
    title: 'Đơn hàng',
    template: 'general',
    fields: [
      { name: 'title', interface: 'input', type: 'string', uiSchema: { title: 'Tiêu đề' } },
      { name: 'amount', interface: 'number', type: 'float', uiSchema: { title: 'Số tiền' } },
    ],
  },
});

Nếu collection orders đã tồn tại → cập nhật; chưa có → tạo mới kèm migrate bảng vật lý.

Capability checks

Trước khi apply, module tự kiểm tra:

• Plugin dependencies: VD field m2m yêu cầu plugin-field-m2m-array đã enabled.
• Template support: view template yêu cầu DB view tồn tại trước.
• Inheritance: inherit template yêu cầu parent collection tồn tại.

Verification

Sau khi apply, verifyCollectionDefinition() kiểm tra collection vừa tạo/sửa:

• Primary key id có tồn tại không
• Mỗi field có interface, type, uiSchema.title không
• Trả về { valid: boolean, issues: string[] } giúp phát hiện lỗi sớm

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