@digiforce-nc/plugin-ui-core

Plugin UI Core engine — quản lý widget tree, xử lý biến template, cung cấp query service cho giao diện động, và UI Builder API để xây dựng giao diện programmatically.

Plugin này làm gì?

Nếu plugin-ui-schema-storage lưu cấu trúc giao diện, thì plugin-ui-core là bộ máy vận hành — nó biết cách đọc widget schema, resolve biến template thành giá trị thực, chạy query để lấy dữ liệu hiển thị, và cung cấp UI Builder để AI agent hoặc automation tạo/sửa giao diện qua API. Bốn thành phần này phối hợp tạo nên hệ thống giao diện động hoàn chỉnh.

Bốn nhiệm vụ chính

#	Nhiệm vụ	Chi tiết
1	Widget management	CRUD uiWidgets, duplicate, attach vào parent, move, mutate batch
2	Variables resolution	Resolve biến template (cú pháp mustache) thành giá trị thực tế
3	Query service	Chạy query dữ liệu, lưu query tái sử dụng, data binding cho widget
4	UI Builder	API programmatic để tạo page, tab, block, field, action — phục vụ AI agent và automation

---

Kiến trúc — luồng render widget

API endpoints

Widget resource

Endpoint	Mô tả
uiWidgets:findOne	Lấy widget theo UID
uiWidgets:schema	Lấy schema đơn lẻ của widget
uiWidgets:schemas	Lấy nhiều schema cùng lúc
uiWidgets:schemaBundle	Bundle schema + toàn bộ descendants
uiWidgets:save	Lưu widget (tạo mới hoặc cập nhật)
uiWidgets:duplicate	Nhân bản widget kèm descendants
uiWidgets:attach	Gắn widget vào parent tại vị trí chỉ định
uiWidgets:move	Di chuyển widget sang parent khác
uiWidgets:destroy	Xóa widget kèm descendants
uiWidgets:mutate	Thực hiện batch operations trên nhiều widget

Variables

Endpoint	Mô tả
variables:resolve	Resolve biến template — nhận danh sách biến dạng path (VD: ctx.currentUser.id), trả về giá trị tương ứng

Lưu ý: Cú pháp biến sử dụng dạng mustache — tên biến được bao trong cặp ngoặc nhọn kép. Tuy nhiên, plugin thực tế nhận path string qua API, không parse template phía server.

Query service

Endpoint	Mô tả
queryService:run	Chạy query trực tiếp (truyền SQL/filter)
queryService:runById	Chạy query đã lưu theo ID
queryService:save	Lưu query để tái sử dụng
queryService:getBind	Lấy data binding — ánh xạ giữa query result và widget field

Database — 3 bảng chính

Bảng	Chứa gì	Ví dụ
uiWidgets	Widget definitions (uid, type, options JSON)	{ uid: 'w1', type: 'table', options: {...} }
uiWidgetTreePath	Quan hệ cây widget (closure table)	{ ancestor: 'w1', descendant: 'w2', depth: 1 }
queryService	Query đã lưu (uid, dataSourceKey, sql)	{ uid: 'q1', sql: 'SELECT * FROM orders' }

UI Builder API (mới)

Module ui-builder/ cung cấp API xây dựng giao diện programmatically — phù hợp cho AI agent, script tự động, hoặc tool migration.

Kiến trúc UI Builder

30+ Actions

Nhóm	Actions	Mô tả
Read	catalog, context, get	Liệt kê widget types, đọc context variables, lấy UI hiện tại
Page	createPage, destroyPage	Tạo/xóa trang
Tab	addTab, updateTab, moveTab, removeTab	Quản lý tab trong trang
Popup Tab	addPopupTab, updatePopupTab, movePopupTab, removePopupTab	Tab trong popup/drawer
Block	addBlock, addBlocks	Thêm block (table, form, chart...) vào trang
Field	addField, addFields	Thêm field vào block
Action	addAction, addActions, addRecordAction, addRecordActions	Thêm action buttons
Settings	updateSettings, setEventFlows, setLayout	Cập nhật cấu hình widget
Layout	moveNode, removeNode	Di chuyển/xóa node
Menu	createMenu, updateMenu	Quản lý menu navigation
Batch	compose, configure, apply, mutate	Operations phức hợp, atomic batch

Ví dụ: Tạo table block bằng API

// Thêm table block hiển thị collection "orders" vào page
await agent.resource('uiBuilder').addBlock({
  values: {
    target: { uid: 'page-grid-uid' },
    use: 'TableBlockWidget',
    resource: {
      binding: 'currentCollection',
      collectionName: 'orders',
    },
  },
});

// Thêm fields vào block vừa tạo
await agent.resource('uiBuilder').addFields({
  values: {
    target: { uid: 'table-block-uid' },
    fields: ['title', 'amount', 'status', 'createdAt'],
  },
});

Catalog — widget type registry

uiBuilder:catalog trả về danh sách widget types khả dụng kèm metadata:

const { data } = await agent.resource('uiBuilder').catalog({
  values: { kind: 'block' },
});
// → [{ key: 'table', use: 'TableBlockWidget', kind: 'block',
//      editableDomains: ['props', 'stepParams'], ... }]

Mỗi catalog item chứa: key, label, use (widget class name), kind, scope, editableDomains, settingsSchema, configureOptions, resourceBindings, eventCapabilities.

Mutate — atomic batch operations

uiBuilder:mutate cho phép gộp nhiều operations vào 1 transaction:

await agent.resource('uiBuilder').mutate({
  values: {
    atomic: true,
    ops: [
      { type: 'addBlock', target: { uid: 'grid-1' }, values: { use: 'FormBlockWidget', ... } },
      { type: 'addField', target: { uid: '$ref:op-0' }, values: { field: 'email' } },
      { type: 'updateSettings', target: { uid: '$ref:op-0' }, values: { title: 'Thêm người dùng' } },
    ],
  },
});

Thành phần chính phía server

Thành phần	Mô tả
UiWidgetRepository	Repository xử lý CRUD widget + tree operations
UiWidgetSchemaService	Service resolve schema bundle, xử lý inheritance
Widget Schema Registry	Registry đăng ký widget type mới từ plugin khác
VariablesService	Service resolve biến template thành giá trị
QueryServiceManager	Quản lý query execution và caching
UiBuilderService	Service chính của UI Builder — catalog, compose, mutate, context

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-localization	Localization cho widget labels

Xem thêm

• Sao chép cấu trúc menu / trang / widget ra file và nạp lại — hướng dẫn lệnh digiforce schema (export và import) trong tài liệu CLI.

Mục lục chi tiết

• Kiến trúc — Widget repository, schema service, variable resolution, query service
• API reference — uiWidgets resource, variables:resolve, queryService
• Database schema — ER diagram, closure table, 3 bảng
• FAQ — Câu hỏi thường gặp