solution-erp/.claude/skills/form-engine/SKILL.md

name, description, when-to-use

name	description	when-to-use
form-engine	Template engine render 8 form hợp đồng ra .docx/.xlsx giống 100% mẫu gốc. Placeholder syntax {{field}}. Dùng khi export HĐ, upload template mới, debug render lỗi format, gen mã HĐ theo RG-001.	export contract to word render template docx xuất đơn đặt hàng excel placeholder không replace upload template mới gen mã hợp đồng

Form Engine Skill

Status: Phase 2 implemented (MVP — placeholder replace cơ bản). Missing: loop {{#loop}}...{{/loop}} cho table lặp, field spec JSON, PDF convert, form builder FE.

Tech stack

Layer	Tech	Purpose
.docx render	DocumentFormat.OpenXml 3.x	Free, maintained by MS
.xlsx render	ClosedXML 0.105+	Free LGPL, dễ dùng, support formula/style
PDF convert	LibreOffice headless (chưa implement)	soffice --headless --convert-to pdf — Phase 4
.doc → .docx	Word COM (PowerShell)	Chạy offline 1 lần trên dev machine

Placeholder syntax

Template (.docx hoặc .xlsx) chứa {{fieldName}} — regex \{\{([a-zA-Z0-9_\.]+)\}\}:

Hợp đồng số: {{maHopDong}}
Bên A: {{benA_tenCongTy}}
Giá trị: {{giaTri}}

Data dictionary:

{
  "maHopDong": "FLOCK 01/HĐGK/SOL&PVL/03",
  "benA_tenCongTy": "Công ty TNHH Xây dựng Solutions",
  "giaTri": "150,000,000 VND"
}

Null value → replace bằng rỗng. Key không có trong data → giữ nguyên placeholder.

Code pointers

• src/Backend/SolutionErp.Application/Forms/Services/IFormRenderer.cs — interface
• src/Backend/SolutionErp.Infrastructure/Forms/DocxRenderer.cs — OpenXml-based
• src/Backend/SolutionErp.Infrastructure/Forms/XlsxRenderer.cs — ClosedXML-based
• src/Backend/SolutionErp.Infrastructure/Forms/FormRenderer.cs — router theo format
• src/Backend/SolutionErp.Application/Forms/FormFeatures.cs — CQRS list/get/render
• src/Backend/SolutionErp.Api/Controllers/FormsController.cs — REST endpoints
• src/Backend/SolutionErp.Infrastructure/Persistence/DbInitializer.cs — SeedContractTemplatesAsync
• fe-admin/src/pages/forms/FormsPage.tsx — UI list + render test
• src/Backend/SolutionErp.Api/wwwroot/templates/ — file templates vật lý

API endpoints

Method	Path	Purpose
GET	/api/forms/templates?type=&onlyActive=	List templates
GET	/api/forms/templates/{id}	Get single
POST	/api/forms/templates/{id}/render	Render với data dictionary → return file

Key algorithm — Placeholder split fix

Word thường split placeholder thành nhiều <w:t> runs (vì style, typo check…). DocxRenderer xử lý bằng:

foreach (var para in root.Descendants<Paragraph>()) {
    var textElements = para.Descendants<Text>().ToList();
    var combined = string.Concat(textElements.Select(t => t.Text));
    if (!combined.Contains("{{")) continue;

    var replaced = Regex.Replace(combined, @"\{\{([a-zA-Z0-9_\.]+)\}\}", match =>
        data.TryGetValue(match.Groups[1].Value, out var v) ? (v ?? "") : match.Value);

    if (replaced != combined) {
        textElements[0].Text = replaced;         // gán vào text đầu
        textElements[0].Space = ...Preserve;     // giữ space
        for (var i = 1; i < textElements.Count; i++)
            textElements[i].Text = "";            // clear phần còn lại
    }
}

Workflow thêm template mới

1. Upload file .docx / .xlsx → wwwroot/templates/{formCode}.{ext}
2. Insert row vào ContractTemplates:

   INSERT INTO ContractTemplates (FormCode, Name, ContractType, FileName, StoragePath, Format, IsActive, CreatedAt)
   VALUES ('SOL-CCM-FO-002.XX', 'Tên', 1, 'file.docx', 'templates/file.docx', 'docx', 1, GETUTCDATE());
   

3. Template tự động xuất hiện ở /forms FE

Known limitations

#	Limitation	Phase fix
1	Không support {{#loop}}...{{/loop}} cho table lặp	Phase 2 iteration 2
2	Không có field spec JSON — form builder FE phải điền JSON thủ công	Phase 2 iteration 2
3	3 file .doc (FO-002.02/03/06) chưa convert → IsActive=false	Convert offline qua Word COM
4	Không có PDF convert → preview chỉ download .docx	Phase 4
5	Không handle .docm (macro) — chỉ accept .docx / .xlsx	By design
6	Không convert format trong template (vd number → 150,000,000 VND) — BE phải format trước khi pass data	Phase 3 khi gen mã HĐ

Common pitfalls (xem gotchas.md)

• Placeholder bị split runs → đã handle trong DocxRenderer
• SpaceProcessingModeValues namespace — xem gotcha #9
• Word COM stuck — gotcha #12
• SaveAs type conversion — gotcha #11
• Template file không tồn tại → throw NotFoundException ở RenderCommandHandler

Gen mã HĐ (RG-001) — chưa implement (Phase 3)

Xem docs/forms-spec.md §RG-001. Tóm tắt format:

Loại HĐ	Format
HĐ Thầu phụ	{Project}/HĐTP/SOL&{Partner}/{Seq}
HĐ Giao khoán	{Project}/HĐGK/SOL&{Partner}/{Seq}
HĐ NCC	{Project}/NCC/SOL&{Partner}/{Seq}
HĐ Nguyên tắc	{Year}/NCC/SOL&{Partner}/{Seq}

Planned implementation: IContractCodeGenerator.GenerateAsync() với transaction SERIALIZABLE + ContractCodeSequences table để tránh race.