[CLAUDE] Phase2: Form Engine MVP + docs (gotchas, skill, handoff)

Backend Forms:
- Domain/Forms: ContractTemplate (FormCode, Name, ContractType, FileName, StoragePath, Format, FieldSpec JSON, IsActive) + ContractClause
- EF config voi unique FormCode + query filter IsDeleted
- DbSets + IApplicationDbContext update
- Migration AddForms (bang 14 total)
- Packages: DocumentFormat.OpenXml 3.x + ClosedXML 0.105+
- Application/Forms:
  - IFormRenderer interface + RenderResult record
  - FormFeatures.cs: List/Get/Render CQRS
  - IWebHostEnvironmentLocator (abstract IWebHostEnvironment)
- Infrastructure/Forms:
  - DocxRenderer: OpenXml-based placeholder {{field}} replace, handle split runs (gom text tat ca <w:t> trong paragraph, replace, gan lai text dau + clear rest)
  - XlsxRenderer: ClosedXML cell value replace
  - FormRenderer router theo format docx/xlsx
- Api:
  - FormsController: GET /templates (filter type, onlyActive), GET /templates/{id}, POST /templates/{id}/render (return file)
  - WebHostEnvironmentLocator impl
- DbInitializer SeedContractTemplatesAsync: seed 8 template metadata, IsActive=true chi khi file ton tai

Templates vat ly:
- Copy 5 .docx/.xlsx tu FORM/ sang wwwroot/templates/
- 3 .doc (FO-002.02/03/06) chua convert: IsActive=false (Word COM bi stuck luc test, can retry voi DisplayAlerts=0 hoac LibreOffice)
- scripts/convert-doc-to-docx.ps1 (Word COM automation)

Frontend fe-admin:
- types/forms.ts: ContractTemplate + ContractTypeLabel
- pages/forms/FormsPage.tsx: list templates + Render dialog (paste JSON data → download .docx/.xlsx)
- Route /forms them vao App.tsx

Bug fix:
- SpaceProcessingModeValues namespace: wrap EnumValue<> full path
- SaveAs2($path, 16) thay vi SaveAs([ref], [ref]) — PowerShell type issue
- Word COM stuck: kill process, skip .doc cho MVP

Docs (theo yeu cau user):
- docs/gotchas.md MOI: 17 pitfalls nhom theo tech stack / EF Core / OpenXml / JSON / dev workflow
- .claude/skills/form-engine/SKILL.md: placeholder → full spec (algorithm + code pointers + API + limitations)
- .claude/skills/permission-matrix/SKILL.md: placeholder → full spec (BE policy + FE guard + seed + pitfalls)
- docs/HANDOFF.md MOI: brief 5 phut cho session sau (run quickstart + where we are + next steps + file tree + gotchas ref)
- docs/STATUS.md: update cumulative stats + next up Phase 3
- docs/changelog/migration-todos.md: tick Phase 2 iteration 1 items + add iteration 2 list
- docs/changelog/sessions/2026-04-21-1200-phase2-form-engine.md: session log
- CLAUDE.md root: them reference den gotchas + HANDOFF

E2E verified:
- GET /api/forms/templates (onlyActive=false) → 8 templates
- POST /api/forms/templates/{FO-002.05}/render voi data dict → HTTP 200 + file .docx 482KB (Microsoft Word 2007+ OK)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/changelog/migration-todos.md

@@ -91,19 +91,34 @@
 
 ## Phase 2 — Form Engine (T5-6)
 
-- [ ] Khảo sát: OpenXml vs Aspose.Words — chọn 1 (Aspose có license phí; OpenXml free nhưng verbose)
-- [ ] Convert 3 file `.doc` → `.docx` (COM automation PowerShell hoặc LibreOffice headless)
-- [ ] Parse chi tiết field của 5 template HĐ — mỗi form thành JSON spec
-- [ ] `Domain/Entities/ContractTemplate` (Id, FormCode, Name, TemplateFile path, FieldSpec JSON)
-- [ ] `Application/Forms/Services/IFormRenderer` — input: template + data dict → output: byte[] (.docx)
-- [ ] Implement `DocxRenderer` (OpenXml-based replace placeholder)
-- [ ] Implement `XlsxRenderer` cho FO-002.07 (dùng EPPlus/ClosedXML)
-- [ ] `Api/Controllers/FormsController` — GET /templates, POST /render
-- [ ] FE user: form builder — chọn template → dynamic form → preview → export
-- [ ] FE admin: upload template mới, edit field mapping
+### MVP xong (Phase 2 iteration 1)
+
+- [x] Khảo sát: chọn **OpenXml + ClosedXML** (free, không cần license)
+- [x] `Domain/Forms/ContractTemplate` (Id, FormCode, Name, ContractType, FileName, StoragePath, Format, FieldSpec JSON, IsActive)
+- [x] `Domain/Forms/ContractClause` skeleton
+- [x] EF config + Migration `AddForms`
+- [x] `Application/Forms/Services/IFormRenderer` interface
+- [x] `Infrastructure/Forms/DocxRenderer` (OpenXml, handle placeholder split runs)
+- [x] `Infrastructure/Forms/XlsxRenderer` (ClosedXML)
+- [x] `Application/Forms/FormFeatures.cs` — List/Get/Render CQRS
+- [x] `Api/Controllers/FormsController` — GET templates, GET single, POST render
+- [x] Copy 5 .docx/.xlsx template → `wwwroot/templates/`
+- [x] Seed 8 ContractTemplate rows (5 IsActive=true, 3 chờ convert)
+- [x] FE admin: `FormsPage` — list + render dialog điền JSON + download
+- [x] E2E verified: render FO-002.05 → file .docx 482KB mở được bằng Word
+
+### Iteration 2 (optional — enhance)
+
+- [ ] Convert 3 file `.doc` → `.docx` (retry Word COM với `DisplayAlerts=0` + timeout, hoặc LibreOffice headless)
+- [ ] Parse chi tiết field của 5 template HĐ — mỗi form thành JSON `FieldSpec`
+- [ ] Support `{{#loop}}...{{/loop}}` block cho table lặp (hạng mục HĐ giao khoán, PO)
+- [ ] FE user: form builder dynamic — render từ fieldSpec thay vì điền JSON tay
+- [ ] FE admin: upload template mới qua UI (POST multipart) + edit field mapping
 - [ ] Lưu `ContractClause` (FO-002.04) dạng rich text, admin edit qua TipTap/TinyMCE
-- [ ] Import/export template (để backup)
-- [ ] Test: 1 HĐ Giao khoán filled → export .docx mở bằng Word y hệt mẫu
+- [ ] PDF convert via LibreOffice headless (`soffice --headless --convert-to pdf`)
+- [ ] Import/export template (backup/restore)
+- [ ] Format helpers: number → `150,000,000 VND`, date → `dd/MM/yyyy`
+- [ ] Content preservation test: render → diff layout với template gốc
 
 ## Phase 3 — Workflow State Machine (T7-9)