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

86
docs/STATUS.md
View File

@ -2,73 +2,85 @@
> **Update rule:** trước khi bắt đầu 1 task → ghi row vào `🔥 In Progress`. Xong → chuyển sang `✅ Recently Done`.
**Last updated:** 2026-04-21 11:30
**Last updated:** 2026-04-21 12:00
## 📍 Phase hiện tại: **Phase 1 — Alpha Core (đợt 2 xong)** — sẵn sàng Phase 2 Form Engine
## 📍 Phase hiện tại: **Phase 2 Form Engine (MVP xong)** — sẵn sàng Phase 3 Workflow
## 🔥 In Progress
_(không có — Phase 1 đợt 2 hoàn tất)_
_(không có — tạm nghỉ chờ user approve move on)_
## ✅ Recently Done (newest on top)
| Ngày | Ai | Task | Commit |
|---|---|---|---|
| 2026-04-21 | Claude | **Phase 1 đợt 2 HOÀN TẤT** — BE: Supplier/Project/Department CRUD + Permission Matrix (MenuItem/Permission + Authorization handler) + 2 migration. FE: DataTable/Dialog generic, usePermission, PermissionGuard, 3 trang CRUD admin, Permission Matrix page, Layout menu động | (sắp commit) |
| 2026-04-21 | Claude | **Phase 2 Form Engine MVP** — BE: ContractTemplate/ContractClause entities + OpenXml + ClosedXML renderer (placeholder `{{field}}`) + FormsController + seed 8 template. FE: FormsPage list + render dialog. `/api/forms/templates/{id}/render` trả file .docx/.xlsx 482KB OK | (sắp commit) |
| 2026-04-21 | Claude | **Docs:** `gotchas.md` (17 pitfalls) + update 2 skill (form-engine, permission-matrix) từ placeholder → full spec | (sắp commit) |
| 2026-04-21 | Claude | **Phase 1 đợt 2** — BE CRUD Supplier/Project/Department + Permission Matrix + FE 4 page | `54d6c9b` |
| 2026-04-21 | Claude | **Docs addition** — `database-guide.md` + `flows/` 6 doc | `49a5f57` |
| 2026-04-21 | Claude | **Phase 1 foundation HOÀN TẤT** — BE Clean Arch + Identity + JWT + FE 2 app + Tailwind 4 + login E2E | `702411f` |
| 2026-04-21 | Claude | **Phase 0 HOÀN TẤT** — scaffold + parse FORM/QUY_TRINH + docs + skills + git init | `25dad7f` |
| 2026-04-21 | Claude | **Phase 1 foundation** — BE Clean Arch + Identity + JWT + FE 2 app + login E2E | `702411f` |
| 2026-04-21 | Claude | **Phase 0** — scaffold + parse FORM/QUY_TRINH + docs + git init | `25dad7f` |
Session logs:
- [`changelog/sessions/2026-04-21-1045-phase0-scaffold.md`](changelog/sessions/2026-04-21-1045-phase0-scaffold.md)
- [`changelog/sessions/2026-04-21-1100-phase1-foundation.md`](changelog/sessions/2026-04-21-1100-phase1-foundation.md)
- [`changelog/sessions/2026-04-21-1130-phase1-cruds-permission.md`](changelog/sessions/2026-04-21-1130-phase1-cruds-permission.md)
- [`changelog/sessions/2026-04-21-1200-phase2-form-engine.md`](changelog/sessions/2026-04-21-1200-phase2-form-engine.md)
## 🎯 Next up — Phase 2 Form Engine (có thể bắt ngay)
Gotchas library: [`gotchas.md`](gotchas.md) — 17 pitfalls đã gặp + cách xử lý.
- [ ] Convert 3 file `.doc` (FO-002.02/03/06) → `.docx` qua PowerShell COM hoặc LibreOffice headless
- [ ] Parse chi tiết field specs cho 5 template HĐ → JSON spec
- [ ] Add NuGet: DocumentFormat.OpenXml, ClosedXML
- [ ] `Domain/Entities/ContractTemplate`, `ContractClause` + EF config
- [ ] `Application/Forms/Services/IFormRenderer` + `DocxRenderer` + `XlsxRenderer`
- [ ] `Api/Controllers/FormsController` (list template, get spec, render preview, render final)
- [ ] FE: form builder dynamic render từ fieldSpec
- [ ] FE admin: upload template + manage ContractClause (rich text editor)
- [ ] Test: FO-002.05 Giao khoán render → docx khớp mẫu 100%
## 🎯 Next up
Chi tiết: [`docs/flows/form-render-flow.md`](flows/form-render-flow.md) + [`docs/changelog/migration-todos.md`](changelog/migration-todos.md) section Phase 2.
### Phase 2 iteration 2 (optional — enhance)
## 🔄 Còn có thể làm parallel (optional, không block Phase 2)
- [ ] Convert 3 file `.doc` (retry Word COM với timeout, hoặc LibreOffice headless)
- [ ] Field spec JSON mỗi template + dynamic form builder FE
- [ ] Support `{{#loop}}...{{/loop}}` cho table lặp
- [ ] PDF convert via LibreOffice
- [ ] Admin upload template UI (POST multipart)
- [ ] FE Users management (tạo user + gán role) — cần để test permission với role khác Admin
- [ ] FE Roles CRUD (tạo custom role mới)
- [ ] Contract entity skeleton (không state machine, chỉ CRUD draft)
- [ ] E2E test permission: tạo user role Drafter-only → verify không thấy menu System/Admin
### Phase 3 — Workflow (sắp tới, item lớn)
## 📊 Thông số sau Phase 1 đợt 2
Xem [`docs/flows/contract-approval-flow.md`](flows/contract-approval-flow.md) + [`docs/workflow-contract.md`](workflow-contract.md).
- **Backend LOC:** ~1500 (Domain 150 + Application 800 + Infrastructure 350 + Api 200)
- **Migrations:** Init + AddMasterData + AddPermissions
- **DB tables:** 7 Identity + 3 Master (Suppliers/Projects/Departments) + 2 Permission (MenuItems/Permissions)
- **API endpoints:** 20+ (Auth 4 + Suppliers 5 + Projects 5 + Departments 5 + Menus 2 + Roles 1 + Permissions 2)
- **Frontend routes:** 5 (Dashboard + 3 CRUD + Permission Matrix)
- **FE LOC:** ~1700 (fe-admin; fe-user vẫn minimal)
Summary:
- [ ] Entity: Contract + ContractApproval + ContractComment + ContractAttachment
- [ ] `IContractWorkflowService` với state guard + role guard
- [ ] `IContractCodeGenerator` RG-001 + transaction SERIALIZABLE
- [ ] `SlaExpiryJob` BackgroundService
- [ ] Email + in-app notification service
- [ ] API `POST /api/contracts/{id}/transitions`
- [ ] FE Inbox + Contract detail page + timeline UI
### Optional (không block Phase 3)
- [ ] FE Users management + Roles CRUD (cho test permission với non-admin role)
- [ ] fe-user sync menu động (đang hardcode)
## 📊 Thông số cumulative
| | Phase 0 | +Phase 1f | +Phase 1.2 | +Docs | +Phase 2 MVP |
|---|---:|---:|---:|---:|---:|
| BE LOC | 0 | ~400 | ~1500 | — | ~1900 |
| DB tables | 0 | 7 | 12 | — | 14 |
| API endpoints | 0 | 4 | ~20 | — | ~23 |
| Migrations | 0 | 1 | 3 | — | 4 |
| FE pages | 0 | 2 | 6 | — | 7 |
| Docs files | 10 | 13 | 14 | 21 | 24 |
| Commits | 1 | 2 | 3 | — | 5 (sắp) |
## 🚨 Blockers / risks
- ⏳ **Gitea remote** — URL chờ user cấp
- ⚠️ **fe-user** chưa được update với menu động — Phase 2 sẽ sync
- ⚠️ **Users CRUD** chưa có UI → khó test permission với non-admin role thật
- ⚠️ **3 file `.doc`** Phase 2 cần convert COM
- ⏳ **Gitea remote URL** — user sẽ cấp sau
- ⚠️ **3 file .doc** chưa convert (IsActive=false) — retry Word COM với timeout/`DisplayAlerts=0` hoặc LibreOffice
- ⚠️ **fe-user** chưa đồng bộ menu động (chỉ fe-admin đã chuyển) — quick fix lúc Phase 3
## Credentials mặc định
## Credentials + URLs
```
Email: admin@solutionerp.local
Password: Admin@123456
admin@solutionerp.local / Admin@123456
```
URLs dev:
- API: http://localhost:5443 — Swagger `/swagger`
- Admin FE: http://localhost:8082
- User FE: http://localhost:8080