Wizard Render Doc từ template

Wizard Render Doc từ template

Wizard chính để generate document từ template + record. Đầu ra: file .docx với Jinja placeholders replaced by data thực.

Vị trí trigger

Trên form các model:

• Hợp đồng (Zone Contract) → nút ”📝 Render từ template”
• Báo giá (Sale Order) → nút ”📝 Render từ template”
• Đặt cọc (Zone Deposit Agreement) → nút ”📝 Render từ template”
• Phụ lục (Zone Contract Amendment) → nút ”📝 Render từ template”
• Chấm dứt (Zone Contract Termination) → nút ”📝 Render từ template”

Wizard flow

1. Click nút ”📝 Render từ template”

Modal wizard mở.

2. Chọn template

Dropdown “Template” — hiện các template active có model = <current model>.

Filter mặc định:

• Language matches partner: nếu KH FDI → show templates en_US first
• Category: theo context (Contract / Quotation / Deposit / …)

Vd HĐ Contract → dropdown show:

• HĐ thuê đất chuẩn 2026 v2
• HĐ thuê đất FDI (bilingual VN/EN)
• HĐ RBF (nhà xưởng có sẵn)
• HĐ Yard (sân bãi)

3. Preview data (optional)

Nút ”👁 Preview data” → modal show record data sẽ được inject vào template:

{
  "record": {
    "name": "ZC-2026-042",
    "customer_id": {
      "name": "Cty TNHH Hoa Biết",
      "vat": "12545522",
      ...
    },
    "project_id": {
      "name": "KCN Tân Hoà",
      "investor_id": { ... }
    }
  },
  "company": { ... },
  "today": "2026-08-15"
}

Verify data trước khi render. Nếu thiếu field → back to record → fill.

4. Custom filename (optional)

Field “Filename” — default HD_ZC-2026-042_Hoa_Biet.docx. Đại có thể sửa:

• Include date: HD_ZC-2026-042_Hoa_Biet_2026-08-15.docx
• Include version: HD_ZC-2026-042_v3.docx

5. Choose target

Radio:

• Attach to record (default): file lưu vào record.attachment_ids
• Download: trả file trực tiếp cho browser, không lưu
• Both: attach + download

6. Click ”🚀 Render”

Wizard chạy:

1. Load template .docx binary
2. Prepare context (record + company + today + user)
3. Call docxtpl.render(context)
4. Save output binary
5. Attach hoặc download

Mất 1-3 giây tùy template size.

7. Post-render

• Nếu Attach: refresh Chatter → thấy attachment với filename
• Nếu Download: browser tự save file
• Auto-log Chatter: “Rendered from template <T> lúc HH:MM by <user>”

Post-actions

Sau khi render:

Option A: Edit inline OnlyOffice

Click attachment file → mở OnlyOffice iframe → edit → save

Option B: Convert PDF

Click nút ”📑 Convert to PDF” → LibreOffice CLI convert → PDF attach cùng record

Chi tiết: Auto-convert PDF

Option C: Send by Email

Click ”📧 Send to KH” → modal compose email với PDF (hoặc .docx) attached → gửi.

Bulk render (multi-record)

Render cho nhiều records cùng lúc:

1. Menu list view (vd Contracts list) → tick chọn 10 records
2. Menu Action → ”📝 Bulk Render Documents”
3. Chọn template
4. Wizard render 10 records với progress bar
5. Output: 10 attachments per record + zip download

Mất 30-60s cho 10 docs. Không recommended > 50 docs cùng lúc (server overhead).

Language routing

Wizard auto-pick template theo partner language:

1. Get partner.lang (vd 'en_US')
2. Search templates với language = en_US
3. Nếu không có → fallback vi_VN
4. Nếu vẫn không → error "No template found for language"

Đại có thể override manual — chọn template khác trong dropdown.

Preview render (before commit)

Nếu Đại chưa chắc chắn template render đúng:

1. Chọn template + record
2. Click ”🧪 Test render” thay vì “Render”
3. Wizard render nhưng KHÔNG attach vào record
4. Download output → verify data đúng
5. Nếu OK → click Render thật

Test render không log vào Chatter, không attach — safe để try nhiều lần.

Escape errors

Missing field

Nếu template có {{ record.x_custom_field }} mà record không có field đó:

• Default: UndefinedError → wizard show error message
• Bypass: Admin config undefined = 'skip' → render với {{ ... }} giữ nguyên (bad output)

Recommended: fix template, không bypass.

Invalid Jinja syntax

Nếu template có Jinja lỗi (thiếu }}, sai endfor):

• Wizard show error line number
• Đại tải template → sửa Word → re-upload

Xem Troubleshoot.

Wizard permission

• Sales rep: render OK
• FC: render OK
• Manager: render OK
• Admin: render + edit template

Không hạn chế render — mọi user có quyền xem record đều render được.

Advanced: custom render context

Đại có thể extend context truyền vào Jinja:

1. Dev mode → Cấu hình → Technical → Doc Engine → Context Extenders
2. Add Python function:

   def get_extra_context(record):
       return {
           'weather_today': get_weather_api(record.project_id.city),
           'exchange_rate': get_forex_rate(),
       }

3. Template có thể dùng {{ weather_today }} / {{ exchange_rate }}

Rare use case, nhưng hữu ích cho template dynamic (vd HĐ tự tính giá theo tỷ giá hôm ký).

Best practices

Mẹo

• Test template trên record mẫu trước khi dùng production
• Attach output thay vì Download-only — giữ audit trail
• Filename có ID record — dễ tìm sau này
• Convert PDF ngay sau render — Word có thể bị modify accidentally, PDF là snapshot
• Send email PDF thay vì .docx — Word có thể mở khác nhau trên KH’s device

FAQ

Wizard không thấy template nào

• Verify template có active = True
• Verify template model match model của record (vd Contract → template model=zone.contract)
• Verify template ownership: nếu Đại không có quyền → không thấy

Render báo lỗi “template file corrupted”

• Template .docx bị hư khi upload
• Re-download template → verify mở được trong Word
• Re-upload

Render output size lớn (100 MB+)

• Template có ảnh embed lớn
• Compress ảnh trong Word trước upload
• Hoặc dùng ảnh CDN link thay vì embed

Muốn render lại HĐ đã render với data mới

• Mở record → click “Render” lại → chọn cùng template
• Wizard render mới → attach thêm (không overwrite cũ)
• Rename old attachment hoặc delete nếu không cần

Liên kết liên quan

• Mẫu tài liệu
• OnlyOffice edit sau render
• Convert PDF
• Troubleshoot