@digiforce-nc/plugin-field-sequence

Plugin cung cấp kiểu field mã tự tăng — tự động sinh mã duy nhất theo pattern tùy chỉnh (ví dụ: INV-2024-0001), hỗ trợ pattern đa phần (string + integer với cron reset), đảm bảo an toàn đồng thời qua bảng sequences.

Plugin này làm gì?

Hãy hình dung: bạn cần mã đơn hàng DH-2024-00001, mã hóa đơn HD-00123, mã nhân viên NV-001... tự động tăng theo quy tắc riêng. Plugin này quản lý sequence counter an toàn đồng thời (concurrent-safe) thông qua bảng sequences riêng biệt, với pattern system linh hoạt cho phép kết hợp chuỗi cố định và số tự tăng có thể reset theo lịch cron.

Bốn nhiệm vụ chính

#	Nhiệm vụ	Chi tiết
1	Pattern system	Kết hợp phần tĩnh (string) và phần tự tăng (integer) trong một template
2	Concurrent-safe counter	Bảng `sequences` đảm bảo không trùng mã khi nhiều request đồng thời
3	Cron reset	Counter tự reset theo lịch (hàng ngày, hàng tháng, hàng năm)
4	Repair mechanism	`app.on('repair')` sửa counter khi dữ liệu không đồng bộ

Kiến trúc

Tổng quan

Luồng sinh mã khi tạo bản ghi

Pattern system

Pattern gồm nhiều phần, mỗi phần có type riêng:

Type	Mô tả	Ví dụ
string	Chuỗi cố định	`"DH-"`, `"-"`
integer	Số tự tăng với padding	`00001`, `00002`, ...

Phần integer có thêm cấu hình:

Thuộc tính	Mô tả
`digits`	Số chữ số (padding zeros) — ví dụ: 5 → `00001`
`start`	Giá trị bắt đầu (mặc định 1)
`cycle`	Biểu thức cron để reset counter (ví dụ: `0 0 1 1 *` = đầu năm)

Database: bảng sequences

Cột	Kiểu	Mô tả
`id`	BIGINT	Primary key
`collection`	STRING	Tên collection chứa field
`field`	STRING	Tên field sequence
`key`	INTEGER	Counter hiện tại
`lastGeneratedAt`	DATE	Thời điểm sinh mã gần nhất

Hooks

Hook	Sự kiện	Hành động
`beforeSave`	Tạo bản ghi mới	Sinh mã sequence, tăng counter
`afterDestroy`	Xóa field	Dọn dẹp row trong bảng sequences
`app.on('repair')`	Sửa chữa hệ thống	Đồng bộ counter với giá trị max thực tế trong bảng

Concurrent safety

Plugin sử dụng bảng sequences thay vì tính MAX() từ dữ liệu — tránh race condition khi nhiều request tạo bản ghi đồng thời. Counter được tăng atomic trong một transaction.

Ví dụ sử dụng

Cấu hình field sequence

typescript

const orderCodeField = {
  name: 'orderCode',
  type: 'sequence',
  interface: 'sequence',
  patterns: [
    { type: 'string', options: { value: 'DH-' } },
    { type: 'integer', options: { digits: 5, start: 1, cycle: '0 0 1 1 *' } },
  ],
};

Mã tạo ra theo thời gian

Đầu năm 2024: DH-00001, DH-00002, ...
Đầu năm 2025: DH-00001 (reset), DH-00002, ...

Thành phần client

Thành phần	Mô tả
`SequenceFieldProvider`	Provider cung cấp context cho cấu hình pattern
`SequenceFieldInterface`	Định nghĩa interface cho field sequence

Dependencies

Package	Vai trò
`@digiforce-nc/server`	Server framework — đăng ký hooks
`@digiforce-nc/database`	Database ORM — field type + bảng sequences
`@digiforce-nc/client`	Client framework — đăng ký component