ADR-0003. Render PDF HKD chính thức bằng Typst

Trường	Giá trị
Status	Accepted
Date	2026-03-30
Deciders	Phat Nguyen
Supersedes	-

Bối cảnh

• Sổ HKD là biểu mẫu chính thức của nhà nước với bố cục nghiêm ngặt: tiêu đề đặt chính xác, khối chữ ký, quy ước viết số/ngày kiểu Việt Nam, bảng nhiều trang và bản dọc/ngang theo từng mẫu.
• Cùng một bộ dữ liệu đã kiểm chứng cũng phải sinh ra một file XLSX có thể chỉnh sửa (do ExcelJS xử lý riêng).
• Chúng ta cần file PDF ổn định đến từng pixel, sẵn sàng để in, mà designer có thể chỉnh đi chỉnh lại không cần biên dịch lại service.

Quyết định

Chúng ta sẽ render PDF bằng Typst qua @myriaddreamin/typst-ts-node-compiler. Các template tồn tại dưới dạng mã nguồn .typ trong resources/templates/ (6 mẫu + common.typ dùng chung); PdfGeneratorService khởi tạo trễ một NodeCompiler duy nhất, đưa dữ liệu đã kiểm chứng vào dưới dạng shadow file (data.json), rồi render. Mỗi consumer có một instance service riêng, nên đường dẫn shadow file cố định không bị dùng chung đồng thời. Các file previews/ độc lập cho phép chạy typst compile để soi lỗi bố cục mà không cần chạy toàn bộ pipeline.

Hệ quả

Ưu	Nhược
Template dạng markup, quản lý theo version; chỉnh sửa nhanh	Một ngôn ngữ mới với team so với HTML/CSS
Hỗ trợ sẵn bảng nhiều trang, typography chính xác, nhúng font	Compiler là phụ thuộc native; cần đóng gói kèm font
Macro chung trong common.typ giữ 6 mẫu nhất quán	Việc cô lập shadow file dựa vào giả định mỗi consumer một service
Preview --root . cho phép kiểm tra trực quan nhanh	Một lỗi biên dịch buộc phải thay instance compiler

Phương án đã cân nhắc

Phương án	Ưu	Nhược	Vì sao loại
Headless Chromium (HTML→PDF)	HTML/CSS quen thuộc	Runtime nặng, ngắt trang dễ hỏng, tốn bộ nhớ	Quá nặng để render theo batch; kiểm soát ngắt trang kém
LaTeX	Typography xuất sắc	Bộ công cụ cồng kềnh, chậm, khó dựng template từ JSON	Bất tiện khi vận hành
Thư viện PDF (pdf-lib / PDFKit)	Thuần JS	Phải tự dựng bố cục cho bảng nhiều trang phức tạp	Quá thấp cấp cho các bố cục đa mẫu chính thức

Tham chiếu

• ledger/src/services/generators/pdf-generator.service.ts
• ledger/resources/templates/ (common.typ, s1a-hkd.typ..s2e-hkd.typ)
• HKD Templates