@digiforce-nc/plugin-field-sort

Plugin cung cấp kiểu field sắp xếp — cho phép người dùng thay đổi thứ tự bản ghi bằng drag & drop, sử dụng LockManager đảm bảo atomic max+1 và action handler move để reorder.

Plugin này làm gì?

Hãy hình dung: bạn cần sắp xếp thủ công menu items, bước quy trình, hoặc danh sách ưu tiên. Plugin này thêm cột sort (BIGINT) vào collection, tự động gán giá trị max+1 khi tạo mới, và cung cấp action move để di chuyển bản ghi lên/xuống hoặc đến vị trí cụ thể — có hỗ trợ scope field để sắp xếp theo nhóm.

Ba nhiệm vụ chính

#	Nhiệm vụ	Chi tiết
1	Auto-assign sort	Khi tạo bản ghi, tự gán `max(sort) + 1` qua LockManager
2	Move action	Action handler cho phép di chuyển bản ghi đến vị trí mới
3	Scope sorting	Sắp xếp trong phạm vi nhóm (ví dụ: sort theo category)

Kiến trúc

Tổng quan

Tầng	Vai trò	Thành phần
Client	Drag & drop UI, hiển thị thứ tự	`SortFieldWidget`
Server	Xử lý move, tính sort value mới	Action `move`, LockManager
Database	Lưu giá trị sort (BIGINT)	Cột sort trên collection

Luồng tạo bản ghi mới

Luồng move (reorder)

Field type `sort`

Thuộc tính	Giá trị
DB column type	BIGINT
Default value	`max(sort) + 1` (trong scope nếu có)
Scope field	Optional — field để nhóm sort (ví dụ: `categoryId`)

LockManager & Scope sorting

Plugin sử dụng @digiforce-nc/lock-manager để đảm bảo atomic operations. Khi cấu hình scope field, mỗi nhóm có chuỗi sort riêng biệt — ví dụ tasks trong category "Phát triển" có sort 1,2,3 độc lập với "Kiểm thử".

Action handler: move

Tham số	Kiểu	Mô tả
`sourceId`	`number/string`	ID bản ghi cần di chuyển
`targetId`	`number/string`	ID bản ghi đích (chèn trước hoặc sau)
`method`	`string`	`insertBefore` hoặc `insertAfter`

Ví dụ sử dụng

Cấu hình field sort

typescript

const sortField = {
  name: 'sort',
  type: 'sort',
  interface: 'sort',
  scopeKey: 'categoryId',
};

Gọi action move

typescript

await api.resource('tasks').move({
  sourceId: 10,
  targetId: 3,
  method: 'insertBefore',
});

Thành phần client

Thành phần	Mô tả
`SortFieldInterface`	Định nghĩa interface cho field sort
`SortFieldWidget`	Widget hiển thị giá trị sort (thường ẩn, dùng cho drag handle)

Dependencies

Package	Vai trò
`@digiforce-nc/server`	Server framework — action handler
`@digiforce-nc/database`	Database ORM — đăng ký field type
`@digiforce-nc/actions`	Action context (move)
`@digiforce-nc/lock-manager`	Đảm bảo atomic operations
`@digiforce-nc/client`	Client framework — đăng ký component