Incomex AI Portal
KB-1123

NĐ-LARK-PG-DIR — Chốt lựa chọn PDF engine v1

3 min read Revision 1
larkpgdirectuspdfgotenbergdecisiongpt

NĐ-LARK-PG-DIR — Chốt lựa chọn PDF engine v1

Trạng thái: DRAFT quyết định kỹ thuật Tác giả: Incomex Hội đồng AI / GPT Ngày: 2026-04-12 Phạm vi: Chốt công cụ tạo file PDF cho hướng Lark → PG → Directus → PDF/Nuxt

1. Quyết định

Ưu tiên số 1: Gotenberg

Lý do chốt:

  • Có API REST sẵn, phù hợp mô hình gọi từ Directus/API layer.
  • Chạy dạng Docker service, hợp với cách triển khai hiện tại.
  • Render từ HTML/CSS bằng Chromium nên phù hợp với các mẫu văn bản có:
    • logo công ty,
    • dấu đỏ dạng ảnh,
    • bảng biểu,
    • bố cục A4 cố định,
    • tiếng Việt/Unicode.
  • Không bắt đội phải học markup mới ở vòng đầu.

2. Đánh giá theo mẫu file mục tiêu

Mẫu file mục tiêu hiện tại là loại văn bản hành chính/bán pháp lý có các đặc điểm:

  • logo ở đầu trang,
  • dấu đỏ chèn lên trang,
  • tiêu đề lớn,
  • bảng nhiều dòng/cột,
  • footer/header lặp lại,
  • dữ liệu phần lớn đổ ra từ dữ liệu nguồn.

Với loại file này, Gotenberg vẫn là lựa chọn số 1 cho giai đoạn đầu.

Vì sao vẫn phù hợp

  • Logo và dấu đỏ chỉ là lớp ảnh/overlay trong template HTML/CSS.
  • Bảng biểu và căn trang 2 trang A4 là thế mạnh thực tế của Chromium render.
  • Có thể thiết kế template cố định rồi chỉ đổ dữ liệu động vào.
  • File mục tiêu không đòi hỏi ký số pháp lý trong giai đoạn đầu; chỉ cần hiển thị dấu đỏ và chữ ký sẵn.

3. Ranh giới cần hiểu rõ

3.1. Gotenberg phù hợp khi

  • file là PDF render từ template cố định,
  • chữ ký/con dấu là ảnh hoặc lớp đồ họa có sẵn,
  • dữ liệu biến đổi theo record,
  • cần gọi API đơn giản.

3.2. Gotenberg không phải công cụ ký số pháp lý

Nếu sau này cần ký số PDF chuẩn pháp lý, đó là bài toán khác và cần thêm lớp ký số riêng sau bước render.

4. Phương án dự phòng

Fallback số 1: Typst

Chỉ cân nhắc Typst khi xuất hiện một trong các tình huống:

  • cần kiểm soát typography/dàn trang chặt hơn HTML,
  • cần văn bản nhiều trang dài và cực ổn định về layout,
  • chấp nhận viết thêm wrapper service.

Ở giai đoạn hiện tại, Typst chưa nên là lựa chọn đầu vì tăng chi phí tích hợp.

5. Khuyến nghị triển khai

  1. Chốt Gotenberg là PDF engine mặc định cho hướng lark_PG_Dir.
  2. Thiết kế 1 template HTML A4 theo mẫu văn bản thực tế.
  3. Gắn logo và dấu đỏ dưới dạng asset cố định.
  4. Đổ dữ liệu động từ Directus API vào template.
  5. Gọi Gotenberg để sinh PDF.
  6. Nuxt chỉ hiển thị file kết quả hoặc link tải.

6. Kết luận ngắn

Với mẫu đầu ra hiện tại, Gotenberg vẫn là lựa chọn hợp lý nhất và nên chốt ưu tiên số 1. Chỉ khi phát sinh yêu cầu dàn trang rất đặc thù hoặc ký số pháp lý mới cần mở thêm phương án khác.