Tệp mô hình
Một tệp YAML khai báo thực thể, trường, vai, quyền và quy trình của một nghiệp vụ.
Lõi dựng bảng dữ liệu, vai Keycloak, API và giao diện từ tệp này, nên đổi nghiệp vụ là đổi tệp, không đổi mã.
Đặc tả hiện hành cho trình soạn thảo ở model-v1.schema.json, và tệp sai mẫu dùng cho kiểm tự động ở e2e/fixtures/invalid-models/.
Ví dụ
Rút gọn từ equipment.yaml:
format: 1
name: equipment
roles:
- {name: BORROWER}
- {name: KEEPER, staff: true}
entities:
device:
fields:
code: {type: text, required: true, unique: true}
name: {type: text, required: true}
access: {BORROWER: read, KEEPER: all}
loan:
fields:
device: {type: reference, to: device, required: true}
reason: {type: text, required: true}
from_at: {type: datetime, required: true}
access: {BORROWER: own, KEEPER: all}
process: {family: approval, handler: KEEPER}
Các mẫu dùng được nằm ở templates/ và hiện trong tab Thư viện mẫu của bảng điều khiển.
Nâng định dạng
Format hiện hành là 1.
Lõi vẫn đọc format 0 bằng cách chạy migration 0 → 1 trong bộ nhớ trước khi kiểm tệp; format mới hơn bản lõi bị từ chối.
dxos model upgrade <tệp> gọi cùng pipeline migration và in unified diff mà không ghi tệp.
Sau khi đọc diff, chạy dxos model upgrade --write <tệp> để thay tệp bằng kết quả hoàn chỉnh qua một lần rename nguyên tử.
Chạy lại trên format hiện hành không đổi nội dung.
Hệ thống nhận ra tệp đổi theo nội dung chữ, nên lần áp dụng đầu của tệp đã nâng tạo thêm một phiên bản không đổi bảng hay quyền nào, và dxos plan --check trả 2 cho đến lúc đó.
Tệp tạm nằm cùng thư mục với tệp gốc và giữ quyền, chủ sở hữu, nhóm của tệp.
Lỗi ở bước migration hay ghi tệp tạm thì tệp gốc giữ nguyên; tiến trình dừng trước rename thì xóa tệp .dxos-model-upgrade.* còn sót rồi chạy lại.
Muốn quay lại sau rename, dùng lịch sử Git hoặc bản sao lưu.
Kiểm tệp trước khi áp dụng
dxos lint <tệp>... đọc tệp bằng đúng bộ đọc của backend và không cần hệ thống đang chạy.
Mỗi lỗi in một dòng tệp:dòng:cột: nội dung, hoặc tệp: nội dung khi lỗi không có một vị trí.
Mã thoát là 0 khi mọi tệp hợp lệ, 1 khi có lỗi và 2 khi không đọc được tệp.
Trên bản cài, lệnh chạy trong image backend đã cài, không mở mạng và không đổi tệp nào.
Trên máy không có DX-OS, tải dxos-lint.jar ở trang Release và chạy java -jar dxos-lint.jar <tệp>... với Java 21; đặt DXOS_LINT_JAR thì dxos lint dùng tệp này thay cho image.
Ví dụ workflow CI cho kho mô hình ở examples/model-repo.
Lint chỉ kiểm tệp, nên dxos plan còn so tệp với mô hình đang chạy, đích webhook và dữ liệu hiện có.
Kết quả lint hợp lệ không có nghĩa là apply thành công; kết quả lint có lỗi thì plan cũng từ chối đúng những lỗi đó.
dxos conformance <mô hình> chạy trên hệ thống đang chạy và kiểm các rào chắn của lõi cho mô hình đã áp dụng; cách chạy và điều kiện ở Cài đặt và vận hành.
Trường và đơn vị
- Kiểu trường:
text,number,datetime,date,boolean,choice,reference,user,unit,code(mục Mã hồ sơ đọc được). - Trường
dategiữ một ngày dạngYYYY-MM-DD, còndatetimegiữ một thời điểm kèm múi giờ. - Trường
booleanlà đúng hoặc sai (true,false); không đặtrequiredhayunique, muốn có giá trị ban đầu thì đặtdefault. - Trường
choicekèmmultiple: truegiữ nhiều lựa chọn trongoptions. API nhận và trả một mảng, mỗi lựa chọn một lần và theo thứ tự củaoptions, và lọc bằngfilter.<tên>.contains=<lựa chọn>.defaultlà một danh sách các lựa chọn củaoptions, không trùng nhau và không rỗng, ví dụdefault: [Mới, Đã sửa]; bản ghi tạo mà không gửi trường này nhận danh sách đó. Trường này không đi cùngunique. - Trường
usergiữ id của một tài khoản; giao diện cho chọn theo tên, và API từ chối id không có thật. - Đơn vị khai báo ở
units, mỗi đơn vị là một nhóm Keycloak; trường kiểuunitcho biết hồ sơ thuộc đơn vị nào. Ví dụ đầy đủ ởonestop.yaml.
Mã hồ sơ đọc được
Trường type: code cho mỗi hồ sơ một mã ngắn để đọc, in và tra, ví dụ HS-2026-00007.
fields:
ma_ho_so: {type: code, format: "HS-{year}-{seq:5}"}
formatgồm chữ cố định (chữ, số và._/-),{year}là năm hồ sơ được tạo (4 chữ số, giờ Việt Nam) và đúng một{seq:N}là số thứ tự viết đủNchữ số, từ 1 đến 9, thêm số 0 ở đầu.- Mỗi thực thể có tối đa một trường
code; trường này luôn duy nhất và không đi cùngrequired,unique,default,renamed_fromhay các ràng buộc giá trị. - Hệ thống gán mã một lần khi tạo hồ sơ; ghi hay sửa mã qua API bị từ chối (400), và sửa hồ sơ không đổi mã.
- Số thứ tự đếm riêng cho từng mô hình, thực thể và trường; khuôn có
{year}thì mỗi năm đếm lại từ 1, khuôn không có thì đếm tiếp mãi. Hai hồ sơ tạo cùng lúc không bao giờ trùng mã, và hồ sơ tạo không thành không làm mất số. - Hết số (ví dụ
{seq:3}đã đến 999) thì hồ sơ mới bị từ chối với 422ERR_CODE_EXHAUSTED; tăngNtrong khuôn. - Tra theo mã bằng
filter.<trường>=<mã>hoặcfilter.<trường>.like=<một phần của mã>; metadata ghitype: codekèmformat, và OpenAPI của mô hình đánh dấu trường chỉ đọc. - Thêm trường
codevào thực thể đã có hồ sơ là thay đổiMIGRATION: khi áp dụng, hồ sơ cũ nhận mã theo thứ tựid, đếm theo năm hồ sơ được tạo, và hồ sơ mới nối tiếp. - Đổi
formatlà thay đổiSAFE: chỉ hồ sơ mới theo khuôn mới, số vẫn nối tiếp và mã cũ giữ nguyên. - Bỏ trường
coderồi thêm lại (hoặc thêm trường khác cùng tên) thì số vẫn nối tiếp từ số cuối đã dùng, vì bộ đếm gắn với mô hình, thực thể và tên trường.
Ràng buộc giá trị
minvàmaxgiới hạn một trườngnumberhoặcdate, cả hai đầu đều nhận giá trị:qty: {type: number, min: 1, max: 100}.patternlà biểu thức chính quy của một trườngtext, và phải khớp toàn bộ giá trị:code: {type: text, pattern: "[A-Z]{3}-[0-9]+"}. Biểu thức chỉ gồm ký tự, dấu chấm, lớp ký tự[...], nhóm(...),|và các lượng từ*,+,?,{n},{n,m}với số lặp tối đa 255. Không có^,$,\d,(?hay lượng từ lười. Một nhóm có lượng từ bên trong không được lặp bằng*,+hay{n,m}, như([a-z]+)*, vì kiểu viết đó có thể làm phép khớp chạy rất lâu. Giá trị được kiểm bằngpatterndài tối đa 1000 ký tự, và phép khớp chỉ được đọc một số ký tự nhất định; quá số đó thì giá trị bị từ chối vớiis too complex to check against the pattern.- Giá trị vi phạm bị API từ chối kèm tên trường, và bảng có ràng buộc
CHECKnên ghi thẳng vào cơ sở dữ liệu cũng bị chặn. - Siết hoặc thêm ràng buộc trên bảng đã có dòng vi phạm thì kế hoạch bị từ chối và nêu số dòng vi phạm; nới hoặc bỏ ràng buộc thì kế hoạch ở mức
SAFE.
Bắt buộc có điều kiện
required_when làm một trường chỉ bắt buộc khi một trường khác của thực thể có giá trị nhất định:
note: {type: text, required_when: "kind == Phần mềm"}
- Điều kiện là một phép so sánh, viết như
whencủa hành động:==và!=cho mọi kiểu,<,<=,>,>=chỉ cho số và ngày. - Trường được so sánh là
number,date,text,choicemột lựa chọn hoặcboolean(foreign == true) của cùng thực thể. - Giá trị của trường
dateviết nhưYYYY-MM-DD, ví dụdue >= 2026-01-31; ngày không có thật bị từ chối khi đọc mô hình. - API kiểm khi tạo và khi sửa, trên hồ sơ sau khi gộp giá trị mới; trường còn trống thì báo
is required when kind == Phần mềm. - Không đi cùng
required, không đặt trên trườngbooleanhayfile, và không so sánh trường với chính nó. - Chỉ kiểm ở API, cơ sở dữ liệu không có ràng buộc này.
Giao diện ui
Khối ui của một thực thể chọn cách nó hiện trên màn hình; không có thì giao diện dựng theo thứ tự các trường:
ui:
icon: inventory
menu: {group: Kho, order: 1}
list: {columns: [code, kind, price], sort: -created_at}
form:
groups:
- {label: Nhận dạng, fields: [code, kind]}
- {label: Chi tiết, fields: [price, bought_on]}
hints: {code: "Ba chữ in hoa, dấu gạch ngang, bốn chữ số"}
iconlà một trongdescription,folder,inbox,person,group,school,assignment,event,room,computer,build,inventory,payments,support,shield,settings,list,calendar,chat,local_shipping.menu.groupgom các thực thể thành một nhóm trong menu vàmenu.orderlà thứ tự.list.columnslà các cột của danh sách: trường của thực thể, hoặccreated_at,updated_at, vàstatus,assigneekhi thực thể có quy trình.list.sortlà tên cột, thêm dấu-ở đầu để sắp giảm dần.form.groupschia form thành nhóm có nhãn; trường không nằm trong nhóm nào xếp vào nhóm cuối.hintsđặt dòng gợi ý dưới ô nhập của một trường.uichỉ chọn trong những gì giao diện đã có và không đổi quyền; sai tên trường, cột hay biểu tượng thì tệp bị từ chối kèm dòng và cột.- Cột mà người dùng chọn bằng nút Cột được giữ trong trình duyệt và đè lên cột mặc định của
ui. - Đổi
uilà thay đổiSAFE, không đụng dữ liệu, và áp dụng được cả khi thực thể còn hồ sơ đang xử lý.
Ví dụ đầy đủ ở asset_register.yaml.
Quyền theo vai
access gán cho mỗi vai một mức:
| Mức | Ý nghĩa |
|---|---|
all | Mọi dòng, đọc và ghi |
own | Dòng của mình |
read | Mọi dòng, chỉ đọc |
unit | Dòng của đơn vị mình |
assigned | Dòng được giao cho mình |
owner_via cho thực thể con theo chủ sở hữu của thực thể cha, qua nhiều cấp.
Quy trình
handlerlà vai xử lý, hoặc một danh sách vai như[MANAGER, SELLER]; ai giữ một trong các vai đó thì xử lý được.familychọn một họ mẫu để bắt đầu:approval,work_itemhoặcreservation; bỏ trống thì tự khai báo đủstatesvàactions.deadlinelà hạn xử lý tùy chọn (ví dụ72h).escalatelà danh sách tối đa 5 mức leo thang tính từ lúc hồ sơ quádeadline, nên quy trình phải khaideadline. Mỗi mức khaiafter(thời gian sau hạn) vàto(một vai hoặc danh sách vai, mỗi vai phải đọc được hồ sơ), cùngrepeat: {every: 12h, times: 3}nếu muốn nhắc lại; bỏrepeatthì mỗi mức gửi một lần. Ví dụ:escalate: [{after: 24h, to: MANAGER}, {after: 72h, to: [DIRECTOR], repeat: {every: 12h, times: 3}}]. Leo thang chỉ ghi dòng lịch sửescalatedvà gửi thông báo qua webhook của mô hình, không đổi trạng thái, người giữ hồ sơ hay quyền của ai. Dịch vụ tắt rồi chạy lại thì chỉ gửi thông báo mới nhất đã đến hạn, và hồ sơ vào hạn mới thì tính lại từ đầu.- Họ mẫu bắt buộc có lý do khi từ chối và trả lại; quy trình tự khai báo đặt
needs_note: truecho từng hành động cần lý do. - Người nộp chỉ rút lại được hồ sơ ở các trạng thái khai trong
withdraw; quy trình không khaiwithdrawthì không cho rút lại. - Hồ sơ có quy trình không xóa được, hồ sơ đã được quyết định thì không sửa được, và hồ sơ đã giao thì chỉ người được giao xử lý được.
- Người tạo hồ sơ không tự quyết định được, trừ khi khai báo
allow_self_decision: true.
Tự khai báo hoặc mở rộng quy trình
stateslà bản đồ từ tên trạng thái sang{label, terminal};initiallà trạng thái hồ sơ mới vào, mặc định là trạng thái khai báo đầu tiên.actionslà bản đồ từ tên hành động sang{label, from, to, by, role, needs_note, require, when, check}.fromlà một trạng thái hoặc một danh sách,bylàhandler(mặc định) hoặcowner.rolegiới hạn một hành động của người xử lý cho vai riêng thay vì cảhandler. Vai ghi ởrolekhông cần có tronghandler; người giữ vai đó vẫn thực hiện được hành động. Nútlabelđể trống thì giao diện hiện mã hành động.needs_note: truebắt buộc có lý do.requireliệt kê trường phải có giá trị trước khi hành động được thực hiện.whenlà một phép so sánh một trường của hồ sơ với một giá trị, viết thành chuỗitrường toán_tử giá trị, ví dụwhen: "amount > 5000000". Hành động chỉ thực hiện được khi phép so sánh đúng với hồ sơ ở lúc thực hiện. Toán tử là==,!=,<,<=,>hoặc>=. Trường là trườngnumber,date,choice,texthoặcbooleancủa thực thể;<,<=,>và>=chỉ dùng cho trườngnumbervàdate. Giá trị của trườngnumberlà số, của trườngdatelà ngàyYYYY-MM-DD, của trườngchoicelà một trongoptionscủa nó. Trường chưa có giá trị thì không đạt điều kiện nào.whenchỉ dùng cho hành động của người xử lý, nên không dùng được vớiwithdrawvà hành động củaauto_close. Viếtwhen: nullđể bỏ điều kiện của một hành động trong họ mẫu. Hành động không đạt điều kiện trả 409ERR_INVALID_STATEvớidata.reasonlàCONDITION_NOT_MET.check: <tên đích>cho một dịch vụ riêng quyết định hành động trước khi hồ sơ chuyển trạng thái. Tên đích khai trongdeploy/webhooks/targets.ymlnhư đích củawebhook; tên chưa có trong tệp thì mô hình bị từ chối. Dịch vụ được hỏi sau khi mọi quy tắc của quy trình đã đạt và trước khi trạng thái đổi. Hành động bị từ chối trả 403ERR_ACTION_NOT_ALLOWEDvớidata.reasonlàCHECK_DENIEDvàdata.codelà mã dịch vụ trả về. Dịch vụ không trả lời hoặc trả lời sai thì cách xử lý doon_errorcủa đích quyết định, cách khai và giao thức ở Tích hợp với hệ thống ngoài. Hành động tự đóng củaauto_closekhông hỏi dịch vụ.- Khi có
family, mục khai báo ghi đè từng khóa của khung; viếtnullđể bỏ một trạng thái hoặc hành động của khung. withdrawvà trạng tháiwithdrawnlà tên dành riêng: khaiwithdraw: {from: [...]}thì nền tảng tự thêm trạng tháiwithdrawn, và hành động này luôn do người nộp thực hiện.- Tên hành động
created,updated,deleted,assigned,file_added,file_removed,completion_skipped,auto_closed,overdue,due_soon,escalated,check_denied,check_unavailablevàcheck_skippedlà tên dành riêng, vì lịch sử hồ sơ dùng chúng cho các dòng do nền tảng ghi. - Mỗi trạng thái không phải cuối phải có hành động đi ra, và ít nhất một hành động đi ra không có
when, để hồ sơ luôn có lối đi; mọi trạng thái phải tới được từinitial, trạng thái cuối không có hành động đi ra, và phải có ít nhất một trạng thái cuối. auto_closelà thời gian chờ người nộp trước khi hệ thống thay họ làm một hành động. Họwork_itemnhận dạng ngắnauto_close: 7d(hành độngconfirm); các trường hợp khác viếtauto_close: {after: 7d, action: <hành động của người nộp>}.- Quy trình khác khung gốc chạy trên BPMN riêng, sinh từ các trạng thái và hành động khai báo khi áp dụng mô hình.
- Đổi trạng thái đầu, thêm hoặc bỏ trạng thái, hay đổi
from,to,by,whencủa một hành động khi còn hồ sơ chưa ở trạng thái cuối thì kế hoạch bị từ chối. - Đổi nhãn,
role,require, các trạng thái củawithdrawhay danh sáchhandlerthì an toàn và có hiệu lực ngay, kể cả với hồ sơ đang mở. - Bỏ một trạng thái còn hồ sơ nằm ở đó, hoặc bỏ
terminalcủa trạng thái còn hồ sơ đã đóng, cũng bị từ chối, vì hồ sơ đã đóng không chạy tiếp được.
process:
handler: [MANAGER, SELLER]
states:
todo: {label: Mới}
review: {label: Đang xem}
done: {label: Xong, terminal: true}
actions:
take: {from: todo, to: review, role: SELLER}
finish: {from: review, to: done, role: MANAGER, require: [amount]}
withdraw: {from: todo}
Hai hành động có when loại trừ nhau chia hồ sơ theo giá trị một trường; hành động không có when luôn là lối thoát:
states:
lead_approved: {label: Chờ giám đốc}
actions:
lead_approve: {from: submitted, to: approved, role: LEAD, when: "amount <= 5000000"}
lead_forward: {from: submitted, to: lead_approved, role: LEAD, when: "amount > 5000000"}
lead_reject: {from: submitted, to: rejected, role: LEAD, needs_note: true}
approve: {from: lead_approved, to: approved, role: DIRECTOR}
Đặt chỗ
family: reservation (có thể mở rộng như trên) kèm booking: {resource, starts, ends, capacity}.
Lượt đặt làm số lượt chạy cùng lúc vượt sức chứa thì bị từ chối, và ứng dụng có chế độ xem lịch.
Ví dụ ở room_booking.yaml.
Hành động hoàn tất
after gán danh sách thao tác cho một trạng thái cuối, ví dụ after: {approved: [{do: add_to_group, user: created_by, group_from: nhom}]}.
Thao tác chạy sau khi giao dịch xong và được thử lại nếu lỗi.
Thao tác có sẵn là add_to_group và remove_from_group.
Nhóm Keycloak phải có sẵn; thiếu thì thông điệp xem được ở tab Hàng đợi sự kiện.
Trường người dùng hoặc nhóm để trống thì thao tác bị bỏ qua và hồ sơ có thêm dòng lịch sử completion_skipped kèm lý do.
Ví dụ ở itaccess.yaml.
Tài liệu in
Khóa documents của một thực thể khai báo các mẫu in; mỗi mẫu biến một hồ sơ thành một tệp PDF.
Một mẫu có tên ([a-z][a-z0-9_]*), và các khóa label, file, when, title và body.
documents:
confirmation:
label: Giấy xác nhận
file: giay-xac-nhan-{{id}}
when: approved
title: GIẤY XÁC NHẬN
body:
- heading: Thông tin chung
- text: "Xác nhận {{full_name}} đã nộp hồ sơ số {{id}}."
- fields: [full_name, created_at]
- signatures: [Người nộp, Cán bộ phụ trách]
labellà tên mẫu ở màn hình hồ sơ; không có chỗ trống.filelà tên tệp tải về không kèm.pdf; chữ có dấu thành chữ không dấu, và ký tự ngoài chữ, số,.,-,_thành_.whenlà một trạng thái hoặc danh sách trạng thái của quy trình mà hồ sơ phải ở trong đó mới in được; bỏ đi thì in ở mọi trạng thái, và thực thể không có quy trình thì không dùngwhen.titlein ở giữa đầu trang đầu.bodylà danh sách các khối, mỗi khối có đúng một khóa:heading: dòng tiêu đề đậm.text: văn bản; mỗi dòng xuống dòng là một dòng của trang và dòng trống là một khoảng cách.fields: bảng nhãn và giá trị cho từng trường được kể tên; giá trị rỗng in—.signatures: từ một đến bốn tiêu đề ký, đặt cạnh nhau trên một khoảng trống để ký.
Chỗ trống {{tên}} trong file, title, heading, text và signatures được thay bằng giá trị của hồ sơ.
Tên là một trường của thực thể, hoặc một cột mọi hồ sơ có: id, created_at, updated_at, và với thực thể có quy trình thêm status và decided_at.
Mẫu không có điều kiện, vòng lặp hay biểu thức, và không đọc dữ liệu ngoài hồ sơ đang in.
Giá trị in như sau: ngày dd/MM/yyyy, thời điểm dd/MM/yyyy HH:mm theo múi giờ của máy chủ, có hoặc không thành Có hoặc Không, trạng thái bằng nhãn của nó, đơn vị bằng nhãn đơn vị, trường nhiều lựa chọn cách nhau bằng dấu phẩy.
Trường tham chiếu và trường người dùng in giá trị lưu của chúng.
Nhãn của cột id, status, created_at, updated_at và decided_at trong bảng là Mã, Trạng thái, Ngày tạo, Cập nhật lần cuối và Ngày quyết định.
Mỗi thực thể có tối đa 10 mẫu, mỗi mẫu tối đa 60 khối, mỗi văn bản tối đa 2000 ký tự và mỗi tài liệu tối đa 50 trang.
plan và apply từ chối mẫu có chỗ trống không phải trường, trạng thái không có trong quy trình, khối lạ hay quá giới hạn, kèm dòng và cột.
Một mẫu đổi là thay đổi mức SAFE (CHANGE_DOCUMENTS).
GET /api/v1/data/{model}/{entity}/{id}/documents liệt kê các mẫu của hồ sơ, tên tệp và việc hồ sơ in được ở trạng thái hiện tại hay không.
GET /api/v1/data/{model}/{entity}/{id}/documents/{tên} trả tệp PDF dạng đính kèm.
Cả hai chỉ cho người đọc được hồ sơ, như màn hình hồ sơ; mẫu ngoài trạng thái cho phép trả 409 với lý do DOCUMENT_NOT_AVAILABLE, và mỗi lần in được ghi vào audit_log (DOCUMENT_PRINTED).
Tệp đính kèm
Trường type: file; tải lên bằng POST /api/v1/data/{model}/{entity}/{id}/files, quyền theo quyền của bản ghi.
Loại tệp nhận được đặt bằng engine.files.allowed-extensions, và tệp luôn tải về dạng đính kèm.
Mỗi hồ sơ giữ tối đa 20 tệp, đặt bằng engine.files.max-per-record.
Webhook
webhook: <tên đích> ở đầu tệp chọn nơi nhận lịch sử hồ sơ của mô hình.
Địa chỉ và bí mật của đích nằm trong deploy/webhooks/targets.yml, ngoài git; mẫu ở deploy/webhooks/targets.example.yml.
Mô hình không khai báo thì dùng DXOS_WEBHOOK_URL, và tên đích chưa có trong tệp thì mô hình không áp dụng được.
Mỗi đích có format: json (mặc định) hoặc format: chat.
Tin của dòng escalated có thêm level (mức, từ 1) và round (lần nhắc, từ 0), và tin chat nêu vai nhận.
Đổi mô hình khi đã có dữ liệu
renamed_fromkhai báo tên cũ khi đổi tên trường, để giữ nguyên dữ liệu.defaultđiền giá trị cho trường bắt buộc mới trên bảng đã có dòng; trường nhiều lựa chọn nhận một danh sách.- Đổi kiểu của một trường đang có (kể cả từ một lựa chọn sang nhiều lựa chọn) bị từ chối; thêm một trường mới thay vì đổi kiểu.
- Đổi tên một trường có
min,maxhaypatterngiữ nguyên dữ liệu và đổi tên cả các ràng buộc của nó. - Xem trước, áp dụng, quay về và các lệnh liên quan ở Cài đặt và vận hành và API.