Data model & metadata

Digiforce là nền tảng metadata-driven: cấu trúc dữ liệu, quan hệ, và giao diện đều khai báo bằng JSON tại runtime - không hardcode trong source. Trang này mô tả mô hình dữ liệu ở mức kiến trúc. Deep dive code-level: Core: Database, Collection & Repository.

---

1) Collection - đơn vị trung tâm

Collection là bản mô tả (metadata) cho một bảng dữ liệu. Mỗi collection khai báo:

• name - tên logic (map thành table/model).
• fields - danh sách field (column) với type, interface, validation.
• relations - hasOne, hasMany, belongsTo, belongsToMany.
• indexes, timestamps, paranoid (soft delete).
• origin - nguồn gốc (core, plugin, user-defined).

Vòng đời collection

1. Khai báo - plugin gọi db.collection(options) hoặc đặt file JSON trong collections/.
2. Extend - plugin khác gọi db.extendCollection(options) để thêm field/relation vào collection đã có.
3. Sync - db.sync() so khớp metadata → DDL (tạo/sửa table, column, index).
4. Runtime - CollectionManager giữ map tất cả collection; ResourceManager tự map collection → resource.

extendCollection - mở rộng không fork

Plugin B muốn thêm field vào collection của plugin A:

Plugin A: db.collection({ name: 'orders', fields: [{ name: 'status', type: 'string' }] })
Plugin B: db.extendCollection({ name: 'orders', fields: [{ name: 'priority', type: 'integer' }] })

Nếu collection orders chưa tồn tại lúc B gọi, options được lưu vào delayCollectionExtend và tự apply khi A define.

---

2) Field types & interfaces

Field types (lưu trữ)

Field type quyết định cách dữ liệu được lưu trong database:

Type	Database column	Ví dụ
string	VARCHAR	name, email
text	TEXT	description, content
integer	INTEGER	count, order
bigInt	BIGINT	snowflake ID
float	FLOAT / DOUBLE	price, score
boolean	BOOLEAN	isActive
date	DATE / TIMESTAMP	createdAt
json	JSON / JSONB	config, metadata
array	ARRAY (Postgres) / JSON (MySQL)	tags
belongsTo	Foreign key	order.userId
hasMany	Virtual (reverse FK)	user.orders
belongsToMany	Junction table	user ↔ roles

Field interfaces (hiển thị)

Interface quyết định UI component nào render field:

Interface	UI component
input	Text input
textarea	Multiline text
richText	Rich text editor
number	Number input
percent	Percentage input
select	Dropdown / enum
multipleSelect	Multi-select
checkbox	Checkbox
datetime	Date/time picker
attachment	File upload
linkTo	Relation picker
subTable	Inline sub-table

Plugin đăng ký field type/interface mới: db.registerFieldTypes({ myType: MyFieldClass }).

---

3) UI Schema - giao diện metadata-driven

UI Schema là JSON tree mô tả cây component: layout, block, field, action button. Schema lưu trong database (collection uiSchemas) và load runtime.

Cấu trúc schema node

Mỗi node trong schema tree:

{
  "x-uid": "unique-id",
  "x-component": "FormV2",
  "x-component-props": { "layout": "vertical" },
  "x-decorator": "CardItem",
  "x-settings": "formSettings",
  "x-initializer": "formInitializer",
  "properties": {
    "field1": { "x-component": "Input", ... },
    "field2": { "x-component": "Select", ... }
  }
}

Key	Vai trò
x-component	Tên component (resolve từ component map)
x-component-props	Props truyền vào component
x-decorator	Component wrapper (card, form item, …)
x-settings	ID cấu hình settings menu (schema settings manager)
x-initializer	ID initializer menu (thêm child nodes)
properties	Child schema nodes

Thay đổi UI không cần rebuild

1. Admin kéo thả block / thêm field trong UI builder.
2. Client gọi API lưu schema node mới vào uiSchemas.
3. Page refresh → Schema Renderer đọc lại → render component mới.

Không cần build code, deploy lại, hay thay đổi plugin source.

---

4) Collection metadata trong database

Collection metadata cũng được lưu trong database (ngoài việc khai báo trong code):

• collections table - lưu metadata collection (user-defined hoặc synced từ code).
• fields table - lưu metadata field cho từng collection.
• uiSchemas table - lưu UI schema tree.

Plugin collection-manager quản lý CRUD metadata này. Khi admin tạo collection mới qua UI → insert metadata → db.sync() → tạo table thực.

---

5) Data source → collection → resource mapping

• Mỗi DataSource giữ CollectionManager (metadata) và ResourceManager (API endpoints).
• Collection tự động map thành resource - tên resource = tên collection.
• Resource cung cấp CRUD actions (list, get, create, update, destroy) qua Repository.
• Plugin thêm resource/action tùy chỉnh ngoài auto-mapping.

---

6) Migration - phiên bản dữ liệu

Khi cấu trúc collection thay đổi (thêm field, sửa type, thêm index):

1. Code migration - file migration trong plugin, chạy khi install / upgrade.
2. Sync migration - db.sync() so khớp model hiện tại với table → tự sinh ALTER.

Thứ tự: core migration → plugin migration (theo dependency). ApplicationVersion theo dõi phiên bản đã chạy.

---

7) Tổng kết: metadata-driven workflow

Từ một collection metadata duy nhất, hệ thống tự sinh:

• Table trong database.
• Resource + actions (CRUD API).
• UI Schema mặc định (có thể tùy chỉnh bằng UI builder).

Đây là cốt lõi "metadata-driven" của Digiforce.

---

Đọc tiếp

• Tổng quan hệ thống
• Server architecture - ResourceManager, DataSourceManager.
• Client architecture - Schema system, component map.
• Plugin architecture - cách plugin khai báo collection.
• Core: Database, Collection & Repository - deep dive code-level.