Tham chiếu kỹ thuật

Sort Field Type

Thuộc tính	Giá trị
Field type	sort
DB column type	BIGINT
Default value	MAX(sort) + 1 (trong scope nếu có)
scopeKey	Tên field dùng làm scope (optional)

Khi tạo cột sort, hệ thống dùng BIGINT để hỗ trợ giá trị lớn, tránh tràn số khi collection có nhiều bản ghi.

LockManager — Atomic max+1

Plugin sử dụng @digiforce-nc/lock-manager để đảm bảo thao tác tìm MAX và gán giá trị mới diễn ra atomic:

Thread A tạo bản ghi:
  → Acquire lock (collection + scope)
  → SELECT MAX(sort) WHERE scopeKey = value
  → max = 5
  → INSERT với sort = 6
  → Release lock

Thread B tạo bản ghi (đợi lock):
  → Acquire lock
  → SELECT MAX(sort) → max = 6
  → INSERT với sort = 7
  → Release lock

Lock theo từng collection + scope, không block toàn bộ hệ thống.

Move Action Handler

Action move đăng ký vào collection, xử lý reorder:

insertBefore

move(sourceId=A, targetId=B, method='insertBefore')
  → Acquire lock
  → Đọc sort values: A.sort=5, B.sort=2
  → Shift: tất cả records có sort >= 2 → sort + 1
  → Set A.sort = 2
  → Release lock

insertAfter

move(sourceId=A, targetId=B, method='insertAfter')
  → Acquire lock
  → Đọc sort values: A.sort=5, B.sort=2
  → Shift: tất cả records có sort > 2 → sort + 1
  → Set A.sort = 3
  → Release lock

Xử lý scope

Khi có scopeKey, move chỉ ảnh hưởng các bản ghi trong cùng scope:

move(sourceId=A, targetId=B)
  → Nếu A.scope != B.scope:
    → Xóa A khỏi scope cũ (shift records trong scope cũ)
    → Thêm A vào scope mới tại vị trí targetId
  → Nếu cùng scope:
    → Reorder bình thường

Scope Field (Optional)

Cấu hình	Mô tả
scopeKey	Tên field dùng phân nhóm
Không có scope	Toàn bộ bảng chia sẻ một chuỗi sort
Có scope	Mỗi giá trị scope có chuỗi sort riêng (bắt đầu từ 1)

Ví dụ: scopeKey: 'categoryId' → tasks trong category "Dev" (sort 1,2,3) độc lập với "QA" (sort 1,2,3).

Sơ đồ tổng quan

┌──────────────┐    move request    ┌──────────────┐
│ Client       │ ─────────────────→ │ Action move  │
│ (drag-drop)  │                    │              │
└──────────────┘                    └──────┬───────┘
                                           │
                                    ┌──────┴───────┐
                                    │ LockManager  │
                                    │ (atomic ops) │
                                    └──────┬───────┘
                                           │
                                    ┌──────┴───────┐
                                    │ Database     │
                                    │ (BIGINT col) │
                                    └──────────────┘