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:** 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:**
```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 | 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`](../../../docs/forms-spec.md). 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.