[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>
2026-04-21 12:01:11 +07:00
parent 54d6c9ba52
commit 5113e4c771
37 changed files with 2379 additions and 88 deletions
--- a/.claude/skills/form-engine/SKILL.md
+++ b/.claude/skills/form-engine/SKILL.md
@ -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.
--- a/.claude/skills/permission-matrix/SKILL.md
+++ b/.claude/skills/permission-matrix/SKILL.md
@ -1,41 +1,143 @@
 ---
 name: permission-matrix
-description: Hệ thống phân quyền Role × MenuKey × CRUD. Sidebar gating, permission guard, seed default, reset password. Dùng khi debug access denied, gán role, menu không hiện.
+description: Hệ thống phân quyền Role × MenuKey × CRUD. Seed 12 menu + admin full. FE PermissionGuard + usePermission. BE AuthorizationHandler + 48 policy. Dùng khi debug access denied, gán role, menu không hiện.
 when-to-use:
  - "permission denied"
  - "access denied"
  - "menu không hiện"
  - "gán role cho user"
-  - "reset password"
  - "seed permission"
+  - "permission matrix edit"
 ---

 # Permission Matrix Skill

-> **Phase 1 deliverable.** Hiện tại skill này là PLACEHOLDER.
+> **Status:** Phase 1 đợt 2 IMPLEMENTED.

-## Context
+## Model

-Pattern copy từ **NamGroup** skill `permission-system` nhưng đơn giản hóa:
- 1 User có N Role
- 1 Role có ma trận (MenuKey, CRUD flags) — `Permission` table
- Không có per-user override (giữ đơn giản cho Phase 1)
- Menu tree flat 2 cấp, hardcode `MenuKey`
+```
+User ────< UserRoles ────< Role ────< Permissions ────< MenuItem
+                                       (RoleId, MenuKey, CRUD flags)
+```

-## Tech
+- 1 User có N Role (qua `AspNetUserRoles` rename → `UserRoles`)
+- 1 Role có N Permission (1 row per MenuKey × 4 CRUD flag)
+- Union (OR) nhiều role → user có quyền nếu **bất kỳ role nào** cho quyền đó
+- Admin role → **bypass** check (luôn pass mọi policy)

- BE: `[Authorize(Policy = "Menu.Read")]` attribute
- FE: `<PermissionGuard menuKey="Contracts" action="Update">` + `usePermission().can("Contracts", "Update")`
- Resolution: API `/api/menus/me` trả về tree + permissions đã resolved theo user's roles
+## Menu tree (seed)

-## Code pointers (sẽ có sau Phase 1)
+12 menu trong `MenuKeys.All`:

- `src/Backend/SolutionErp.Domain/Identity/Permission.cs`
- `src/Backend/SolutionErp.Application/Permissions/Queries/GetMyMenuTreeQuery.cs`
- `fe-admin/src/components/PermissionGuard.tsx`
- `fe-admin/src/hooks/usePermission.ts`
+```
+Dashboard
+Master
+  ├── Suppliers
+  ├── Projects
+  └── Departments
+Contracts
+Forms
+Reports
+System
+  ├── Users
+  ├── Roles
+  └── Permissions
+```

-## Common pitfalls (dự kiến)
+Tree hierarchy qua `ParentKey` field. Seed trong `DbInitializer.SeedMenuTreeAsync`.

- Quên refresh token sau khi admin update permission → user phải logout/login mới thấy
- MenuKey hardcode dễ typo → tập trung vào file `src/lib/menuKeys.ts` (FE) + `MenuKeys.cs` (BE const)
+## Code pointers
+
+**Backend:**
+- `Domain/Identity/MenuKeys.cs` — const class, single source of truth
+- `Domain/Identity/MenuItem.cs` — entity (Key PK, Label, ParentKey, Order, Icon)
+- `Domain/Identity/Permission.cs` — entity (RoleId, MenuKey, 4 flag)
+- `Application/Permissions/Queries/GetMyMenuTree/GetMyMenuTreeQuery.cs` — resolve per-user, union OR, filter tree
+- `Application/Permissions/PermissionFeatures.cs` — list/upsert
+- `Api/Authorization/MenuPermissionRequirement.cs` + `MenuPermissionHandler.cs` — policy check
+- `Api/Program.cs` — register 48 policy `{menu}.{action}` trong AddAuthorization
+- `Infrastructure/Persistence/DbInitializer.cs` — `SeedMenuTreeAsync` + `SeedAdminPermissionsAsync`
+- `Api/Controllers/MenusController.cs`, `RolesController.cs`, `PermissionsController.cs`
+
+**Frontend (fe-admin):**
+- `src/lib/menuKeys.ts` — const mirror, cần **đồng bộ tay** với BE
+- `src/types/menu.ts` — MenuNode type
+- `src/hooks/usePermission.ts` — `can(menuKey, action)` helper
+- `src/components/PermissionGuard.tsx` — wrap button/content
+- `src/components/Layout.tsx` — render sidebar động từ AuthContext.menu
+- `src/pages/system/PermissionsPage.tsx` — ma trận edit UI
+- `src/contexts/AuthContext.tsx` — `loadMenu()` on login + localStorage cache
+
+## BE policy usage
+
+Register trong Program.cs:
+
+```csharp
+services.AddAuthorization(opts =>
+{
+    foreach (var menu in MenuKeys.All)
+        foreach (var action in MenuKeys.Actions)
+            opts.AddPolicy($"{menu}.{action}", p =>
+                p.Requirements.Add(new MenuPermissionRequirement(menu, action)));
+});
+services.AddScoped<IAuthorizationHandler, MenuPermissionHandler>();
+```
+
+Apply ở controller:
+
+```csharp
+[HttpPut("{id:guid}")]
+[Authorize(Policy = "Contracts.Update")]
+public async Task<IActionResult> Update(...) { }
+```
+
+## FE guard usage
+
+```tsx
+// Hook
+const { can } = usePermission()
+if (!can('Contracts', 'Update')) return null
+
+// Component wrap
+<PermissionGuard menuKey="Contracts" action="Update">
+  <Button>Sửa</Button>
+</PermissionGuard>
+
+// Route guard
+<Route
+  path="/system/permissions"
+  element={
+    <PermissionGuard menuKey="Permissions" action="Read" fallback={<Forbidden />}>
+      <PermissionsPage />
+    </PermissionGuard>
+  }
+/>
+```
+
+## Workflow — gán quyền cho role mới
+
+1. Admin login → `/system/permissions`
+2. Chọn role (vd "CostControl")
+3. Tick checkbox trên matrix grid — mỗi lần tick tự động PUT `/api/permissions` upsert
+4. User thuộc role đó logout/login lại → thấy permission mới (menu refresh từ `/api/menus/me`)
+
+## Guard rules đã implement
+
+- **Admin bypass:** role `Admin` luôn pass mọi policy (kể cả chưa seed row Permission)
+- **Not user active:** `User.IsActive=false` → AuthorizationHandler return fail
+- **Self-demote protection:** admin đang edit không thể giảm quyền role Admin (check trong `UpsertPermissionCommandHandler`)
+
+## Common pitfalls
+
+- **Quên refresh menu sau update permission** → user thấy menu cũ. Giải pháp: logout/login, hoặc Phase 3 thêm SignalR push.
+- **MenuKey typo** — TS không check vì menu.key là string. Luôn dùng `MenuKeys.Contracts` const, không hardcode `"Contracts"`.
+- **FE cache menu trong localStorage** → sau user được assign role mới, FE thấy menu cũ. Login lại fix.
+- **Hai role conflict** (1 cho, 1 cấm): union OR → có ít nhất 1 role cho là được.
+- **403 ở API nhưng FE không hide button** → FE guard chỉ UX, BE phải là source of truth. Phải apply `[Authorize(Policy = "X.Y")]` ở controller.
+
+## Phase tiếp theo
+
+- **Phase 3:** SignalR notify khi permission đổi → FE tự refetch `/api/menus/me`
+- **Phase 4:** Per-user override (ngoài role) — thêm bảng `UserPermissionOverrides`
+- **Phase 4:** Invalidate JWT khi role đổi (rare event, nhưng secure)