@digiforce-nc/plugin-field-formula

Plugin cung cấp kiểu field công thức tính toán — tự động tính giá trị dựa trên các field khác trong cùng bản ghi, sử dụng engine evaluator hỗ trợ cú pháp mathjs và excel-like.

Plugin này làm gì?

Hãy hình dung: bạn có field price và quantity, muốn field total tự động tính price * quantity. Plugin này cung cấp field type formula với engine tính toán mạnh mẽ — hỗ trợ cả cú pháp toán học (mathjs) lẫn hàm Excel (SUM, IF, CONCAT). Kết quả tự động tính lại khi dữ liệu thay đổi.

Ba nhiệm vụ chính

#	Nhiệm vụ	Chi tiết
1	Tính toán công thức	Engine evaluator tính giá trị dựa trên expression và field values
2	Tự động recompute	Hooks trigger tính lại khi bản ghi save, bulk create, hoặc field definition thay đổi
3	Typed output	Kết quả lưu theo `dataType` setting (number, string, date...)

Kiến trúc

Tổng quan

Plugin có cả server (field type, evaluator, hooks) và client (interface, expression editor). Server tính toán và lưu kết quả; client cung cấp UI soạn công thức.

Luồng tính toán khi save bản ghi

Luồng recompute khi field definition thay đổi

Evaluator engines

Engine	Cú pháp	Ví dụ
mathjs	Toán học tiêu chuẩn	`price * quantity`, `sqrt(a^2 + b^2)`
excel-like	Hàm dạng Excel	`IF(status == "paid", total, 0)`, `CONCAT(firstName, " ", lastName)`

Field type `formula`

Thuộc tính	Mô tả
expression	Biểu thức công thức (tham chiếu field qua tên)
engine	Engine tính toán: `mathjs` hoặc `formula` (excel-like)
dataType	Kiểu dữ liệu cột lưu kết quả (double, string, integer...)

Hooks

Hook	Sự kiện	Hành động
`afterSave`	Bản ghi được lưu	Tính lại formula cho bản ghi đó
`bulkCreate`	Tạo nhiều bản ghi	Tính formula cho tất cả bản ghi mới
`fields.afterUpdate`	Sửa field definition	Recompute toàn bộ bản ghi

Ví dụ sử dụng

Cấu hình field formula

typescript

const totalField = {
  name: 'total',
  type: 'formula',
  interface: 'formula',
  dataType: 'double',
  expression: 'price * quantity',
  engine: 'mathjs',
};

Thành phần client

Thành phần	Mô tả
`FormulaFieldInterface`	Định nghĩa interface cho field formula
`Formula`	Component hiển thị kết quả tính toán (read-only)
`Expression Editor`	UI soạn công thức với autocomplete tên field

Dependencies

Package	Vai trò
`@digiforce-nc/server`	Server framework (peer)
`@digiforce-nc/database`	Database ORM — đăng ký field type
`@digiforce-nc/evaluators`	Engine tính toán (mathjs, excel-like)
`@digiforce-nc/utils`	Tiện ích chung
`@digiforce-nc/client`	Client framework — đăng ký component