vietreport-admin/solution-erp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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>
This commit is contained in:
pqhuy1987
2026-04-21 12:01:11 +07:00
parent 54d6c9ba52
commit 5113e4c771
37 changed files with 2379 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files

130
.claude/skills/form-engine/SKILL.md
View File

@ -1,34 +1,130 @@
---
name: form-engine
description: Template engine render 8 form hợp đồng ra .docx/.xlsx giống 100% mẫu gốc. Gen mã HĐ theo RG-001. Dùng khi export HĐ, upload template mới, debug render lỗi format.
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"
- "gen mã hợp đồng"
- "placeholder không replace"
- "upload template mới"
- "gen mã hợp đồng"
---
# Form Engine Skill
> **Phase 2 deliverable.** Hiện tại skill này là PLACEHOLDER.
> **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.
## Context
## Tech stack
Xem đầy đủ ở [`docs/forms-spec.md`](../../../docs/forms-spec.md):
- 8 form (6 .docx/.doc + 1 .xlsx + 1 .docx quy định)
- Mã HĐ format theo SOL-CCM-RG-001: `{Project}/{Type}/SOL&{Partner}/{Seq}` và biến thể
- 3 file `.doc` cần convert qua Word COM / LibreOffice headless trước khi parse
| 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 |
## Tech stack dự kiến
## Placeholder syntax
- **.docx render:** DocumentFormat.OpenXml (free, verbose) hoặc Aspose.Words (phí, dễ)
- **.xlsx render:** EPPlus (free non-commercial) hoặc ClosedXML (free)
- **PDF preview:** wkhtmltopdf hoặc LibreOffice `--convert-to pdf`
Template (.docx hoặc .xlsx) chứa `{{fieldName}}` — regex `\{\{([a-zA-Z0-9_\.]+)\}\}`:
## Code pointers (sẽ có sau Phase 2)
```
Hợp đồng số: {{maHopDong}}
Bên A: {{benA_tenCongTy}}
Giá trị: {{giaTri}}
```
- `src/Backend/SolutionErp.Application/Forms/Services/IFormRenderer.cs`
- `src/Backend/SolutionErp.Infrastructure/Forms/DocxRenderer.cs`
- `src/Backend/SolutionErp.Infrastructure/Forms/XlsxRenderer.cs`
- `src/Backend/SolutionErp.Infrastructure/Services/ContractCodeGenerator.cs`
**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.