@digiforce-nc/plugin-action-template-print

Plugin cung cấp in theo template (DOCX/XLSX) - admin upload template Word/Excel chứa placeholder, hệ thống render dữ liệu bản ghi vào template qua Carbone engine, hỗ trợ QR code và hình ảnh.

Plugin này làm gì?

Hãy hình dung bạn cần in hóa đơn, hợp đồng, phiếu xuất kho - mỗi loại có mẫu riêng với logo, bảng dữ liệu, QR code. Thay vì code từng mẫu, admin chỉ cần upload file DOCX/XLSX chứa placeholder (VD: {d.customerName}, {d.items[i].price}). Khi user nhấn in, server lấy dữ liệu bản ghi → render vào template qua Carbone engine → trả file kết quả.

Ba nhiệm vụ chính

#	Nhiệm vụ	Chi tiết
1	Quản lý template	Collection `printingTemplates` lưu trữ template với metadata (collection, data source, format)
2	Render dữ liệu	Carbone engine thay placeholder bằng dữ liệu thực, hỗ trợ loop, condition, format
3	QR code & hình ảnh	Tự động tạo QR code và nhúng hình ảnh từ attachment field vào kết quả

Kiến trúc

Tổng quan

Plugin có cả server (collection template, render pipeline, Carbone engine) lẫn client (UI quản lý template, nút action in). Template file lưu trên filesystem tại storage/print-templates/.

Tầng	Vai trò	Thành phần
Client UI	Quản lý template + nút action in	`TemplateManager`, `RecordActionWidget`
Server Collection	CRUD metadata template	`printingTemplates`
Render Pipeline	Chuẩn bị data, resolve attachments, QR	Render pipeline
Carbone Engine	Render data vào template DOCX/XLSX	`carbone`
File Storage	Lưu file template gốc	`storage/print-templates/`

API endpoints

Endpoint	Method	Mô tả
`{collection}:templatePrint`	POST	Render dữ liệu bản ghi vào template, trả file kết quả
`printingTemplates:upload`	POST	Upload template mới
`printingTemplates:download`	GET	Tải file template gốc
`printingTemplates` CRUD	GET/POST/PUT/DELETE	Quản trị metadata template (admin)

templatePrint - Request

Tham số	Kiểu	Mô tả
`filterByTk`	string/number	ID bản ghi cần in
`templateName`	string	Tên template sử dụng

ACL - Phân quyền

Quyền	Loại	Mô tả
`ui.templatePrint`	Snippet	ACL snippet cho phép truy cập UI template print
`templatePrint`	Action	Cho phép user đã đăng nhập thực hiện in
On install	Strategy	Tự động thêm vào admin và member role strategies

Database

Bảng `printingTemplates`

Cột	Kiểu	Mô tả
`name`	string	Tên định danh template (unique)
`title`	string	Tên hiển thị
`collectionName`	string	Collection mà template áp dụng
`rootDataType`	string	Loại dữ liệu gốc (single record / list)
`dataSource`	string	Data source sử dụng
`filename`	string	Tên file template trên filesystem
`enabled`	boolean	Template có đang hoạt động

File storage

Template file được lưu tại storage/print-templates/ trên server filesystem. Khi upload template mới, file được copy vào thư mục này với tên duy nhất.

Luồng hoạt động

Carbone placeholder

Template sử dụng cú pháp Carbone cho placeholder:

Cú pháp	Mô tả	Ví dụ
`{d.field}`	Field đơn giản	`{d.customerName}`
`{d.items[i].field}`	Loop qua mảng	`{d.items[i].productName}`
`{d.field:formatN(2)}`	Format số	`{d.total:formatN(2)}`
`{d.field:formatD(DD/MM/YYYY)}`	Format ngày	`{d.createdAt:formatD(DD/MM/YYYY)}`
`{d.field:ifEQ(value)}...{d.field:showEnd}`	Điều kiện	Hiện/ẩn block theo giá trị

Thành phần client

Thành phần	Mô tả
`TemplatePrintActionProvider`	Provider cho nút action template print
`TemplatePrintRecordActionWidget`	Widget nút in cho row action (in một bản ghi)
`TemplatePrintCollectionActionWidget`	Widget nút in cho collection action (in nhiều bản ghi)
`TemplateManagerUI`	UI quản lý template: upload, xem danh sách, xóa, tải về
`TemplatePrintDesigner`	Cấu hình action trong designer (chọn template, format)

Dependencies

Package	Vai trò
`@digiforce-nc/actions`	Action context types (peer)
`@digiforce-nc/database`	Database ORM (peer)
`@digiforce-nc/server`	Server framework (peer)
`@digiforce-nc/client`	Client framework (peer)
`@digiforce-nc/plugin-file-manager`	Quản lý file upload/storage (peer)
`carbone`	Template render engine - DOCX/XLSX (dev)
`qrcode`	Tạo QR code nhúng vào template (dev)
`jsdom`	DOM manipulation cho image handling (dev)