Biểu mẫu tài liệu & merge field

govex-cloud-template quản lý biểu mẫu Word (DOCX), merge field, snapshot phiên bản và sinh văn bản DOCX/PDF/HTML từ dữ liệu entity. Dùng khi service cần sinh văn bản điện tử từ biểu mẫu và cho người dùng chỉnh sửa bản đã sinh.

Khi nào sử dụng

Quản lý tập biểu mẫu Word theo code, loại biểu mẫu (TYPE_1, TYPE_2, TYPE_3) và trạng thái hiệu lực.
Upload file DOCX và để dependency quét, chuẩn hóa danh sách merge field phục vụ binding dữ liệu.
Sinh văn bản với dữ liệu lấy từ entity nghiệp vụ, hệ thống hoặc biểu thức tính toán.
Khóa merge field trên bản DOCX đầu ra để người dùng không sửa được dữ liệu hệ thống.
Theo dõi lịch sử sinh/chỉnh sửa văn bản và hủy bản sinh khi chưa hoàn thành.

Cài đặt

<dependency>
    <groupId>vn.govex.cloud</groupId>
    <artifactId>govex-cloud-template</artifactId>
</dependency>

Dependency này kéo theo các dependency nội bộ cần thiết (govex-cloud-aspose, govex-cloud-oss). Version do BOM quản lý, xem Cài đặt.

Cấu hình

Property	Mô tả	Mặc định
`govex.template.enabled`	Bật dependency template; phải khai báo `true` tường minh, nếu thiếu property thì auto-configuration không đăng ký	— (không bật)
`govex.template.merge-field-locale`	Locale dùng khi định dạng merge field	`vi-VN`
`govex.template.merge-field-zone-id`	Múi giờ dùng khi định dạng merge field có instant/offset	`Asia/Ho_Chi_Minh`

govex:
  template:
    enabled: true
    merge-field-locale: vi-VN
    merge-field-zone-id: Asia/Ho_Chi_Minh

Sử dụng

Upload file biểu mẫu; dependency quét MERGEFIELD và chuẩn hóa các marker {{field}}, [[field]], «field»:

PUT /api/v1/templates/{id}/file
Content-Type: multipart/form-data

Xem danh sách merge field để binding dữ liệu:

GET /api/v1/templates/{id}/merge-fields
GET /api/v1/templates/{id}/merge-fields/inspect

Sinh văn bản:

POST /api/v1/templates/{id}/generate
Content-Type: application/json

{
  "entityType": "HO_SO",
  "entityId": "1776726e-8292-453a-9ab4-beeccc763a20",
  "outputFormat": "DOCX",
  "entityData": { "maHoSo": "HS-2026-001", "tenDoiTuong": "Nguyễn Văn A" },
  "idempotencyKey": "gen-2026-001"
}

Kết quả trả về gồm generationId, fileUrl, fileName, format, editStatus, onlyofficeEditUrl (với DOCX), outputHash, warningCodes. Dùng generationId cho các thao tác tiếp theo:

GET /api/v1/templates/{id}/generations
PUT /api/v1/templates/{id}/generations/{genId}/finalize

Trong service có thể inject DocumentGenerationService (các method generateDocument, previewDocument, getGenerationHistory, finalizeGeneration, cancelGeneration) và TemplateService (listTemplates, createTemplate, updateTemplate, deleteTemplate, uploadTemplateFile) để gọi trực tiếp thay vì qua REST.

Giá trị merge field được phân giải theo sourceType: ENTITY, SYSTEM, COMPUTED, BUILTIN; nguồn API bị từ chối. Cơ chế khóa field theo loại biểu mẫu: TYPE_1 khóa các field có lockedInOutput, TYPE_2 khóa toàn bộ field đã binding, TYPE_3 không khóa.

Luồng hoạt động

Sơ đồ dưới đây mô tả luồng sinh văn bản: upload biểu mẫu → quét và chuẩn hóa merge field ({{field}}, [[field]], «field») → DocumentGenerationService.generateDocument → Aspose merge → DOCX/PDF (kèm URL OnlyOffice khi đầu ra DOCX).

Lưu ý

Cần datasource/JPA và changelog classpath db/changelog/template/changelog-master.yaml include trong changelog master của ứng dụng.
Cần bean Storage của govex-cloud-oss để lưu file biểu mẫu và file đầu ra; cần license Aspose hợp lệ (qua govex-cloud-aspose) để merge.
Chỉ template có status = ACTIVE và đã có file mới sinh được văn bản.
Cùng idempotencyKey sẽ trả lại kết quả cũ (trừ khi lần trước đã CANCELLED); cancelGeneration xóa file đầu ra và không hủy được bản đã FINALIZED.
renderApprovedContent chỉ hỗ trợ DOCX/PDF, dùng cho nội dung đã được con người phê duyệt.
Xóa template là xóa mềm (status = DELETED); các endpoint /api/v1/templates/**, /api/v1/builtin-merge-fields/** đi qua policy host của govex-cloud-security.

Khi nào sử dụng​

Cài đặt​

Cấu hình​

Sử dụng​

Luồng hoạt động​

Lưu ý​