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

---
name: form-engine
description: 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.
when-to-use:
  - "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 (post Session 6 — 2026-04-30):** Tier 3 FEATURE-COMPLETE.
> ✅ Placeholder replace + split-runs handling, ✅ FieldSpec JSON, ✅ Form builder FE (admin upload), ✅ DynamicForm renderer (Form↔JSON toggle), ✅ PDF export qua LibreOffice headless, ✅ .doc/.xls auto-convert tới .docx/.xlsx.
> **Missing (low priority):** loop `{{#loop}}...{{/loop}}` cho table lặp (chưa cần — 8 form hiện không có table dynamic), Export PE phiếu PDF (Phase 9 carry over, không quan trọng).

## 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:**
```json
{
  "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:

```csharp
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`:
   ```sql
   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 | Status |
|---|---|---|
| 1 | Không support `{{#loop}}...{{/loop}}` cho table lặp | Pending (chưa cần) |
| 2 | Không handle `.docm` (macro) — chỉ accept `.docx` / `.xlsx` | By design (security) |
| 3 | BE phải format số/tiền trước khi pass data (template không format) | By design — caller responsibility |
| 4 | PE Export phiếu PDF chưa wire | Phase 9 carry over (không quan trọng) |

## 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) — DONE Phase 3 + Phase 6 PE

Đã implement: `ContractCodeGenerator` + `PurchaseEvaluationCodeGenerator` (atomic SERIALIZABLE). Detail trong skill `contract-workflow` (HĐ) + format PE `PE/{YYYY}/{A|B}/{Seq:D3}`. 17 unit test cover (Infrastructure.Tests/Services).

Xem [`docs/forms-spec.md §RG-001`](../../../docs/forms-spec.md) cho format spec từng ContractType.